Voor ontwikkelaars
API en webhooks
Uw webshop of een ander systeem stuurt bestellingen als stops naar Routehive en krijgt de bezorgstatus terug via webhook of opvraging. Beschikbaar in de pakketten Pro en Vloot.
Authenticatie
De eigenaar of een beheerder maakt de API-sleutel aan op de pagina API en webhooks in de app. De sleutel wordt maar één keer getoond. Stuur hem in de header van elk verzoek als Bearer-token. Met een alleen-lezen-sleutel kunt u geen stops toevoegen.
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"]
}'Endpoints
GET /api/v1/routes?date=YYYY-MM-DD- De ritten van een dag (standaard vandaag, in de tijdzone van het bedrijf).
GET /api/v1/routes/{id}- Een rit met zijn stops, op volgorde.
POST /api/v1/stops- Een nieuwe stop, bijvoorbeeld een webshopbestelling.
GET /api/v1/stops/{id}- Status van een stop: bezorgd, mislukt, geïnd bedrag, foto en handtekening.
Een stop toevoegen
Zonder rit gaat de stop naar de rit Binnenkomend van die dag, waar de planner hem toewijst. Stuurt u hetzelfde bestelnummer (reference) voor dezelfde dag opnieuw, dan ontstaat er geen nieuwe stop: u krijgt de bestaande terug. Opnieuw sturen is dus veilig.
Velden
address- Het adres (verplicht). Met coördinaten wordt het opzoeken van het adres overgeslagen.
name- Naam van de ontvanger of het bedrijf.
phone, email- Telefoon en e-mail voor meldingen.
reference- Uw bestelnummer: daaraan herkent u de stop in de webhook, en het voorkomt dubbele stops.
cod_amount, payment_required- Rembours in de kleinste eenheid van de valuta (forint: hele forint, euro: centen).
date- Dag van de rit Binnenkomend (JJJJ-MM-DD). Standaard vandaag.
route_id- Een bepaalde rit in plaats van Binnenkomend, als die nog uitgebreid kan worden.
packages- Barcodes van pakketten: de chauffeur scant ze vóór de bezorging.
require_photo, require_signature- Verplichte foto of handtekening bij de bezorging.
Webhooks
De webhook-URL stelt u in op dezelfde pagina (alleen https), waar u ook de gebeurtenissen kiest. Routehive stuurt bij elke gebeurtenis een JSON via POST; de inhoud is gelijk aan het antwoord op de statusopvraging van een stop.
stop.delivered- Een stop is bezorgd (met geïnd bedrag en aanduiding van foto en handtekening).
stop.failed- Een bezorging is mislukt (met de notitie van de chauffeur).
route.dispatched- Een rit is aan de chauffeur uitgegeven.
route.completed- Een rit is afgerond.
{
"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
}
}De handtekening controleren
Elk verzoek heeft de header X-Routehive-Signature: t=tijdstempel,v1=handtekening. De handtekening is de HMAC-SHA256 van tijdstempel, een punt en de ruwe body, met het webhookgeheim. Komt die niet overeen, weiger het verzoek dan.
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"));
}Elk 2xx-antwoord bevestigt de ontvangst. Bij fouten proberen we het steeds minder vaak opnieuw (1 minuut, 5 minuten, 30 minuten, 2 uur, 12 uur, 24 uur). Na 50 fouten op rij wordt de webhook uitgeschakeld en krijgt de eigenaar een e-mail.
Fouten en limieten
Fouten zien er zo uit: {"error": {"code": …, "message": …}}. De code is Engels, de melding in de taal van uw bedrijf. Elke sleutel kan 120 verzoeken per minuut doen; daarboven krijgt u 429.
Plan de routes van morgenochtend zo
Meld u aan, voeg uw chauffeurs toe, laad uw adressen. Gratis voor in totaal 15 stops in 2 routes, zonder creditcard.