Naar de inhoud

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.

Machineleesbare beschrijving (OpenAPI)

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.

API en webhooks

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.