Kūrėjams
API ir „webhook“
Jūsų el. parduotuvė ar kita sistema siunčia užsakymus į Routehive kaip sustojimus ir gauna pristatymo būseną per „webhook“ arba užklausą. Prieinama „Pro“ ir „Fleet“ planuose.
Autentifikavimas
API raktą sukuria savininkas arba administratorius programos puslapyje API ir „webhook“. Raktas rodomas tik vieną kartą. Siųskite jį kiekvienos užklausos antraštėje kaip „Bearer“ žetoną. Su tik skaitymo raktu sustojimų pridėti negalima.
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"]
}'Galiniai taškai
GET /api/v1/routes?date=YYYY-MM-DD- Vienos dienos maršrutai (numatytai šiandien, įmonės laiko juostoje).
GET /api/v1/routes/{id}- Maršrutas su sustojimais iš eilės.
POST /api/v1/stops- Naujas sustojimas, pavyzdžiui, el. parduotuvės užsakymas.
GET /api/v1/stops/{id}- Sustojimo būsena: pristatyta, nepavyko, surinkta suma, nuotrauka ir parašas.
Sustojimo pridėjimas
Be maršruto sustojimas patenka į tos dienos maršrutą „Gaunami“, iš kurio jį paskirsto dispečeris. Jei tą patį užsakymo numerį (reference) tai pačiai dienai išsiųsite dar kartą, naujas sustojimas nesukuriamas: gausite esamą. Pakartotinis siuntimas saugus.
Laukai
address- Adresas (privaloma). Su koordinatėmis adreso paieška praleidžiama.
name- Gavėjo ar įmonės pavadinimas.
phone, email- Telefonas ir el. paštas pranešimams.
reference- Jūsų užsakymo numeris: pagal jį atpažinsite sustojimą „webhook“ pranešime, jis neleidžia dubliuotis.
cod_amount, payment_required- Išperkamoji suma mažiausiu valiutos vienetu (forintas: sveiki forintai, euras: centai).
date- Maršruto „Gaunami“ diena (MMMM-MM-DD). Numatytai šiandien.
route_id- Konkretus maršrutas vietoj „Gaunami“, jei jį dar galima papildyti.
packages- Siuntinių brūkšniniai kodai: vairuotojas juos nuskenuoja prieš pristatymą.
require_photo, require_signature- Privaloma nuotrauka arba parašas pristatant.
„Webhook“
„Webhook“ adresą nustatote tame pačiame puslapyje (tik https) ir pasirenkate įvykius. Routehive apie kiekvieną įvykį siunčia JSON POST metodu; turinys toks pat kaip sustojimo būsenos atsakymas.
stop.delivered- Sustojimas pristatytas (su surinkta suma ir nuotraukos bei parašo žymomis).
stop.failed- Pristatymas nepavyko (su vairuotojo pastaba).
route.dispatched- Maršrutas išduotas vairuotojui.
route.completed- Maršrutas baigtas.
{
"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
}
}Parašo tikrinimas
Kiekviena užklausa turi antraštę X-Routehive-Signature: t=laiko žyma,v1=parašas. Parašas yra HMAC-SHA256 iš laiko žymos, taško ir neapdoroto turinio su „webhook“ paslaptimi. Jei nesutampa, atmeskite užklausą.
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"));
}Bet koks 2xx atsakymas patvirtina gavimą. Klaidų atveju bandome vis rečiau (1 minutė, 5 minutės, 30 minučių, 2 valandos, 12 valandų, 24 valandos). Po 50 klaidų iš eilės „webhook“ išjungiamas, o savininkas gauna el. laišką.
Klaidos ir ribos
Klaidos atrodo taip: {"error": {"code": …, "message": …}}. Kodas angliškas, pranešimas jūsų įmonės kalba. Kiekvienas raktas gali siųsti 120 užklausų per minutę; virš to gausite 429.
Taip planuokite rytojaus ryto maršrutus
Užsiregistruokite, pridėkite vairuotojus, įkelkite adresus. Nemokamai iš viso 15 sustojimų 2 maršrutuose, nereikia kreditinės kortelės.