Fejlesztőknek
API és webhookok
A webshopod vagy más rendszered címként küldi a rendeléseket a Routehive-ba, a kézbesítés állapotát pedig webhookkal vagy lekérdezéssel kapja vissza. A Pro és a Flotta csomagban érhető el.
Hitelesítés
API-kulcsot a tulajdonos vagy az admin hoz létre az app API és webhookok oldalán. A kulcs csak egyszer látszik. Minden kérés fejlécében küldd, Bearer tokenként. A csak olvasásra szóló kulccsal cím nem vehető fel.
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"]
}'Végpontok
GET /api/v1/routes?date=YYYY-MM-DD- Egy nap körei (alapból ma, a cég időzónájában).
GET /api/v1/routes/{id}- Egy kör a megállóival, sorrendben.
POST /api/v1/stops- Új cím, például egy webshop-rendelés.
GET /api/v1/stops/{id}- Egy cím állapota: kézbesítve, sikertelen, beszedett összeg, fotó és aláírás.
Cím felvétele
Ha nem adsz meg kört, a cím a nap Beérkező körébe kerül, onnan a diszpécser osztja ki. Ha ugyanazt a rendelésszámot (reference) újra elküldöd ugyanarra a napra, nem lesz belőle új cím: a meglévőt kapod vissza. Így az újraküldés biztonságos.
Mezők
address- A cím (kötelező). Koordinátával a címkeresés kimarad.
name- A címzett neve vagy cégneve.
phone, email- Telefonszám és e-mail cím az értesítésekhez.
reference- A rendelésszámod: ezzel ismered fel a webhookban, és ez védi ki a duplázást.
cod_amount, payment_required- Utánvét a pénznem legkisebb egységében (forintban egész forint, euróban cent).
date- A Beérkező kör napja (ÉÉÉÉ-HH-NN). Alapból ma.
route_id- Megadott kör a Beérkező helyett, ha még bővíthető.
packages- Csomagkódok: a sofőr kézbesítés előtt beolvassa őket.
require_photo, require_signature- Kötelező fotó vagy aláírás a kézbesítéshez.
Webhookok
A webhook címét ugyanazon az oldalon adod meg, csak https címet. Kiválasztod, mely eseményekről kérsz értesítést. A Routehive minden eseményről JSON-t küld POST kéréssel, a tartalom ugyanaz, mint a cím lekérdezésének válasza.
stop.delivered- Egy cím kézbesítve (beszedett összeggel, fotó és aláírás jelzéssel).
stop.failed- Egy kézbesítés sikertelen (a sofőr megjegyzésével).
route.dispatched- Egy kör kiadva a sofőrnek.
route.completed- Egy kör lezárult.
{
"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
}
}Az aláírás ellenőrzése
Minden kérés X-Routehive-Signature fejlécet kap: t=időbélyeg,v1=aláírás. Az aláírás a HMAC-SHA256 kód a webhook titkával, ezen a szövegen: az időbélyeg, egy pont, majd a nyers törzs. Ha nem egyezik, dobd el a kérést.
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"));
}Bármely 2xx válasz nyugtázza a küldést. Hibánál egyre ritkábban próbáljuk újra (1 perc, 5 perc, 30 perc, 2 óra, 12 óra, 24 óra). 50 egymás utáni hiba után a webhookot kikapcsoljuk, és levelet küldünk a tulajdonosnak.
Hibák és korlátok
Hibánál a válasz: {"error": {"code": …, "message": …}}. A kód angol, a szöveg a céged nyelvén. Kulcsonként percenként 120 kérés fér bele, felette 429 jön.
Holnap reggel már így tervezhetsz
Regisztrálj, vedd fel a sofőröket, töltsd be a címeket. Összesen 15 megállóig, 2 körben ingyenes, bankkártya nélkül.