Zum Inhalt springen

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.

Maschinenlesbare Beschreibung (OpenAPI)

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.

API und Webhooks

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.