Pre vývojárov
API a webhooky
Váš e-shop alebo iný systém posiela objednávky do Routehive ako zastávky a stav doručenia dostáva späť cez webhook alebo dopyt. Dostupné v balíkoch Pro a Flotila.
Overenie
Kľúč API vytvorí vlastník alebo admin na stránke API a webhooky v aplikácii. Kľúč sa zobrazí len raz. Posielajte ho v hlavičke každej požiadavky ako token Bearer. S kľúčom len na čítanie nemožno pridávať zastávky.
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 jedného dňa (predvolene dnes, v časovom pásme firmy).
GET /api/v1/routes/{id}- Trasa so zastávkami v poradí.
POST /api/v1/stops- Nová zastávka, napríklad objednávka z e-shopu.
GET /api/v1/stops/{id}- Stav zastávky: doručená, neúspešná, vybraná suma, fotka a podpis.
Pridanie zastávky
Bez trasy sa zastávka dostane do trasy Prichádzajúce daného dňa, odkiaľ ju dispečer pridelí. Ak znova pošlete to isté číslo objednávky (reference) na ten istý deň, nová zastávka nevznikne: dostanete existujúcu. Opakované odoslanie je bezpečné.
Polia
address- Adresa (povinná). So súradnicami sa vyhľadanie adresy vynechá.
name- Meno príjemcu alebo názov firmy.
phone, email- Telefón a e-mail pre upozornenia.
reference- Vaše číslo objednávky: podľa neho spoznáte zastávku vo webhooku a bráni duplicitám.
cod_amount, payment_required- Dobierka v najmenšej jednotke meny (forint: celé forinty, euro: centy).
date- Deň trasy Prichádzajúce (RRRR-MM-DD). Predvolene dnes.
route_id- Konkrétna trasa namiesto Prichádzajúcich, ak sa ešte dá rozšíriť.
packages- Čiarové kódy balíkov: vodič ich pred doručením naskenuje.
require_photo, require_signature- Povinná fotka alebo podpis pri doručení.
Webhooky
Adresu webhooku nastavíte na tej istej stránke (len https) a vyberiete udalosti. Routehive pošle pri každej udalosti JSON cez POST; obsah je rovnaký ako odpoveď o stave zastávky.
stop.delivered- Zastávka bola doručená (s vybranou sumou a údajom o fotke a podpise).
stop.failed- Doručenie zlyhalo (s poznámkou vodiča).
route.dispatched- Trasa bola vydaná vodičovi.
route.completed- Trasa bola dokončená.
{
"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
}
}Overenie podpisu
Každá požiadavka má hlavičku X-Routehive-Signature: t=časová pečiatka,v1=podpis. Podpis je HMAC-SHA256 z časovej pečiatky, bodky a surového tela s tajomstvom webhooku. Ak nesedí, požiadavku zahoďte.
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"));
}Akákoľvek odpoveď 2xx potvrdí prijatie. Pri chybách skúšame znova čoraz zriedkavejšie (1 minúta, 5 minút, 30 minút, 2 hodiny, 12 hodín, 24 hodín). Po 50 chybách za sebou sa webhook vypne a vlastník dostane e-mail.
Chyby a limity
Chyby vyzerajú takto: {"error": {"code": …, "message": …}}. Kód je po anglicky, správa v jazyku vašej firmy. Každý kľúč môže poslať 120 požiadaviek za minútu; nad tento limit príde 429.
Už zajtra ráno môžete plánovať takto
Zaregistrujte sa, pridajte vodičov, nahrajte adresy. Zadarmo spolu do 15 zastávok v 2 trasách, bez platobnej karty.