Zulassungs-API: Anträge aus Ihrer Software über die KBA-Großkundenschnittstelle einreichen

Wie kommt ein Partner von der Sandbox in den Live-Betrieb?

Jeder Zugang startet in der Sandbox: eigene Datenbank, kein Kontakt zum KBA, Schlüssel mit dem Präfix zo24_sbx_. Den Live-Schlüssel (zo24_live_) gibt es erst nach einem erfolgreichen Sandbox-Test; Sandbox-Vorgänge werden nach 30 Tagen automatisch gelöscht.

1. GET /v1/ping prüft Schlüssel und Zugang, GET /v1/feldregeln liefert die Pflichtfelder je Arbeitsgang.
2. POST /v1/antraege/pruefen prüft Schema und Plausibilität, ohne das KBA zu kontaktieren.
3. POST /v1/antraege reicht ein und verlangt einen Idempotency-Key mit 8 bis 128 Zeichen.
4. POST /v1/sandbox/antraege/{id}/simulieren erzeugt in der Sandbox Ergebnisse, Bescheide und Webhooks.
5. Nach dem Test schalten wir den Live-Zugang frei; der Aufbau der Aufrufe bleibt gleich, nur Host und Schlüssel ändern sich.

# Antrag in der Sandbox einreichen
# SANDBOX_URL erhalten Sie mit dem Zugang
curl -X POST "$SANDBOX_URL/v1/antraege" \
  -H "Authorization: Bearer zo24_sbx_…" \
  -H "Idempotency-Key: fuhrpark-4711-neuzulassung" \
  -H "Content-Type: application/json" \
  --data @antrag.json

# gleiche Anfrage mit gleichem Schlüssel wiederholt:
# ursprüngliche Antwort + Kopfzeile
Idempotent-Replayed: true

Eine Wiederholung mit gleichem Schlüssel und gleichem Inhalt liefert die ursprüngliche Antwort zurück. Bricht die Verbindung beim Einreichen ab, kann Ihr System also gefahrlos erneut senden, ohne einen zweiten Antrag beim KBA auszulösen.

Wie prüft Ihr System die Signatur eines Webhooks?

Jeder Webhook kommt als POST mit den Kopfzeilen Webhook-Id, Webhook-Timestamp (Unix-Sekunden) und Webhook-Signature: v1=<hex>. Die Signatur ist ein HMAC-SHA256 über <Webhook-Id>.<Webhook-Timestamp>.<Body> mit dem Geheimnis, das beim Anlegen des Webhooks einmal angezeigt wurde.

Ereignisse können mehrfach eintreffen: Entdoppeln Sie über Webhook-Id und verwerfen Sie Zeitstempel, die älter als 5 Minuten sind. Die Nutzlast enthält keine personenbezogenen Daten; Einzelheiten holt Ihr System über die verlinkten Endpunkte.

Ihr Endpunkt muss binnen 10 Sekunden mit einem 2xx-Status antworten; Weiterleitungen werden nicht verfolgt. Schlägt eine Zustellung fehl, wiederholen wir sie bis zu sechsmal in wachsenden Abständen von 30 Sekunden, 2 Minuten, 10 Minuten, 1 Stunde, 6 Stunden und 24 Stunden. Nach 50 fehlgeschlagenen Zustellungen in Folge wird der Webhook automatisch deaktiviert.

# Python: Webhook-Signatur prüfen
import hashlib
import hmac
import time

def webhook_ist_echt(webhook_id, zeitstempel, signatur, body, geheimnis):
    # Zeitstempel in Unix-Sekunden, max. 5 Minuten alt
    if abs(time.time() - int(zeitstempel)) > 300:
        return False
    nachricht = f"{webhook_id}.{zeitstempel}.".encode() + body
    erwartet = "v1=" + hmac.new(
        geheimnis.encode(), nachricht, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(erwartet, signatur)