Status und KBA-Ergebnisse

Speichern Sie die öffentliche Antrags-ID direkt nach der Anlage. Rufen Sie danach GET /api/v1/applications/{id} mit wachsendem Polling-Intervall ab und protokollieren Sie die X-Request-Id bei Auffälligkeiten. Bei fehlgeschlagenen Testanträgen enthält results.failure_code den beim Testereignis gesetzten stabilen Code.

Das Objekt results ist in jedem Antragsobjekt vorhanden. Es bündelt die fachliche Entscheidung, die KBA-Antragsnummer, das zugeordnete Kennzeichen und die aktuelle freigebbare Behördenquittung. Die KBA-Unterfelder sind optional, weil sie zu unterschiedlichen Zeitpunkten eintreffen.

results.kba_application_number ist die vom KBA vergebene Referenz. Sie ist unabhängig von der öffentlichen id der API und Ihrer external_reference. Speichern Sie alle drei Werte getrennt.

Nicht vorhandene optionale Ergebnisfelder werden ausgelassen. Prüfen Sie deshalb jedes Feld separat und aktualisieren Sie Ihren gespeicherten Ergebnisstand bei jedem Polling-Response.

{
  "id": "app_live_7f3a92c41b6d8e2054fa1c09",
  "external_reference": "fleet-2026-0042",
  "status": "succeeded",
  "results": {
    "decision": "approved",
    "kba_application_number": "88888012345678901234",
    "assigned_license_plate": "B DZ 1234"
  }
}

Lehnt das KBA oder die Zulassungsstelle einen Antrag ab, ist das kein API-Fehler: Der Abruf antwortet weiterhin mit HTTP 200. Die Ablehnung steht im Antragsobjekt — status: failed, results.decision: rejected und next_action.type: resolve_application_issue.

status_details.failure_reason enthält einen kuratierten, anzeigbaren Grund ohne interne oder Dienstleisterdetails. Die originale Behördenquittung steht, sofern freigebbar, in results.authority_status. Das Feld kann auch bei fehlgeschlagenen Anträgen fehlen, etwa wenn die Quittung interne Details enthält.

{
  "status": "failed",
  "status_details": {
    "label": "Fehlgeschlagen",
    "failure_reason": "Der Antrag konnte nicht erfolgreich abgeschlossen werden."
  },
  "next_action": {
    "type": "resolve_application_issue",
    "message": "Bitte prüfen Sie den fachlichen Ablehnungsgrund und wenden Sie sich bei Rückfragen an den Support."
  },
  "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"
      }
    ]
  }
}

results.authority_status ist ein Array, weil eine einzelne Behördenantwort mehrere Quittungscodes enthalten kann. Jeder Eintrag hält den fünfstelligen Code und genau seine Message zusammen; führende Nullen sind Bestandteil des Code-Strings.

Prüfen Sie jeden Eintrag und behalten Sie auch unbekannte Code-/Message-Paare bei. Für die grundsätzliche Statusentscheidung verwenden Sie weiterhin status und results.decision.

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

for (const { code, message } of authorityEntries) {
  applyKnownRule(code, message)
}

storeUnknownEntries(authorityEntries.filter(({ code }) => !isKnownCode(code)))

Das Antragsobjekt enthält verfügbare Dokumentmetadaten in documents. Die eigene Listenroute liefert dieselben abrufbaren Dokumentressourcen; der Binärinhalt wird erst über download_url übertragen.

• Liste abrufen und Dokumenttyp prüfen.
• Das gewünschte Dokument über seine ID binär herunterladen.
• MIME-Typ, Dateiname und Mandantenzuordnung vor dem Speichern kontrollieren.

Die Gebührenroute liefert alle verfügbaren Revisionen. amount: 3170 bedeutet 31,70 EUR. Ein Gebührenbescheid ist nur abrufbar, wenn die Position eine notice_url enthält. Das Feld fees im Antragsobjekt kann zusätzlich die aktuell ausgewählte Gebührenrevision zusammenfassen. revision ist deren fortlaufende Revisionsnummer; current: true kennzeichnet die für den Antrag aktuell wirksame Revision.

{
  "fees": {
    "id": "fee_9",
    "object": "official_fee",
    "amount": 3170,
    "amount_net": 3170,
    "vat_amount": 0,
    "currency": "EUR",
    "revision": 2,
    "current": true
  }
}