Testereignis auslösen

Testereignisse simulieren Signatur, Bearbeitung, Abschluss und Fehlschlag ohne KBA-Aufruf. Erforderlich ist applications:write.

Beschreibung

Setzt den nächsten Zustand eines Testantrags.

Parameter

idpathPflicht

ID eines Testantrags.

Beispiel: app_test_1a2b3c4d5e6f708192a3b4c5

Request-Body

Der Body wird als application/json übertragen. Verwenden Sie ausschließlich die dokumentierten Feldnamen.

Request-Felder

Feld	Typ	Angabe	Beschreibung
`type`	enum	Pflicht	`signature.completed`, `processing.started`, `application.completed` oder `application.failed`.
`failure.code`	string	Bedingt	Optional bei `application.failed`; stabiler maschinenlesbarer Fehlercode.
`failure.message`	string	Bedingt	Optional bei `application.failed`; lesbare Fehlerbeschreibung.

{
  "type": "application.completed"
}

SchemaquelleOpenAPI 3.1 herunterladen

Responses

200

Testereignis angewendet; aktualisiertes Antragsobjekt.

401/403

API-Schlüssel, Testumgebung oder Scope applications:write ist ungültig.

404

Testantrag fehlt oder gehört zu einem anderen Mandanten.

409

Ereignis passt nicht zum aktuellen Antragszustand.

422

Ereignistyp oder failure-Daten sind ungültig.

Response-Body

Content-Type: application/json. Die erfolgreiche Antwort enthält die nachfolgend beschriebenen Felder.

Response-Felder

Feld	Typ	Angabe	Beschreibung
`id`	string	Immer	Öffentliche Antrags-ID.
`object`	string	Immer	Konstanter Wert `vehicle_registration_application`.
`environment`	enum	Immer	`test` oder `live`.
`livemode`	boolean	Immer	`true` bei Produktivanträgen.
`procedure`	enum	Immer	Ausgeschriebener Vorgang.
`procedure_code`	enum	Immer	`AB`, `WG`, `WZ`, `NZ`, `TZ`, `UG` oder `HA`.
`submission_mode`	enum	Immer	`company` oder `third_party`.
`contract_partner_id`	string	Optional	Beim Anlegen gebundener Vertragspartner. KOPA-Schlüssel und Stammdaten werden nicht ausgegeben.
`holder`	object	Optional	Gespeicherte Halter-ID, Revision und Verifizierungsstatus. Fehlt bei AB ohne Halterreferenz.
`external_reference`	string	Optional	Beim Anlegen übergebene Referenz.
`signature_profile`	string	Optional	Beim Anlegen gebundenes Signaturprofil. Fehlt ohne Profilangabe.
`status`	enum	Immer	Aktueller Antragsstatus. Dieses Feld für Programmlogik verwenden.
`status_details`	object	Immer	Anzeigetext, Änderungszeitpunkt und gegebenenfalls Fehlerangaben.
`next_action`	object	Optional	Nächste Clientaktion, beispielsweise Signatur oder Fehlerbehebung.
`signature`	object	Immer	Signaturpflicht, Status und gegebenenfalls Signatur-URL.
`results`	object	Immer	Aktuelle Entscheidung und alle bereits verfügbaren KBA-, Kennzeichen- und Behördenwerte. Optionale Unterfelder werden ausgelassen, solange kein Wert vorliegt.
`results.decision`	enum	Immer	`pending`, `approved`, `rejected` oder `manual_review`. Zusammen mit `status` für Programmlogik verwenden.
`results.failure_code`	string	Optional	Stabiler maschinenlesbarer Code eines fehlgeschlagenen Testereignisses. Kein KBA-Quittungscode.
`results.kba_application_number`	string	Optional	Vom KBA vergebene Antragsnummer, sobald sie für den Antrag vorliegt. Nicht mit der öffentlichen `id` oder `external_reference` verwechseln. Ein erfolgreicher Testabschluss liefert eine simulierte Nummer mit Präfix `KBA-TEST-`.
`results.assigned_license_plate`	string	Optional	Dem Antrag zugeordnetes Kennzeichen, sobald es als Ergebniswert vorliegt.
`results.authority_status`	array	Optional	Alle freigebbaren Code-/Message-Paare der aktuellsten Behördenquittung. Das Feld ist kein Quittungsverlauf und kann auch bei `status: failed` fehlen.
`results.authority_status[].code`	string	Bedingt	Fünfstelliger Quittungscode der Live-Behördenantwort. Führende Nullen bleiben erhalten. Ein erfolgreicher Testabschluss liefert `0000`.
`results.authority_status[].message`	string	Bedingt	Die diesem Code zugeordnete offizielle Message. Nicht für Programmlogik verwenden.
`documents`	array	Immer	Metadaten bereitgestellter Dokumente.
`orders_url`	string	Immer	URL der antragsgebundenen Zusatzbestellungen.
`fees`	object	Optional	Aktuelle Gebührenrevision in Euro-Cent.
`tariff`	object	Optional	Tarifinformationen.
`timestamps`	object	Immer	Erstellungs-, Änderungs- und Statuszeitpunkt.
`warnings`	array	Optional	Nicht blockierende Hinweise.

{
  "id": "app_test_1a2b3c4d5e6f708192a3b4c5",
  "object": "vehicle_registration_application",
  "environment": "test",
  "livemode": false,
  "procedure": "new_registration",
  "procedure_code": "NZ",
  "submission_mode": "third_party",
  "holder": {
    "id": "hld_test_1a2b3c4d5e6f708192a3b4c5",
    "revision": 1,
    "verification_status": "verified"
  },
  "external_reference": "test-ci-1042",
  "status": "succeeded",
  "status_details": {
    "label": "Abgeschlossen",
    "updated_at": "2026-08-23T10:58:04+02:00"
  },
  "signature": {
    "required": true,
    "status": "completed"
  },
  "results": {
    "decision": "approved",
    "kba_application_number": "KBA-TEST-A1B2C3D4E5F6",
    "authority_status": [
      {
        "code": "0000",
        "message": "Testvorgang erfolgreich abgeschlossen"
      }
    ]
  },
  "documents": [
    {
      "id": "doc_17",
      "type": "TEST",
      "name": "api test result",
      "filename": "test-ergebnis-app_test_1a2b3c4d5e6f708192a3b4c5.pdf",
      "mime_type": "application/pdf",
      "created_at": "2026-08-23T10:58:04+02:00",
      "download_url": "/api/v1/applications/app_test_1a2b3c4d5e6f708192a3b4c5/documents/doc_17"
    }
  ],
  "orders_url": "/api/v1/applications/app_test_1a2b3c4d5e6f708192a3b4c5/orders",
  "timestamps": {
    "created_at": "2026-08-23T10:42:18+02:00",
    "updated_at": "2026-08-23T10:58:04+02:00",
    "status_updated_at": "2026-08-23T10:58:04+02:00"
  }
}

Empfohlene Reihenfolge

01
Signatur abschließen
signature.completed beendet den Signaturschritt.
02
Bearbeitung starten
processing.started setzt den Status auf processing.
03
Ergebnis setzen
application.completed oder application.failed bildet das gewünschte Ergebnis ab.

Fehlercode setzen

Für application.failed können failure.code und failure.message gesendet werden. Der Code steht anschließend in results.failure_code; ohne Angabe lautet er test_rejected. Die Meldung steht in status_details.failure_reason.

{
  "type": "application.failed",
  "failure": {
    "code": "vehicle_data_rejected",
    "message": "Simulierter Ablehnungsgrund"
  }
}

{ "id": "app_test_1a2b3c4d5e6f708192a3b4c5", "object": "vehicle_registration_application", "environment": "test", "livemode": false, "procedure": "new_registration", "procedure_code": "NZ", "submission_mode": "third_party", "holder": { "id": "hld_test_1a2b3c4d5e6f708192a3b4c5", "revision": 1, "verification_status": "verified" }, "external_reference": "test-ci-1042", "status": "succeeded", "status_details": { "label": "Abgeschlossen", "updated_at": "2026-08-23T10:58:04+02:00" }, "signature": { "required": true, "status": "completed" }, "results": { "decision": "approved", "kba_application_number": "KBA-TEST-A1B2C3D4E5F6", "authority_status": [ { "code": "0000", "message": "Testvorgang erfolgreich abgeschlossen" } ] }, "documents": [ { "id": "doc_17", "type": "TEST", "name": "api test result", "filename": "test-ergebnis-app_test_1a2b3c4d5e6f708192a3b4c5.pdf", "mime_type": "application/pdf", "created_at": "2026-08-23T10:58:04+02:00", "download_url": "/api/v1/applications/app_test_1a2b3c4d5e6f708192a3b4c5/documents/doc_17" } ], "orders_url": "/api/v1/applications/app_test_1a2b3c4d5e6f708192a3b4c5/orders", "timestamps": { "created_at": "2026-08-23T10:42:18+02:00", "updated_at": "2026-08-23T10:58:04+02:00", "status_updated_at": "2026-08-23T10:58:04+02:00" } }

Request-Felder

Response-Body

Response-Felder

Signatur abschließen

Bearbeitung starten

Ergebnis setzen