Для разработчиков
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- Телефон и e-mail для уведомлений.
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 маршрутах, без кредитной карты.