Към съдържанието

За разработчици

API и уебхукове

Вашият онлайн магазин или друга система изпраща поръчките в Routehive като спирки и получава статуса на доставката чрез уебхук или заявка. Наличен в пакетите Pro и Автопарк.

Машинночетимо описание (OpenAPI)

Удостоверяване

API ключът се създава от собственика или администратор на страницата API и уебхукове в приложението. Ключът се показва само веднъж. Изпращайте го в заглавката на всяка заявка като Bearer токен. С ключ само за четене не могат да се добавят спирки.

curl -X POST https://routehive.eu/api/v1/stops \
  -H "Authorization: Bearer rh_..." \
  -H "Content-Type: application/json" \
  -d '{
    "address": "Budapest, Andrássy út 1.",
    "name": "Example Ltd.",
    "phone": "+36 30 123 4567",
    "reference": "WS-1001",
    "cod_amount": 12500,
    "packages": ["PKG-1001"]
  }'

Крайни точки

GET /api/v1/routes?date=YYYY-MM-DD
Маршрутите за един ден (по подразбиране днес, в часовата зона на фирмата).
GET /api/v1/routes/{id}
Маршрут със спирките по ред.
POST /api/v1/stops
Нова спирка, например поръчка от онлайн магазин.
GET /api/v1/stops/{id}
Статус на спирка: доставена, неуспешна, събрана сума, снимка и подпис.

Добавяне на спирка

Без маршрут спирката отива в маршрута „Входящи“ за деня, откъдето диспечерът я разпределя. Ако изпратите отново същия номер на поръчка (reference) за същия ден, нова спирка не се създава: получавате съществуващата. Повторното изпращане е безопасно.

Полета

address
Адресът (задължително). С координати търсенето на адреса се пропуска.
name
Име на получателя или фирмата.
phone, email
Телефон и имейл за известия.
reference
Номерът на поръчката ви: по него разпознавате спирката в уебхука и той предотвратява дублиране.
cod_amount, payment_required
Наложен платеж в най-малката единица на валутата (форинт: цели форинти, евро: центове).
date
Ден на маршрута „Входящи“ (ГГГГ-ММ-ДД). По подразбиране днес.
route_id
Конкретен маршрут вместо „Входящи“, ако още може да се допълва.
packages
Баркодове на пратките: шофьорът ги сканира преди доставката.
require_photo, require_signature
Задължителна снимка или подпис при доставката.

Уебхукове

Адресът на уебхука се задава на същата страница (само https), там избирате и събитията. Routehive изпраща JSON чрез POST за всяко събитие; съдържанието е същото като отговора за статуса на спирка.

stop.delivered
Спирка е доставена (със събраната сума и отметки за снимка и подпис).
stop.failed
Доставка е неуспешна (с бележката на шофьора).
route.dispatched
Маршрут е издаден на шофьора.
route.completed
Маршрут е завършен.
{
  "event": "stop.delivered",
  "event_id": "stop_..._delivered_20261120143005123",
  "created_at": "2026-11-20T14:30:05Z",
  "data": {
    "id": "...",
    "route_id": "...",
    "reference": "WS-1001",
    "status": "delivered",
    "delivered_at": "2026-11-20T14:30:04Z",
    "note": null,
    "payment_required": true,
    "paid": true,
    "cod_amount": 12500,
    "collected_amount": 12500,
    "has_photo": true,
    "has_signature": false
  }
}

Проверка на подписа

Всяка заявка има заглавка X-Routehive-Signature: t=времеви печат,v1=подпис. Подписът е HMAC-SHA256 от времевия печат, точка и суровото тяло с тайната на уебхука. Ако не съвпада, отхвърлете заявката.

import { createHmac, timingSafeEqual } from "node:crypto";

// header: X-Routehive-Signature, body: the raw request body (string)
function verify(header, body, secret) {
  const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const expected = createHmac("sha256", secret).update(`${t}.${body}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
  return fresh && timingSafeEqual(Buffer.from(v1, "hex"), Buffer.from(expected, "hex"));
}

Всеки отговор 2xx потвърждава получаването. При грешки опитваме все по-рядко (1 минута, 5 минути, 30 минути, 2 часа, 12 часа, 24 часа). След 50 поредни грешки уебхукът се изключва и собственикът получава имейл.

Грешки и ограничения

Грешките изглеждат така: {"error": {"code": …, "message": …}}. Кодът е на английски, съобщението на езика на фирмата ви. Всеки ключ може да прави 120 заявки в минута; над това идва 429.

API и уебхукове

Планирайте така утрешните сутрешни маршрути

Регистрирайте се, добавете шофьорите си, заредете адресите. Безплатно за общо 15 спирки в 2 маршрута, без кредитна карта.