Für Entwickler
API und Webhooks
Ihr Webshop oder ein anderes System sendet Bestellungen als Stopps an Routehive und erhält den Zustellstatus per Webhook oder Abfrage zurück. Verfügbar in den Paketen Pro und Flotte.
Authentifizierung
Der Inhaber oder ein Admin erstellt den API-Schlüssel auf der Seite API und Webhooks der App. Der Schlüssel wird nur einmal angezeigt. Senden Sie ihn bei jeder Anfrage als Bearer-Token im Header. Mit einem Nur-Lese-Schlüssel können keine Stopps angelegt werden.
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"]
}'Endpunkte
GET /api/v1/routes?date=YYYY-MM-DD- Touren eines Tages (Standard: heute, in der Zeitzone des Unternehmens).
GET /api/v1/routes/{id}- Eine Tour mit ihren Stopps in Reihenfolge.
POST /api/v1/stops- Ein neuer Stopp, zum Beispiel eine Webshop-Bestellung.
GET /api/v1/stops/{id}- Status eines Stopps: zugestellt, fehlgeschlagen, kassierter Betrag, Foto und Unterschrift.
Stopp anlegen
Ohne Tour landet der Stopp in der Eingangstour des Tages, von dort teilt ihn der Disponent zu. Senden Sie dieselbe Bestellnummer (reference) für denselben Tag erneut, entsteht kein neuer Stopp: Sie erhalten den vorhandenen zurück. Erneutes Senden ist also sicher.
Felder
address- Die Adresse (Pflicht). Mit Koordinaten entfällt die Adresssuche.
name- Name des Empfängers oder der Firma.
phone, email- Telefonnummer und E-Mail-Adresse für Benachrichtigungen.
reference- Ihre Bestellnummer: daran erkennen Sie den Stopp im Webhook, und sie verhindert Dubletten.
cod_amount, payment_required- Nachnahme in der kleinsten Einheit der Währung (Forint: ganze Forint, Euro: Cent).
date- Tag der Eingangstour (JJJJ-MM-TT). Standard: heute.
route_id- Eine bestimmte Tour statt der Eingangstour, solange sie noch erweiterbar ist.
packages- Paket-Barcodes: der Fahrer scannt sie vor der Zustellung.
require_photo, require_signature- Pflichtfoto oder Pflichtunterschrift für die Zustellung.
Webhooks
Die Webhook-URL legen Sie auf derselben Seite fest (nur https) und wählen die Ereignisse aus. Routehive sendet zu jedem Ereignis ein JSON per POST; der Inhalt entspricht der Antwort der Stopp-Abfrage.
stop.delivered- Ein Stopp wurde zugestellt (mit kassiertem Betrag, Foto- und Unterschriftsangabe).
stop.failed- Eine Zustellung ist fehlgeschlagen (mit der Notiz des Fahrers).
route.dispatched- Eine Tour wurde an den Fahrer ausgegeben.
route.completed- Eine Tour wurde abgeschlossen.
{
"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
}
}Signatur prüfen
Jede Anfrage hat den Header X-Routehive-Signature: t=Zeitstempel,v1=Signatur. Die Signatur ist der HMAC-SHA256 aus Zeitstempel, Punkt und rohem Inhalt mit dem Webhook-Geheimnis. Stimmt sie nicht, verwerfen Sie die Anfrage.
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"));
}Jede 2xx-Antwort bestätigt den Empfang. Bei Fehlern versuchen wir es immer seltener erneut (1 Minute, 5 Minuten, 30 Minuten, 2 Stunden, 12 Stunden, 24 Stunden). Nach 50 Fehlern in Folge wird der Webhook deaktiviert und der Inhaber per E-Mail informiert.
Fehler und Limits
Fehler sehen so aus: {"error": {"code": …, "message": …}}. Der Code ist englisch, die Meldung in der Sprache Ihres Unternehmens. Pro Schlüssel sind 120 Anfragen pro Minute möglich, darüber kommt 429.
So planen Sie schon morgen früh Ihre Touren
Registrieren Sie sich, legen Sie Ihre Fahrer an, laden Sie Ihre Adressen hoch. Kostenlos für insgesamt 15 Stopps in 2 Touren, ohne Kreditkarte.