Dla programistów
API i webhooki
Twój sklep internetowy lub inny system wysyła zamówienia do Routehive jako przystanki i otrzymuje status dostawy przez webhook lub zapytanie. Dostępne w pakietach Pro i Flota.
Uwierzytelnianie
Właściciel lub administrator tworzy klucz API na stronie API i webhooki w aplikacji. Klucz jest pokazywany tylko raz. Wysyłaj go w nagłówku każdego żądania jako token Bearer. Kluczem tylko do odczytu nie można dodawać przystanków.
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"]
}'Endpointy
GET /api/v1/routes?date=YYYY-MM-DD- Trasy danego dnia (domyślnie dziś, w strefie czasowej firmy).
GET /api/v1/routes/{id}- Trasa z przystankami, w kolejności.
POST /api/v1/stops- Nowy przystanek, na przykład zamówienie ze sklepu.
GET /api/v1/stops/{id}- Status przystanku: dostarczony, nieudany, pobrana kwota, zdjęcie i podpis.
Dodawanie przystanku
Bez trasy przystanek trafia do trasy Przychodzące danego dnia, skąd dyspozytor go przydziela. Jeśli ponownie wyślesz ten sam numer zamówienia (reference) na ten sam dzień, nowy przystanek nie powstanie: otrzymasz istniejący. Ponowne wysłanie jest bezpieczne.
Pola
address- Adres (wymagany). Ze współrzędnymi wyszukiwanie adresu jest pomijane.
name- Nazwa odbiorcy lub firmy.
phone, email- Telefon i e-mail do powiadomień.
reference- Twój numer zamówienia: po nim rozpoznasz przystanek w webhooku, a on zapobiega duplikatom.
cod_amount, payment_required- Pobranie w najmniejszej jednostce waluty (forint: całe forinty, euro: centy).
date- Dzień trasy Przychodzące (RRRR-MM-DD). Domyślnie dziś.
route_id- Konkretna trasa zamiast Przychodzących, jeśli można ją jeszcze rozszerzyć.
packages- Kody kreskowe paczek: kierowca skanuje je przed dostawą.
require_photo, require_signature- Obowiązkowe zdjęcie lub podpis przy dostawie.
Webhooki
Adres webhooka ustawiasz na tej samej stronie (tylko https) i wybierasz zdarzenia. Routehive wysyła JSON metodą POST przy każdym zdarzeniu; treść jest taka sama jak odpowiedź o statusie przystanku.
stop.delivered- Przystanek dostarczony (z pobraną kwotą i informacją o zdjęciu i podpisie).
stop.failed- Dostawa nieudana (z notatką kierowcy).
route.dispatched- Trasa wydana kierowcy.
route.completed- Trasa zakończona.
{
"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
}
}Weryfikacja podpisu
Każde żądanie ma nagłówek X-Routehive-Signature: t=znacznik czasu,v1=podpis. Podpis to HMAC-SHA256 ze znacznika czasu, kropki i surowej treści, z sekretem webhooka. Jeśli się nie zgadza, odrzuć żądanie.
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"));
}Każda odpowiedź 2xx potwierdza odbiór. Przy błędach ponawiamy coraz rzadziej (1 minuta, 5 minut, 30 minut, 2 godziny, 12 godzin, 24 godziny). Po 50 błędach z rzędu webhook zostaje wyłączony, a właściciel dostaje e-mail.
Błędy i limity
Błędy wyglądają tak: {"error": {"code": …, "message": …}}. Kod jest po angielsku, komunikat w języku firmy. Każdy klucz może wysłać 120 żądań na minutę; powyżej dostaniesz 429.
Już jutro rano możecie tak planować trasy
Zarejestrujcie się, dodajcie kierowców, wczytajcie adresy. Za darmo do 15 punktów łącznie, w 2 trasach, bez karty płatniczej.