Antrag und Status abrufen

Der aktuelle KBA-Ergebnisstand steht vollständig unter results. results.decision ist immer vorhanden; kba_application_number, assigned_license_plate und authority_status erscheinen, sobald der jeweilige Wert vorliegt.

Die KBA-Antragsnummer ist nicht die öffentliche API-ID. Verwenden Sie id für API-Aufrufe, external_reference für Ihre eigene Zuordnung und results.kba_application_number als Referenz des KBA-Vorgangs.

Optionale Ergebnisfelder werden ohne Wert vollständig ausgelassen und nicht als null geliefert. Clients müssen daher jedes KBA-Unterfeld unabhängig auf Vorhandensein prüfen.

Bei status: failed steht die aktuelle Entscheidung in results.decision: rejected. status_details.failure_reason ist der kuratierte, anzeigbare Grund. Die originale Behördenquittung steht, sofern freigebbar, in results.authority_status.

results.authority_status ist ein Array. Jeder Eintrag enthält genau einen fünfstelligen code und seine zugehörige message. Eine Behördenantwort kann mehrere solcher Paare enthalten. Werten Sie deshalb alle Einträge aus. Das gesamte Feld bleibt optional.

Bei fehlgeschlagenen Testanträgen enthält results.failure_code zusätzlich den beim Testereignis gesetzten stabilen Code. Dieses Feld ist von den behördlichen Code-/Message-Paaren getrennt.

{
  "status": "failed",
  "status_details": {
    "label": "Fehlgeschlagen",
    "failure_reason": "Der Antrag konnte nicht erfolgreich abgeschlossen werden."
  },
  "results": {
    "decision": "rejected",
    "authority_status": [
      {
        "code": "00764",
        "message": "Die fachliche Prüfung der Zulassung ist fehlgeschlagen"
      },
      {
        "code": "00301",
        "message": "Die Angabe zur Versicherungsbestätigungsnummer fehlt"
      }
    ]
  }
}

• Codes als Strings speichern, damit führende Nullen erhalten bleiben.
• Das Array vollständig durchlaufen und Code sowie Message immer gemeinsam speichern.
• Unbekannte Paare nicht verwerfen. Zusammen mit application.id, timestamps.status_updated_at und X-Request-Id protokollieren.
• Für Programmlogik status und results.decision verwenden. Die einzelnen Messages und status_details.failure_reason sind Anzeigetexte und können sich sprachlich ändern.

const rejected = application.status === 'failed' &&
  application.results.decision === 'rejected'

const authorityEntries = application.results.authority_status ?? []

if (rejected) {
  for (const { code, message } of authorityEntries) {
    handleAuthorityCode(code, message)
  }
}

Verwenden Sie ein wachsendes Intervall von einigen Sekunden bis zu mehreren Minuten. Bei 429 gibt Retry-After die Wartezeit vor.