Перейти к содержимому

Для разработчиков

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
Телефон и 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.

API и вебхуки

Планируйте завтрашние утренние маршруты так

Зарегистрируйтесь, добавьте водителей, загрузите адреса. Бесплатно для 15 точек всего, в 2 маршрутах, без кредитной карты.