За разработчици
API и уебхукове
Вашият онлайн магазин или друга система изпраща поръчките в Routehive като спирки и получава статуса на доставката чрез уебхук или заявка. Наличен в пакетите Pro и Автопарк.
Удостоверяване
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.
Планирайте така утрешните сутрешни маршрути
Регистрирайте се, добавете шофьорите си, заредете адресите. Безплатно за общо 15 спирки в 2 маршрута, без кредитна карта.