Перейти до вмісту

Для розробників

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 маршрутах, без банківської картки.