Zum Inhalt springen

Referenz: API

Alle Endpunkte und Datentypen der Dropshipping API 2.3.0, erzeugt aus der OpenAPI-Datei /spec/api.yaml. Aus derselben Datei lässt sich mit gängigen Generatoren Client-Code erzeugen.

Pfade sind relativ zur Basis-URL https://{host}/dropshipping-api/{clientId}/2.3.0. Pflichtfelder tragen ein *. Welche Felder je Vorgangsart darüber hinaus Pflicht sind, lässt sich an einem gemeinsamen Schema nicht ausdrücken — das beschreiben die Seiten der Vorgangsarten.

POWRdrive Dropshipping Client API · 2.3.0

OpenAPI-YAML

Alle Endpunkte und Datentypen zum Aufklappen. Aus der YAML lässt sich zusätzlich Client-/Server-Code generieren.

Endpunkte

POST/vehicleDeregistrations/deregistrationsAußerbetriebsetzung beauftragen

Stellt den Antrag bei der GKS. Die Antwort enthält nur die Auftragsnummer — das Ergebnis wird asynchron über Webhook-Events mitgeteilt, typischerweise ACCEPTED gefolgt von APPROVED_WITH_DOCUMENTS.

Request application/json

customization* VehicleDeregistrationCustomization
productType enum
VEHICLE_DEREGISTRATION
licensePlateNumberComponents* EuroLicensePlateNumberComponents
usageType enum
Kennzeichenmerkmal — für alle Anträge mit bisherigem Kennzeichen (AB, HA, UG, WG, WZ): EURO (Normalfall), ELECTRIC (Elektrokennzeichen) und HISTORIC (Oldtimerkennzeichen); andere Werte werden mit HTTP 400 abgewiesen.
EURO · ELECTRIC · HISTORIC
city* string
Unterscheidungszeichen, 1–3 Buchstaben (Umlaute zulässig). Kleinbuchstaben werden großgeschrieben; das Muster lässt sie deshalb zu.
middle* string
Erkennungsbuchstaben, 1–2 Buchstaben ohne Umlaute. Kleinbuchstaben werden großgeschrieben.
end* string
Erkennungsnummer, 1–4 Ziffern.
licensePlateReservationIncluded* boolean
Kennzeichen fahrzeugbezogen reservieren, längstens zwölf Monate. Bei Entsorgung (SCRAPPED_IN_GERMANY, EXPORTED_FOR_DISPOSAL) ausgeschlossen.
vehicleIdentificationNumber* string
Fahrzeugidentifizierungsnummer. Geprüft wird die Regel des KBA: Ziffern und Großbuchstaben, höchstens 25 Stellen (sonst Fehlercode 00306); Kleinbuchstaben werden großgeschrieben. **Auf Länge und Zeichenwahl wird bewusst NICHT strenger geprüft** — seit 1981 hat eine FIN zwar genau 17 Stellen und üblicherweise kein I, O oder Q, aber Oldtimer führen kürzere Nummern, und die amtlichen Beispiele des KBA enthalten vereinzelt doch ein O. Eine falsche FIN fällt deshalb erst beim KBA auf und kostet die Übermittlungsgebühr: bitte gegen den Fahrzeugschein prüfen.
vehicleRegistrationCertificateSecurityCode* string
Sicherheitscode der Zulassungsbescheinigung Teil I, genau sieben Ziffern oder Buchstaben (`SicherheitscodeZB1`). Klein- und Großschreibung gehören hier zum Wert und werden nicht vereinheitlicht.
frontLicensePlateSecurityCode string
Sicherheitscode der vorderen Stempelplakette, genau drei Ziffern oder Buchstaben. Erforderlich bei Fahrzeugen mit zwei Kennzeichenschildern; bei nur einem Schild unzulässig.
rearLicensePlateSecurityCode* string
Sicherheitscode der hinteren Stempelplakette, genau drei Ziffern oder Buchstaben.
vehicleRegistrationCertificateNumber string
Erweiterung — Nummer der ZB I, 18–20 Zeichen, Buchstabe am Anfang. Kleinbuchstaben werden großgeschrieben; das Muster lässt sie deshalb zu.
recycling Recycling
type* enum
SCRAPPED_IN_GERMANY — Verwertungsnachweis lag vor (§ 15 Abs. 1/2 FZV). NOT_DISPOSED — außer Betrieb gesetzt, nicht als Abfall entsorgt (§ 15 Abs. 5 FZV). EXPORTED_FOR_DISPOSAL — zur Entsorgung außerhalb EU/EWR verbracht (§ 15 Abs. 4 FZV).
SCRAPPED_IN_GERMANY · NOT_DISPOSED · EXPORTED_FOR_DISPOSAL
dismantlingCompanyNumber string
Betriebsnummer des Demontagebetriebs, höchstens 20 Zeichen (`BetriebsnummerDemontagebetrieb`). Pflicht bei SCRAPPED_IN_GERMANY.
certificateDate string (date)
Ausstellungsdatum des Nachweises. Pflicht bei SCRAPPED_IN_GERMANY.
countryCode string
Zielstaat nach KBA-Staatsschlüssel, ein bis drei Großbuchstaben (`StaatVerwertung`, z. B. D, NL). Pflicht bei EXPORTED_FOR_DISPOSAL.
vehicleRegistrationCertificatePartII VehicleRegistrationCertificatePartII
number string
Nummer der ZB II. Kleinbuchstaben werden großgeschrieben.
securityCode* string
Zwölfstellig, **beginnend mit `B`**; danach zehn Stellen (Ziffern und Buchstaben, Kleinbuchstaben zulässig). Die letzte Stelle ist eine Ziffer oder `X` und trägt die Modulo-11-Prüfziffer über den gesamten Code. Format und Prüfziffer sind zwei Prüfungen: Die Form lässt sich gegen `pattern` vorab feststellen, die Prüfziffer rechnet der Dienst vor dem Versand nach und weist sie mit 400 ab.
contractPartner ContractPartner
email* string (email)
externalOrderId string
Ihre eigene Referenz. Wird in Webhook-Events zurückgegeben — und ist zugleich der Schutz gegen den doppelt gestellten Antrag: Derselbe Mandant, dieselbe `externalOrderId`, dieselbe FIN und derselbe Geschäftsvorfall innerhalb von 15 Minuten gelten als Wiederholungsversuch. Es geht dann NICHTS erneut an das KBA, und die Antwort nennt den bestehenden Vorgang (HTTP 200, dieselbe `order.id`). Ohne Referenz greift der Schutz nicht — dann fehlt die Aussage „das ist derselbe Auftrag". **Weichen die Daten ab, ist es kein Wiederholungsversuch:** Dieselbe Referenz und FIN mit geändertem Inhalt beantwortet der Dienst mit **409** und ändert nichts. Weder darf er die Korrektur still verwerfen noch ungefragt einen zweiten Antrag samt Gebühr auslösen. Für einen weiteren Antrag eine eigene Referenz vergeben; für eine Berichtigung den bestehenden Vorgang korrigieren.
correctionOf integer (int64)
Vorgangsnummer eines abgewiesenen oder fehlgeschlagenen Auftrags, der mit diesem Rumpf korrigiert werden soll. Es entsteht ein neuer KBA-Versuch am selben Auftrag; die Antwort nennt `attemptOf` und `attempt`. Laufende oder beschiedene Aufträge ergeben 409.
gksConfigurationId string (uuid)
vehicleHolder VehicleDeregistrationRequestVehicleHolder
Wird entgegengenommen, aber nicht an das KBA übermittelt: Bei der Außerbetriebsetzung stammen die Halterdaten aus dem Fahrzeugregister.
address Address
firstName string
lastName string
companyName string
streetName string
houseNumber string
zipCode string
cityName string
countryCode string
KBA-Staatsschlüssel
{
  "externalOrderId": "bestellung-4711",
  "email": "kunde@example.de",
  "customization": {
    "productType": "VEHICLE_DEREGISTRATION",
    "licensePlateNumberComponents": {
      "usageType": "EURO",
      "city": "HN",
      "middle": "LL",
      "end": "2418"
    },
    "frontLicensePlateSecurityCode": "Vbg",
    "rearLicensePlateSecurityCode": "K7m",
    "vehicleIdentificationNumber": "WBA65432113218654",
    "vehicleRegistrationCertificateSecurityCode": "8407251",
    "licensePlateReservationIncluded": false
  }
}

Antworten

200 Der Antrag wurde angenommen.
order* object
id* integer (int64)
attemptOf integer (int64)
Nur bei einer Korrektur — die Auftragsnummer der Versuchskette.
attempt integer
Nur bei einer Korrektur — die laufende Nummer des neuen Versuchs.
{
  "order": {
    "id": 1
  }
}
400
401
403
409 Unter dieser `externalOrderId` und FIN liegt bereits ein Vorgang mit ANDEREN Daten. Es wurde nichts geändert und nichts gesendet.
error* string
Fehlerbeschreibung einschließlich TraceId.
traceId string
Auch im Header X-Trace-Id enthalten. Bei Rückfragen an den Support anzugeben.
413
415
500
503
default
GET/vehicleDeregistrations/files/content/{fileAccessKey}Beleg herunterladen

Löst einen Zugriffsschlüssel aus einem Webhook-Event ein. Schlüssel haben eine begrenzte Gültigkeit; abgelaufene Belege lassen sich im Self-Service-Bereich erneut freigeben.

Parameter

fileAccessKey*path

Antworten

200 Dateiinhalt. Der Content-Type entspricht dem tatsächlichen mediaType des Dokuments (in der Regel application/pdf), nicht zwingend application/octet-stream.

Schema: string (binary)

401
403
404 Schlüssel unbekannt oder abgelaufen.
error* string
Fehlerbeschreibung einschließlich TraceId.
traceId string
Auch im Header X-Trace-Id enthalten. Bei Rückfragen an den Support anzugeben.
500
default
GET/vehicleDeregistrations/feeNoticesSammelgebührenbescheide auflisten

Erweiterung gegenüber kennzeichen.dev. Die Sammelgebührenbescheide (0103) der Zulassungsbehörden, mit denen sie die Amtsgebühren mehrerer Anträge in Rechnung stellen — je Bescheid Behörde, Kontoinhaber, IBAN, Verwendungszweck, Fälligkeit, Betrag und die abgerechneten Anträge samt Positionen. PDF und XML sind über den Belegabruf mit dem `fileAccessKey` aus `files` einzulösen. **Nur für Mandanten mit eigener KBA-Registrierung** — der Bescheid lautet auf sie. Ein Vertragspartner, dessen Abrechnung über uns läuft, bekommt **403**, nicht eine leere Liste. Jeder Bescheid kommt auch als Ereignis `FEE_NOTICE_XKFZ_EVENT`; die Liste ist der Weg für den Abgleich und für das Nachholen des Bestands. Ein auf mehrere Nachrichten geteilter Bescheid steht einmal in der Liste, mit seiner letzten Nachricht; die vorherigen Teile sind kein eigener Eintrag, ihre Anträge stehen in `applications` (siehe `part`). Nur unter diesem Präfix erreichbar: Der Bescheid gehört zu keinem Geschäftsvorfall.

Parameter

fromqueryNur Bescheide, die ab diesem Zeitpunkt eingegangen sind. Unlesbar ⇒ **400**.
toquery
limitquery
offsetqueryGanze Zahl ab 0 und höchstens 9007199254740991 (der größte exakt darstellbare Wert). Alles andere ⇒ **400**.

Antworten

200 Die Bescheide, neueste zuerst.
feeNotices* FeeNotice[]
id* integer
messageId* string
Nachrichten-ID des KBA — eindeutig, auch bei erneuter Zustellung.
receivedAt* string
Wann die Nachricht hier ankam, ohne Zeitzone, sekundengenau.
issuedAt string
zeitpunktDerErstellung laut Nachrichtenkopf, wie das KBA ihn schreibt.
issuer* object
partnerKey* string
Kommunikationspartnerschlüssel der Zulassungsbehörde, z. B. B115779.
districtKey* string
Kreisschlüssel samt Zusatzziffer des Gebührengläubigers, z. B. 010010.
debtor* object
partnerKey* string
Kommunikationspartnerschlüssel des Gebührenschuldners — die eigene KoPa.
bank* object
accountHolder* string
iban* string
directDebit* boolean
true, wenn die Behörde per SEPA-Lastschrift einzieht — dann wird nicht überwiesen.
paymentReference string
Verwendungszweck laut Bescheid, meist Bescheidnummer und Kassenzeichen.
paymentId string
Kassenzeichen des Bescheids, sofern die Behörde eines eigens nennt.
dueDate string
amount* integer
Gesamtbetrag in Cent — der der Nachricht, nicht eine eigene Addition. Bei einem geteilten Bescheid die Summe sämtlicher Anträge aus der letzten Nachricht.
currency* string
noticeNumber string
Nummer des Gebührenbescheids laut Nachricht.
part object
Teil n von m laut Bescheidkopf (XKfz 6.0). Ab mehr als 500 Anträgen teilt die Behörde den Bescheid auf mehrere Nachrichten; nur die letzte trägt Gesamtbetrag, Bankverbindung, Kassenzeichen und PDF. Ein geteilter Bescheid erscheint deshalb nur einmal, mit seiner abschließenden Nachricht (der mit Gesamtbetrag), und `applications` enthält die Anträge aller bis dahin eingegangenen Teile. `part` gibt die Zählung laut Bescheidkopf wieder; sie kann auch eigenständige Bescheide eines Abrechnungszeitraums zählen, `part.number` muss also nicht `part.of` sein. Trifft ein früherer Teil erst danach ein, kommt das Ereignis erneut — mit derselben `id`, derselben `messageId`, demselben `amount` und der ergänzten Antragsliste.
number* integer
of* integer
applicationCount* integer
Anzahl der abgerechneten Anträge laut Nachricht; mindestens die Zahl der mitgeführten. Liegt sie über `applications`, fehlen noch Teile.
assignedCount* integer
Wie viele der Anträge zu einem eigenen Vorgang gehören.
applications* FeeNoticeApplication[]
applicationId string
Antragsnummer des KBA, 20-stellig.
paymentId string
Kassenzeichen dieses Antrags (Referenztyp 12).
licensePlate string
vehicleIdentificationNumber string
applicationDate string
businessTransaction string
AB
amount* integer
Summe der Positionen in Cent.
items* FeeNoticeItem[]
number* integer
code string
Gebührennummer nach GebOSt, z. B. 224.2.
name string
amount* integer
Betrag in Cent.
note string
assignment* enum
MATCHED — der Antrag gehört zu einem eigenen Vorgang (`order`). UNKNOWN — kein eigener Vorgang trägt diese Antragsnummer; kein Fehler, der Bescheid kann Anträge eines früheren Systems enthalten. AMBIGUOUS — die Antragsnummer steht mehrfach im Bescheid. MISMATCH — ein Vorgang trägt die Nummer, aber das Kennzeichen oder der Vertragspartner passt nicht.
MATCHED · UNKNOWN · AMBIGUOUS · MISMATCH
order object
id* integer (int64)
externalId string
contractPartner string
Kommunikationspartnerschlüssel des Vertragspartners, der den Antrag gestellt hat (Referenztyp 28), z. B. U234567 — nur, wenn die Behörde ihn nennt.
files* EingangsFile[]
purposeType* enum
RECEIPT ist der Gebührenbescheid als PDF, UNSPECIFIED das XML der Nachricht.
CERTIFICATE · RECEIPT · APPLICATION · UNSPECIFIED
mediaType* string
fileAccessKey* string (password)
Einzulösen über GET /vehicleDeregistrations/files/content/{fileAccessKey}.
expirationTime* string
Zeitpunkt nach ISO 8601, ohne Zeitzone, sekundengenau. Die Schlüssel eines Sammelgebührenbescheids (`gb_…`) und einer Nachricht ohne Vorgang (`ek_…`) gelten 90 Tage ab dem Ablegen — nicht 72 Stunden wie ein Vorgangsbeleg. Die Einzelauskunft (GET /vehicleDeregistrations/feeNotices/{id}, GET /vehicleDeregistrations/unmatchedMessages/{id}) setzt die Frist neu an.
filename* string
Der Name, unter dem der Abruf die Datei ausliefert — nach dem Muster `Datum_Behörde_0|1_Kassenzeichen_Nachrichten-ID.xml|pdf`, wie es kennzeichen.dev verwendet hat.
limit* integer
offset* integer
total* integer
hasMore* boolean
400 Ein Parameter war unbrauchbar oder unbekannt.
401
403
500
default
GET/vehicleDeregistrations/feeNotices/{id}Ein Sammelgebührenbescheid

Die Einzelauskunft verlängert die Gültigkeit der Zugriffsschlüssel: Wer sie holt, will die Dateien laden.

Parameter

id*path

Antworten

200 Der Bescheid.
id* integer
messageId* string
Nachrichten-ID des KBA — eindeutig, auch bei erneuter Zustellung.
receivedAt* string
Wann die Nachricht hier ankam, ohne Zeitzone, sekundengenau.
issuedAt string
zeitpunktDerErstellung laut Nachrichtenkopf, wie das KBA ihn schreibt.
issuer* object
partnerKey* string
Kommunikationspartnerschlüssel der Zulassungsbehörde, z. B. B115779.
districtKey* string
Kreisschlüssel samt Zusatzziffer des Gebührengläubigers, z. B. 010010.
debtor* object
partnerKey* string
Kommunikationspartnerschlüssel des Gebührenschuldners — die eigene KoPa.
bank* object
accountHolder* string
iban* string
directDebit* boolean
true, wenn die Behörde per SEPA-Lastschrift einzieht — dann wird nicht überwiesen.
paymentReference string
Verwendungszweck laut Bescheid, meist Bescheidnummer und Kassenzeichen.
paymentId string
Kassenzeichen des Bescheids, sofern die Behörde eines eigens nennt.
dueDate string
amount* integer
Gesamtbetrag in Cent — der der Nachricht, nicht eine eigene Addition. Bei einem geteilten Bescheid die Summe sämtlicher Anträge aus der letzten Nachricht.
currency* string
noticeNumber string
Nummer des Gebührenbescheids laut Nachricht.
part object
Teil n von m laut Bescheidkopf (XKfz 6.0). Ab mehr als 500 Anträgen teilt die Behörde den Bescheid auf mehrere Nachrichten; nur die letzte trägt Gesamtbetrag, Bankverbindung, Kassenzeichen und PDF. Ein geteilter Bescheid erscheint deshalb nur einmal, mit seiner abschließenden Nachricht (der mit Gesamtbetrag), und `applications` enthält die Anträge aller bis dahin eingegangenen Teile. `part` gibt die Zählung laut Bescheidkopf wieder; sie kann auch eigenständige Bescheide eines Abrechnungszeitraums zählen, `part.number` muss also nicht `part.of` sein. Trifft ein früherer Teil erst danach ein, kommt das Ereignis erneut — mit derselben `id`, derselben `messageId`, demselben `amount` und der ergänzten Antragsliste.
number* integer
of* integer
applicationCount* integer
Anzahl der abgerechneten Anträge laut Nachricht; mindestens die Zahl der mitgeführten. Liegt sie über `applications`, fehlen noch Teile.
assignedCount* integer
Wie viele der Anträge zu einem eigenen Vorgang gehören.
applications* FeeNoticeApplication[]
applicationId string
Antragsnummer des KBA, 20-stellig.
paymentId string
Kassenzeichen dieses Antrags (Referenztyp 12).
licensePlate string
vehicleIdentificationNumber string
applicationDate string
businessTransaction string
AB
amount* integer
Summe der Positionen in Cent.
items* FeeNoticeItem[]
number* integer
code string
Gebührennummer nach GebOSt, z. B. 224.2.
name string
amount* integer
Betrag in Cent.
note string
assignment* enum
MATCHED — der Antrag gehört zu einem eigenen Vorgang (`order`). UNKNOWN — kein eigener Vorgang trägt diese Antragsnummer; kein Fehler, der Bescheid kann Anträge eines früheren Systems enthalten. AMBIGUOUS — die Antragsnummer steht mehrfach im Bescheid. MISMATCH — ein Vorgang trägt die Nummer, aber das Kennzeichen oder der Vertragspartner passt nicht.
MATCHED · UNKNOWN · AMBIGUOUS · MISMATCH
order object
id* integer (int64)
externalId string
contractPartner string
Kommunikationspartnerschlüssel des Vertragspartners, der den Antrag gestellt hat (Referenztyp 28), z. B. U234567 — nur, wenn die Behörde ihn nennt.
files* EingangsFile[]
purposeType* enum
RECEIPT ist der Gebührenbescheid als PDF, UNSPECIFIED das XML der Nachricht.
CERTIFICATE · RECEIPT · APPLICATION · UNSPECIFIED
mediaType* string
fileAccessKey* string (password)
Einzulösen über GET /vehicleDeregistrations/files/content/{fileAccessKey}.
expirationTime* string
Zeitpunkt nach ISO 8601, ohne Zeitzone, sekundengenau. Die Schlüssel eines Sammelgebührenbescheids (`gb_…`) und einer Nachricht ohne Vorgang (`ek_…`) gelten 90 Tage ab dem Ablegen — nicht 72 Stunden wie ein Vorgangsbeleg. Die Einzelauskunft (GET /vehicleDeregistrations/feeNotices/{id}, GET /vehicleDeregistrations/unmatchedMessages/{id}) setzt die Frist neu an.
filename* string
Der Name, unter dem der Abruf die Datei ausliefert — nach dem Muster `Datum_Behörde_0|1_Kassenzeichen_Nachrichten-ID.xml|pdf`, wie es kennzeichen.dev verwendet hat.
401
403
404 Unbekannt, nicht der eigene — oder nur ein früherer Teil eines geteilten Bescheids.
error* string
Fehlerbeschreibung einschließlich TraceId.
traceId string
Auch im Header X-Trace-Id enthalten. Bei Rückfragen an den Support anzugeben.
500
default
GET/vehicleDeregistrations/unmatchedMessagesRückkanal-Nachrichten ohne Vorgang auflisten

Erweiterung gegenüber kennzeichen.dev. Alles, was das KBA an Ihre Registrierung schickt, ohne dass ein Antrag aus diesem System dazu passt — etwa der Bescheid zu einem Antrag, den ein früheres System unter derselben Registrierung gestellt hat. Ordnen Sie die Nachricht über `applicationId`, `vehicleIdentificationNumber` oder `licensePlate` Ihren eigenen Aufträgen zu, holen Sie die Belege über den Belegabruf und melden Sie den Stand über `PUT …/unmatchedMessages/{id}/state` zurück. Jede Nachricht kommt auch als Ereignis `UNMATCHED_MESSAGE_XKFZ_EVENT`. Den Gebührenbescheid (Art 46) unter den Belegen führt nur, wer selbst beim KBA abrechnet.

Parameter

fromquery
toquery
statequery
messageTypequery
limitquery
offsetqueryGanze Zahl ab 0 und höchstens 9007199254740991 (der größte exakt darstellbare Wert). Alles andere ⇒ **400**.

Antworten

200 Die Nachrichten, neueste zuerst.
messages* UnmatchedMessage[]
id* integer
messageType* string
Nachrichtentyp des KBA, z. B. 0709 (Antragskopie/Bescheid) oder 0002 (Quittung).
messageId string
receivedAt* string
issuedAt string
issuer* object
partnerKey* string
recipient* object
partnerKey* string
applicationId string
vehicleIdentificationNumber string
licensePlate string
businessTransaction string
status string
Antragsstatus laut Nachricht, z. B. bearbeitet, abgelehnt oder — seit XKfz 6.0 in der finalen Zulassungsnachricht — abgeschlossen.
statusTime string
processingKind string
Bearbeitungsart laut Nachricht, z. B. A für automatisiert.
decision enum
APPROVED · REJECTED · UNKNOWN
messages object[]
Die Quittungseinträge, sofern die Nachricht eine Quittung ist.
state* enum
OPEN · HANDLED · IGNORED
order object
id* integer (int64)
files* EingangsFile[]
purposeType* enum
RECEIPT ist der Gebührenbescheid als PDF, UNSPECIFIED das XML der Nachricht.
CERTIFICATE · RECEIPT · APPLICATION · UNSPECIFIED
mediaType* string
fileAccessKey* string (password)
Einzulösen über GET /vehicleDeregistrations/files/content/{fileAccessKey}.
expirationTime* string
Zeitpunkt nach ISO 8601, ohne Zeitzone, sekundengenau. Die Schlüssel eines Sammelgebührenbescheids (`gb_…`) und einer Nachricht ohne Vorgang (`ek_…`) gelten 90 Tage ab dem Ablegen — nicht 72 Stunden wie ein Vorgangsbeleg. Die Einzelauskunft (GET /vehicleDeregistrations/feeNotices/{id}, GET /vehicleDeregistrations/unmatchedMessages/{id}) setzt die Frist neu an.
filename* string
Der Name, unter dem der Abruf die Datei ausliefert — nach dem Muster `Datum_Behörde_0|1_Kassenzeichen_Nachrichten-ID.xml|pdf`, wie es kennzeichen.dev verwendet hat.
limit* integer
offset* integer
total* integer
hasMore* boolean
400 Ein Parameter war unbrauchbar oder unbekannt.
401
403
500
default
GET/vehicleDeregistrations/unmatchedMessages/{id}Eine Nachricht ohne Vorgang

Verlängert die Gültigkeit der Zugriffsschlüssel ihrer Belege.

Parameter

id*path

Antworten

200 Die Nachricht.
id* integer
messageType* string
Nachrichtentyp des KBA, z. B. 0709 (Antragskopie/Bescheid) oder 0002 (Quittung).
messageId string
receivedAt* string
issuedAt string
issuer* object
partnerKey* string
recipient* object
partnerKey* string
applicationId string
vehicleIdentificationNumber string
licensePlate string
businessTransaction string
status string
Antragsstatus laut Nachricht, z. B. bearbeitet, abgelehnt oder — seit XKfz 6.0 in der finalen Zulassungsnachricht — abgeschlossen.
statusTime string
processingKind string
Bearbeitungsart laut Nachricht, z. B. A für automatisiert.
decision enum
APPROVED · REJECTED · UNKNOWN
messages object[]
Die Quittungseinträge, sofern die Nachricht eine Quittung ist.
state* enum
OPEN · HANDLED · IGNORED
order object
id* integer (int64)
files* EingangsFile[]
purposeType* enum
RECEIPT ist der Gebührenbescheid als PDF, UNSPECIFIED das XML der Nachricht.
CERTIFICATE · RECEIPT · APPLICATION · UNSPECIFIED
mediaType* string
fileAccessKey* string (password)
Einzulösen über GET /vehicleDeregistrations/files/content/{fileAccessKey}.
expirationTime* string
Zeitpunkt nach ISO 8601, ohne Zeitzone, sekundengenau. Die Schlüssel eines Sammelgebührenbescheids (`gb_…`) und einer Nachricht ohne Vorgang (`ek_…`) gelten 90 Tage ab dem Ablegen — nicht 72 Stunden wie ein Vorgangsbeleg. Die Einzelauskunft (GET /vehicleDeregistrations/feeNotices/{id}, GET /vehicleDeregistrations/unmatchedMessages/{id}) setzt die Frist neu an.
filename* string
Der Name, unter dem der Abruf die Datei ausliefert — nach dem Muster `Datum_Behörde_0|1_Kassenzeichen_Nachrichten-ID.xml|pdf`, wie es kennzeichen.dev verwendet hat.
401
403
404 Unbekannt — oder nicht die eigene.
error* string
Fehlerbeschreibung einschließlich TraceId.
traceId string
Auch im Header X-Trace-Id enthalten. Bei Rückfragen an den Support anzugeben.
500
default
PUT/vehicleDeregistrations/unmatchedMessages/{id}/stateDen Stand einer Nachricht ohne Vorgang vermerken

Was Ihr System aus der Nachricht gemacht hat: HANDLED (übernommen, mit oder ohne eigenen Vorgang in `orderId`), IGNORED, oder wieder OPEN. Das Dashboard zeigt danach denselben Stand.

Parameter

id*path

Request application/json

state* enum
OPEN · HANDLED · IGNORED
orderId integer
Der eigene Vorgang, dem die Nachricht zugeordnet wurde — nur mit HANDLED sinnvoll.
{
  "state": "HANDLED",
  "orderId": 376
}

Antworten

200 Die Nachricht mit dem neuen Stand.
id* integer
messageType* string
Nachrichtentyp des KBA, z. B. 0709 (Antragskopie/Bescheid) oder 0002 (Quittung).
messageId string
receivedAt* string
issuedAt string
issuer* object
partnerKey* string
recipient* object
partnerKey* string
applicationId string
vehicleIdentificationNumber string
licensePlate string
businessTransaction string
status string
Antragsstatus laut Nachricht, z. B. bearbeitet, abgelehnt oder — seit XKfz 6.0 in der finalen Zulassungsnachricht — abgeschlossen.
statusTime string
processingKind string
Bearbeitungsart laut Nachricht, z. B. A für automatisiert.
decision enum
APPROVED · REJECTED · UNKNOWN
messages object[]
Die Quittungseinträge, sofern die Nachricht eine Quittung ist.
state* enum
OPEN · HANDLED · IGNORED
order object
id* integer (int64)
files* EingangsFile[]
purposeType* enum
RECEIPT ist der Gebührenbescheid als PDF, UNSPECIFIED das XML der Nachricht.
CERTIFICATE · RECEIPT · APPLICATION · UNSPECIFIED
mediaType* string
fileAccessKey* string (password)
Einzulösen über GET /vehicleDeregistrations/files/content/{fileAccessKey}.
expirationTime* string
Zeitpunkt nach ISO 8601, ohne Zeitzone, sekundengenau. Die Schlüssel eines Sammelgebührenbescheids (`gb_…`) und einer Nachricht ohne Vorgang (`ek_…`) gelten 90 Tage ab dem Ablegen — nicht 72 Stunden wie ein Vorgangsbeleg. Die Einzelauskunft (GET /vehicleDeregistrations/feeNotices/{id}, GET /vehicleDeregistrations/unmatchedMessages/{id}) setzt die Frist neu an.
filename* string
Der Name, unter dem der Abruf die Datei ausliefert — nach dem Muster `Datum_Behörde_0|1_Kassenzeichen_Nachrichten-ID.xml|pdf`, wie es kennzeichen.dev verwendet hat.
400 state fehlt oder ist unbekannt, oder orderId nennt keinen eigenen Vorgang.
401
403
404 Unbekannt — oder nicht die eigene.
error* string
Fehlerbeschreibung einschließlich TraceId.
traceId string
Auch im Header X-Trace-Id enthalten. Bei Rückfragen an den Support anzugeben.
413
415
500
default
GET/vehicleDeregistrations/ordersDie eigenen Aufträge auflisten

**Auch unter vier weiteren Praefixen erreichbar** (`vehicleHolderChanges`, `vehicleTransfers`, `vehicleReRegistrations`, `vehicleRegistrations`) — die Liste haengt am Vorgang, nicht am Geschaeftsvorfall. Nach dem Geschaeftsvorfall grenzt `businessTransaction` ein. Erweiterung gegenüber kennzeichen.dev. **Wofür sie da ist:** Bis hierher kam ein Aufrufer nur über die einzelne Vorgangsnummer an seinen Stand — und die kennt er nur, solange kein Webhook verlorengegangen ist. Genau dafür ist ein Abgleich da. **`changedSince` ist der eigentliche Zweck.** Wer täglich abgleicht, will nicht den ganzen Bestand, sondern das, was sich seit gestern getan hat. **Nur Auftragsköpfe.** Ein korrigierter Antrag ist beim KBA ein neuer Antrag, für den Kunden aber derselbe Auftrag; als eigene Zeile gelistet zählte ihn doppelt, wer über die Schnittstelle abrechnet. Die Versuche stehen in der Einzelauskunft (`attempt`, `attemptOf`). **Knapp gehalten:** kein `files`, keine `registrationData`, keine Gebührenangaben. Das sind je Vorgang eigene Abfragen, und zweihundert davon in einem Aufruf machen aus einer Abgleichshilfe eine Last. Wer die Einzelheiten braucht, holt den Vorgang — die Liste sagt ihm, welchen.

Parameter

externalIdqueryExakt Ihre eigene Referenz aus dem Antrag — nicht unscharf. Eine unscharfe Suche brächte `A-11` mit, wenn Sie `A-1` meinen. Gesetzt, aber leer (`externalId=`) ergibt **400**.
statequeryEin Zustand — oder **mehrere, mit Komma verbunden**; dann gilt „einer davon". Der Alltagsfall ist eine Gruppe: `beschieden,abgelehnt` heisst „alles, was fertig ist". Fragte man stattdessen zweimal und fügte selbst zusammen, stimmten weder `total` noch `hasMore`, und beim Blättern doppelte sich der Rand. Möglich sind: `angelegt`, `eingereicht`, `inBearbeitung`, `weitergeleitet`, `beschieden`, `abgelehnt`, `fehlgeschlagen`. Ein unbekannter Wert ergibt **400** und wird namentlich genannt — nicht die vollständige Liste: Still übergangen hielten Sie das Ergebnis für Ihren Filter.
businessTransactionqueryEiner oder mehrere Geschäftsvorfälle, mit Komma verbunden (`businessTransaction=NZ,TZ`). Nur die sieben Codes in Großschreibung; ein unbekannter Wert (etwa `nz`) ergibt **400** und wird namentlich genannt. Gesetzt, aber leer (`businessTransaction=`) ergibt ebenfalls **400** — ein leerer Filter liefert bewusst nicht den Gesamtbestand.
createdSincequeryNur Aufträge ab diesem Zeitpunkt. Unlesbar oder leer ⇒ **400**.
changedSincequeryNur Aufträge, deren Stand sich seitdem geändert hat. Unlesbar oder leer ⇒ **400**.
limitqueryEin größerer Wert wird auf 200 gekappt. Die Antwort weist das WIRKLICH angewandte Limit aus — sonst hielten Sie eine gekappte Liste für vollständig.
offsetqueryGanze Zahl ab 0 und höchstens 9007199254740991 (der größte exakt darstellbare Wert). Alles andere ⇒ **400**.

Antworten

200 Die Aufträge, neueste zuerst.
orders* VehicleDeregistrationOrderSummary[]
order object
id integer
externalId string
attemptOf integer
Id des Auftrags. In dieser Liste stehen nur Auftragsköpfe, also immer die eigene Id.
businessTransaction string
state enum
angelegt · eingereicht · inBearbeitung · weitergeleitet · beschieden · abgelehnt · fehlgeschlagen
derivedStatus enum
PENDING · SUCCESS · FAILURE · VEHICLE_UNKNOWN · VEHICLE_ALREADY_DEREGISTERED · LICENSE_PLATE_CODE_INVALID · REGISTRATION_CERTIFICATE_CODE_INVALID · LICENSE_PLATE_CODE_QTY_INVALID · INPUT_INVALID · RESERVATION_IMPOSSIBLE · ERROR_UNHANDLED
applicationId string
vehicleIdentificationNumber string
licensePlate string
createdAt string (date-time)
changedAt string (date-time)
Der Wert, gegen den `changedSince` filtert.
limit* integer
Das angewandte Limit. Höchstens 200, auch wenn Sie mehr anfragen.
offset* integer
total* integer
Wie viele Aufträge der Filter insgesamt trifft — nicht die Seitengröße.
hasMore* boolean
Ob nach dieser Seite noch etwas kommt. Steht ausdrücklich da, statt sie aus `total > offset + limit` ableiten zu lassen: Diese Rechnung stellt jeder Aufrufer selbst an, und einer stellt sie falsch.
400 Ein Filterwert war unbrauchbar.
401
403
500
default
GET/vehicleDeregistrations/orders/{orderId}Auskunft zu einem Vorgang

**Auch unter vier weiteren Praefixen erreichbar.** Derselbe Handler bedient `vehicleHolderChanges`, `vehicleTransfers`, `vehicleReRegistrations` und `vehicleRegistrations` — die Auskunft haengt am Vorgang, nicht am Geschaeftsvorfall. Wer eine Umschreibung stellt, muss seine Auskunft nicht unter einem Pfad abholen, der „Abmeldung" heisst. Dasselbe gilt fuer den Belegabruf. Erweiterung gegenüber kennzeichen.dev. Erlaubt den Abgleich, wenn ein Webhook-Event verloren gegangen ist.

Parameter

orderId*path

Antworten

200 Aktueller Stand des Vorgangs
order object
id integer
Vorgangsnummer in diesem System.
externalId string
Ihre eigene Referenz aus dem Antrag.
attempt integer
Laufende Nummer des Versuchs. Ein korrigierter Antrag entsteht als NEUER Vorgang mit derselben `externalId` — beim KBA ist jeder Versuch ein eigener Antrag mit eigener Antragsnummer.
attemptOf integer
Id des Auftrags, zu dem dieser Versuch gehört; beim ersten Versuch die eigene Id. **Wer über die Schnittstelle abrechnet, gruppiert danach** — sonst zählt derselbe Auftrag mehrfach. Abgerechnet wird er einmal (die Übermittlungsgebühr je abgewiesenem Versuch bleibt davon unberührt).
state enum
Der Stand des Vorgangs. **Endzustand heisst: Endzustand des VERSUCHS, nicht des Auftrags.** `beschieden`, `abgelehnt` und `fehlgeschlagen` beenden den einzelnen Antrag beim KBA. Der Auftrag darüber kann weitergehen: Wird ein abgewiesener Antrag korrigiert, entsteht ein zweiter Versuch, und der Auftragskopf folgt dem jüngsten — er wechselt dann von `fehlgeschlagen` zurück nach `inBearbeitung`. Wer auf „Endzustand" vertraut und den Auftrag in seinem System abschliesst, verpasst die Korrektur und meldet ein Fahrzeug als nicht abgemeldet, obwohl es abgemeldet wird. Der Rücksprung sieht dabei aus wie ein Fehler des Systems und ist keiner. Fragen Sie den Versuch ab, wenn Sie einen Endzustand brauchen — `attempt` und `attemptOf` sagen Ihnen, was Sie vor sich haben. Die Webhook-Ereignisse führen für denselben Sachverhalt eigene, englische Werte (`ACCEPTED`, `APPROVED_WITH_DOCUMENTS`, `REJECTED_WITH_DOCUMENTS`) samt `derivedStatus`.
angelegt · eingereicht · inBearbeitung · weitergeleitet · beschieden · abgelehnt · fehlgeschlagen
derivedStatus enum
Die grobe Einordnung: läuft noch, erledigt, gescheitert. `state` hat sieben Werte, und welche davon Endzustände sind, steht in dieser Spezifikation — ein Aufrufer müsste die Liste bei jeder Erweiterung nachziehen. Wenn Ihr System nur wissen will, ob es weiter warten muss, werten Sie dieses Feld aus. Es ist dieselbe Abbildung, die auch das Webhook-Ereignis führt.
PENDING · SUCCESS · FAILURE · VEHICLE_UNKNOWN · VEHICLE_ALREADY_DEREGISTERED · LICENSE_PLATE_CODE_INVALID · REGISTRATION_CERTIFICATE_CODE_INVALID · LICENSE_PLATE_CODE_QTY_INVALID · INPUT_INVALID · RESERVATION_IMPOSSIBLE · ERROR_UNHANDLED
applicationId string
Antragsnummer des KBA — der Schlüssel für jede Rückfrage dort. Erst gesetzt, nachdem die Quittung eingetroffen ist; bei einem Antrag, der das KBA nicht erreicht hat, bleibt sie leer.
vehicleIdentificationNumber string
Die FIN des Vorgangs, immer in Großschreibung. **Am Auftragskopf kann sie sich ändern.** Eine Korrektur darf eine falsch abgetippte FIN berichtigen; der Kopf folgt dem jüngsten Versuch und trägt danach die neue. Die `externalId` bleibt dabei dieselbe. Wer Fahrzeuge über die FIN führt, sollte das wissen — sonst liest es sich wie eine Verwechslung von Fahrzeugen.
licensePlate string
Kennzeichen in der Anzeigeform, z. B. `HN-LL 2418`.
files object[]
Belege aus dem Rückkanal. Der Gebührenbescheid erscheint nur, wenn Sie selbst beim KBA registriert sind. Am Auftragskopf stehen die Belege aller Versuche (Kopf und `attempts[].id`), ohne Dubletten und in der Reihenfolge ihres Eingangs; die Auskunft zu einer Versuchs-Id führt nur dessen eigene.
purposeType string
mediaType string
fileAccessKey string
Einzulösen über `/vehicleDeregistrations/files/content/{fileAccessKey}`.
expirationTime string (date-time)
Bis dahin ist der Schlüssel gültig — beim Ablegen eines Vorgangsbelegs 72 Stunden; danach im Self-Service erneut freigeben. **Format:** vollständiger ISO-8601-Zeitstempel MIT Zonenangabe und Millisekunden (`2026-09-19T14:38:22.558Z`). Das Webhook-Ereignis nennt denselben Zeitpunkt als `LocalDateTime` — in UTC, aber ohne Zone und sekundengenau (`2026-09-19T14:38:22`); dieses Format schreibt der Webhook-Vertrag vor (`spec/webhooks.yaml`, Vorbild kennzeichen.dev). Wer beide Quellen vergleicht, liest den Wert des Ereignisses als UTC.
filename string
Der Name, unter dem der Abruf die Datei ausliefert (`Content-Disposition`), z. B. `Vorgang-17_KBA-NZ-123_Zulassungsbescheid.pdf`. Zwei Belege mit `purposeType: CERTIFICATE` — Zulassungsbescheid und vorläufiger Zulassungsnachweis — sind daran zu unterscheiden.
costBreakdown object
Die Gebührenaufstellung aus der Entscheidung (0709) — derselbe Wert wie `costBreakdown` im Webhook-Ereignis, für den Abgleich nach einem verlorenen Ereignis. **Nur bei eigener KBA-Registrierung** (Selbstabrechner); ein Vertragspartner unter unserer Registrierung sieht die amtlichen Beträge weder hier noch im Ereignis noch im Dashboard. Fehlt, solange keine Entscheidung vorliegt.
kbaCost integer
Nutzungsgebühr des KBA nach Nr. 129 GebOSt, in Cent. Steht da, wenn das KBA sie mit Quittungscode 07085 angekündigt hat oder der Antrag beschieden bzw. abgelehnt ist; sonst fehlt das Feld.
registrationOfficeCosts object
items* VehicleDeregistrationOrderCostBreakdownItem[]
number* integer
code string
Gebührennummer nach GebOSt, z. B. 224.2.
name string
amount* integer
Betrag in kleinster Währungseinheit (Cent).
note string
total* VehicleDeregistrationOrderCostBreakdownItem
number* integer
code string
Gebührennummer nach GebOSt, z. B. 224.2.
name string
amount* integer
Betrag in kleinster Währungseinheit (Cent).
note string
registrationData object
Über sechzig Angaben aus den Zulassungsbescheinigungen, sofern die Rückmeldung sie führt.
registrationDocumentsReady boolean
Erweiterung gegenüber kennzeichen.dev. `true`, wenn die Zulassungsbehörde meldet, dass die Zulassungsunterlagen (ZB I, ZB II, Stempelplaketten, Feinstaubplakette) wie gewünscht versandt wurden oder zur Abholung bereitliegen — derselbe Wert wie `registrationDocumentsReady` im Webhook-Ereignis. Nur bei Zulassungsvorfällen und nur in der automatisierten Bearbeitung nach einer antragsgemäßen Entscheidung. **Fehlt das Feld, ist nichts gesagt** — nicht „nicht versandt": Die Behörde führt die Angabe nicht in jeder Nachricht. Löst die abschliessende Rückmeldung weder einen Zustandswechsel noch neue Belege aus, kommt kein weiteres Ereignis; dann steht die Angabe nur hier.
parties object[]
Beteiligte laut Rückmeldung, etwa der Halter — bei allen Geschäftsvorfällen. Dieselbe Struktur wie im Webhook-Ereignis (spec/webhooks.yaml, …Party): `role` (Codeliste `rolle`, `2` ist der Halter), `roleName` (Klartext der Rolle, fehlt wenn die Nachricht keinen führt), `kind` (natural, legal, association), `name` und bei einer Vereinigung `representative`.
messages object[]
Meldungen des KBA mit Klartext und Begründung. `code` ist nicht immer ein fünfstelliger Quittungscode: Eine Ablehnung führt dort ihren kurzen Ablehnungsgrund; trägt sie keinen — der Regelfall —, steht im `code` der Antragsstatus in Worten. **Bis zum 19.08.2026 stand hier `{code, text, zusatz}`.** Geliefert wurden schon immer fünf Felder, und `zusatz` heisst in Wahrheit `additional` — Codegenerierung gegen den Vertrag erzeugte damit ein Feld, das nie befüllt wird, und übersah drei, die kommen. Die Webhook-Spezifikation beschrieb dieselbe Struktur die ganze Zeit richtig; beide sagen jetzt dasselbe, weil beide Wege dieselbe Funktion benutzen.
type* string
Herkunft der Meldung — `QUITTUNG` für jede Meldung des KBA, aus der Quittung (0002) wie aus der Entscheidung (0709).
kind enum
Quittungsart in Worten (Codeliste quittungsart 0/1/2). Fehlt bei den Ablehnungsgründen der 0709 — sie tragen keine Quittungsart.
Hinweis · Warnung · Fehler
code string
**Nicht immer fünfstellig.** Drei Ausprägungen kommen vor: der fünfstellige Quittungscode des KBA (`07077`); der kurze, numerische Ablehnungsgrund der 0709 (Codeliste `grundablehnungzulassungsantrag`, etwa `1` für Steuerrückstände, `2` für Gebührenrückstände); und — bei einer Ablehnung ohne Ablehnungsgrund, dem Regelfall — der Antragsstatus in Worten (Codeliste `statuselektronischerantrag`: neu, geprueft, wartend, weitergeleitet, bearbeitet, abgeschlossen, abgelehnt, eskaliert). Prüfen Sie den Wert nicht auf fünf Stellen.
text string
additional string
Der Zusatztext des KBA. Bei einer abgelehnten Zulassung trägt er den GRUND — die 0709 führt ihn ausdrücklich nicht.
createdAt string (date-time)
updatedAt string (date-time)
businessTransaction enum
Geschaeftsvorfall des Vorgangs — einer der sieben Codes. Wird in jeder Auskunft geliefert; derselbe Wert steht als `businessTransaction` im Webhook-Ereignis.
AB · HA · UG · WG · WZ · NZ · TZ
paymentReference string
Kassenzeichen aus dem Sammelgebuehrenbescheid (0103) — die Zahlungsreferenz. Erst gesetzt, nachdem der Bescheid eingetroffen ist. **Unabhängig von `feeAmountCents`.** Beide stammen aus demselben Bescheid, werden aber einzeln gesetzt: Ein Betrag ohne Kassenzeichen kommt vor. Wer seine Abrechnung auf „wenn `paymentReference` da, dann `feeAmountCents` lesen" baut, verliert diese Beträge.
feeAmountCents integer
Abgerechneter Betrag in ganzen Cent, aus demselben Bescheid. Kann gesetzt sein, ohne dass `paymentReference` es ist — siehe dort.
attempts object[]
**Alle Versuche dieses Auftrags** — der Weg vom Auftrag zu seinen Versuchen. `attemptOf` führt vom Ereignis oder vom Versuch zum Auftrag; dies ist die Gegenrichtung. Sie wird gebraucht, weil die **Übermittlungsgebühr je Versuch anfällt** und der Auftragskopf die Versuche mischt: `state` und `vehicleIdentificationNumber` folgen dem jüngsten Versuch, `paymentReference` und `feeAmountCents` können von einem älteren stammen. Wer über den Kopf abrechnet, bucht die Gebühr des einen und übersieht die des anderen. Die Auftragsliste (`GET …/orders`) führt ausschliesslich Auftragsköpfe — ein Versuch ist dort nicht zu finden, und einen Filter darauf gibt es nicht. Ohne dieses Feld bliebe das Webhook-Ereignis der einzige Weg an eine Versuchs-Id; damit hinge die Abrechnung wieder an dem Kanal, für dessen Ausfall die Auftragsliste gebaut wurde, und ein verlorenes Ereignis wäre dauerhaft nicht heilbar. Ältester Versuch zuerst. Bei einem Auftrag ohne Korrektur enthält die Liste genau einen Eintrag — den Auftrag selbst. Die amtlichen Gebührenangaben stehen hier unter derselben Sichtbarkeitsregel wie am Auftrag: Wer sie dort nicht sieht, sieht sie auch hier nicht.
id* integer
Id dieses Versuchs. Über `GET …/orders/{id}` abrufbar, in `GET …/orders` NICHT enthalten.
attempt* integer
state* enum
angelegt · eingereicht · inBearbeitung · weitergeleitet · beschieden · abgelehnt · fehlgeschlagen
derivedStatus* enum
PENDING · SUCCESS · FAILURE · VEHICLE_UNKNOWN · VEHICLE_ALREADY_DEREGISTERED · LICENSE_PLATE_CODE_INVALID · REGISTRATION_CERTIFICATE_CODE_INVALID · LICENSE_PLATE_CODE_QTY_INVALID · INPUT_INVALID · RESERVATION_IMPOSSIBLE · ERROR_UNHANDLED
applicationId string
Die eigene Antragsnummer dieses Versuchs. Jeder Versuch bekommt beim KBA eine neue — darüber läuft die Rückfrage.
vehicleIdentificationNumber* string
paymentReference string
feeAmountCents integer
retryable boolean
Gesetzt, wenn der Vorgang nur voruebergehend gescheitert ist (Portalausfall, Registerauskunft derzeit nicht moeglich). Derselbe Antrag hat spaeter Aussicht auf Erfolg.
holderDataProvenance object
Der Herkunftsnachweis der Halterdaten — nur bei Anträgen, die sich über `powerOfAttorney.processId` auf einen Vollmachtsvorgang mit Nachweis berufen. Der Fingerabdruck ist derselbe wie am Vollmachtsvorgang; `unchanged` ist hier immer `true`, denn eine Abweichung führt zur Ablehnung, bevor ein Vorgang entsteht.
provider enum
Der Dienst, der die Halterdaten geliefert hat.
nect-sign · nect-business-sign · yousign
providerProcessId string
Kennung des Vorgangs beim Anbieter — darüber kann er ihn im Prüfverfahren bestätigen.
verifiedAt string (date-time)
Zeitpunkt laut Anbieter (die Unterschrift); nennt er keinen, der Eingang des Ergebnisses bei uns.
identitySource string
Was der Anbieter zur Quelle meldet — bei Business Sign `Handelsregister`. Nur vorhanden, wenn er etwas nennt; Nect Sign nennt keine Ausweisart.
fingerprint string
powerOfAttorneyProcessId integer (int64)
Nur an der Vorgangsauskunft — der Vollmachtsvorgang, auf den sich der Antrag beruft.
unchanged boolean
Nur an der Vorgangsauskunft. Ob die Halterdaten des Antrags den gelieferten entsprechen. Verglichen wird, was in die XKfz-Nachricht geht; zulässig sind allein das Entfernen führender und nachgestellter Leerzeichen, die Umwandlung des Datumsformats und die Umschlüsselung des Staats von ISO „DE" auf KBA „D".
deviatingFields string[]
Nur an der Vorgangsauskunft. Leer, wenn `unchanged` — siehe oben.
checkedAt string (date-time)
Nur an der Vorgangsauskunft — Zeitpunkt des Abgleichs.
401
403
404 Vorgang unbekannt.
error* string
Fehlerbeschreibung einschließlich TraceId.
traceId string
Auch im Header X-Trace-Id enthalten. Bei Rückfragen an den Support anzugeben.
500
default
POST/vehicleHolderChanges/holderChangesHalteränderung (Adressänderung) beauftragen

Stellt den Antrag bei der GKS. Die Antwort enthält nur die Auftragsnummer — das Ergebnis kommt asynchron als Webhook-Event vom Typ `VEHICLE_HOLDER_CHANGE_XKFZ_EVENT`. Nachgewiesen wird die Berechtigung über den **Sicherheitscode der Zulassungsbescheinigung Teil I** — anders als bei der Abmeldung werden die Sicherheitscodes der Stempelplaketten NICHT geprüft und dürfen nicht mitgesendet werden: `customization.licensePlateSeals`, `frontLicensePlateSecurityCode` oder `rearLicensePlateSecurityCode` beantwortet die Schnittstelle mit 400 (`null` oder eine leere Liste gelten als nicht angegeben). Unter `vehicleHolder.address` steht die **neue** Anschrift. Der Name steht entweder als `firstName` und `lastName` (natürliche Person) oder als `companyName` (juristische Person), nie beides; Straße, Hausnummer, Postleitzahl und Ort sind Pflicht. JSON-Schema kann dieses Entweder-oder nicht als `required` ausdrücken — ein Verstoß kommt als `400` zurück. Für einen Antrag auf eine dritte Person ist `powerOfAttorney` mitzugeben (siehe `PowerOfAttorney`). Ohne Vollmacht ist nur der Antrag auf sich selbst zulässig.

Request application/json

customization* VehicleHolderChangeCustomization
vehicleIdentificationNumber* string
licensePlateNumberComponents* EuroLicensePlateNumberComponents
usageType enum
Kennzeichenmerkmal — für alle Anträge mit bisherigem Kennzeichen (AB, HA, UG, WG, WZ): EURO (Normalfall), ELECTRIC (Elektrokennzeichen) und HISTORIC (Oldtimerkennzeichen); andere Werte werden mit HTTP 400 abgewiesen.
EURO · ELECTRIC · HISTORIC
city* string
Unterscheidungszeichen, 1–3 Buchstaben (Umlaute zulässig). Kleinbuchstaben werden großgeschrieben; das Muster lässt sie deshalb zu.
middle* string
Erkennungsbuchstaben, 1–2 Buchstaben ohne Umlaute. Kleinbuchstaben werden großgeschrieben.
end* string
Erkennungsnummer, 1–4 Ziffern.
vehicleRegistrationCertificateSecurityCode* string
Siebenstelliger Sicherheitscode der ZB I — der Nachweis der Berechtigung. Die Codes der Stempelplaketten werden bei der Halteränderung NICHT geprüft.
vehicleRegistrationCertificateNumber string
Nummer der ZB I, 18–20 Zeichen, Buchstabe am Anfang. Kleinbuchstaben werden großgeschrieben — abgetippt wie gedruckt ist sie gültig.
vehicleRegistrationCertificateImprintNumber string
Druckstücknummer der ZB I, falls vorhanden. Acht Zeichen: Großbuchstabe, sechs Ziffern oder Großbuchstaben, zuletzt Ziffer oder X (Schema XKfz 6.0, Type.Druckstuecknummer).
vehicleRegistrationCertificatePartIINumber string
Wird nur auf ausdrückliche Angabe gesendet. Die Konventionstabelle des KBA führt die Vorgangskomponente bei der Halteränderung als unzulässig, die amtlichen Beispiele senden sie dennoch — beim KBA in Klärung. Kleinbuchstaben werden großgeschrieben.
deliveryToHolder boolean
Zustellung der neuen ZB I: true an den Halter, false an den Bevollmächtigten, sofern der Antrag einen nennt (sonst ebenfalls an den Halter). Ohne Angabe geht keine Lieferinformation an das KBA; es stellt dann dem Halter zu, und der Abgleich mit einer Vollmacht wertet das wie true. `deliveries` kennt die Halteränderung nicht; ein mitgeschicktes Feld wird ohne Meldung übergangen.
customerNumber string
contractPartner ContractPartner
vehicleHolder object
Der Halter mit seiner NEUEN Anschrift. Pflicht, außer bei `powerOfAttorney.processId`: Dann stammen die Halterdaten vom Vertrauensdienst, und ohne Angabe gilt, was er festgestellt hat. Mit Angabe muss die Anschrift der vom Vertrauensdienst festgestellten entsprechen, sonst 400 — die neue Anschrift ist der Antrag. Ein mitgeschickter `occupationKey` muss zum in der Vollmacht unterschriebenen Wirtschaftszweig passen, sonst ebenfalls 400.
address* HolderAddress
firstName string
lastName string
companyName string
gender enum
Nur bei natürlichen Personen zulässig.
FEMALE · MALE · DIVERSE · UNSPECIFIED
streetName string
houseNumber string
Laut XKfz-Schema NUR Ziffern, höchstens vier. Ein Zusatz wie "7a" ist dort nicht vorgesehen und gehört in addressSuffix.
zipCode string
cityName string
countryCode string
KBA-Staatsschlüssel. Ohne Angabe D.
addressSuffix string
partyType enum
Die Art des Beteiligten. **Freiwillig und zusätzlich** — ohne Angabe gilt wie bisher der Name: `companyName` heisst juristische Person, sonst natürliche Person. - `NATURAL_PERSON`, `LEGAL_PERSON` — die beiden bisherigen Arten, ausdrücklich benannt. - `AUTHORITY` — eine Behörde. Geht im XML als juristische Person hinaus; das Schema kennt keine eigene Art. - `SOLE_TRADER` — Einzelunternehmer. MIT `companyName` juristische Person, OHNE natürliche Person (amtliche Dokumentation zur Vollmacht: „Status als juristische Person wird nur dann zuerkannt, wenn ‚Name des Unternehmens' ausgefüllt ist"). Der Berufs-/Wirtschaftszweigschlüssel ist in beiden Fällen anzugeben — `888` gilt nur für Privatpersonen. - `ASSOCIATION` — eine nicht rechtsfähige Vereinigung, etwa eine GbR ohne Registereintrag oder eine Erbengemeinschaft. Geht als eigene Struktur (`NameVereinigung`) ans KBA, mit optionalem Vertreter. Ein eingetragener Verein ist dagegen eine juristische Person. Erweiterung gegenüber kennzeichen.dev.
NATURAL_PERSON · LEGAL_PERSON · AUTHORITY · SOLE_TRADER · ASSOCIATION
associationRepresentative object
Der benannte Vertreter einer Vereinigung — nur bei `partyType: ASSOCIATION` und dort freiwillig (seit XKfz 6.0 optional). In `POST /powerOfAttorneys` gibt es ihn nicht: Für eine Vereinigung lässt sich über uns keine Vollmacht unterschreiben (siehe `principal`).
firstName string
lastName string
companyName string
dateOfBirth string (date)
Streng als JJJJ-MM-TT. Nur bei natürlichen Personen. Zulässiger Bereich 1880–2099.
placeOfBirth string
Nur bei natürlichen Personen.
occupationKey string
Berufs- bzw. Wirtschaftszweigschlüssel, drei Stellen. Beim Halter einer Zulassung (UG, WG, WZ, NZ, TZ) Pflicht (KBA-Wissensartikel „Angabe des Berufsschlüssels bzw. Wirtschaftszweigs"). Firmen und juristische Personen nehmen den Schlüssel aus dem KBA-Verzeichnis SV 5, etwa `G01` für den Handel mit Kraftfahrzeugen; fehlt er, `400`. Privatpersonen ohne Angabe erhalten "888"; Freiberufler und Einzelunternehmer geben ihren Schlüssel an. Geprüft wird nur die Form. Bei der Halteränderung, beim Bevollmächtigten und beim Lieferungsempfänger optional.
powerOfAttorney PowerOfAttorney
representative HolderParty
address* HolderAddress
firstName string
lastName string
companyName string
gender enum
Nur bei natürlichen Personen zulässig.
FEMALE · MALE · DIVERSE · UNSPECIFIED
streetName string
houseNumber string
Laut XKfz-Schema NUR Ziffern, höchstens vier. Ein Zusatz wie "7a" ist dort nicht vorgesehen und gehört in addressSuffix.
zipCode string
cityName string
countryCode string
KBA-Staatsschlüssel. Ohne Angabe D.
addressSuffix string
partyType enum
Die Art des Beteiligten. **Freiwillig und zusätzlich** — ohne Angabe gilt wie bisher der Name: `companyName` heisst juristische Person, sonst natürliche Person. - `NATURAL_PERSON`, `LEGAL_PERSON` — die beiden bisherigen Arten, ausdrücklich benannt. - `AUTHORITY` — eine Behörde. Geht im XML als juristische Person hinaus; das Schema kennt keine eigene Art. - `SOLE_TRADER` — Einzelunternehmer. MIT `companyName` juristische Person, OHNE natürliche Person (amtliche Dokumentation zur Vollmacht: „Status als juristische Person wird nur dann zuerkannt, wenn ‚Name des Unternehmens' ausgefüllt ist"). Der Berufs-/Wirtschaftszweigschlüssel ist in beiden Fällen anzugeben — `888` gilt nur für Privatpersonen. - `ASSOCIATION` — eine nicht rechtsfähige Vereinigung, etwa eine GbR ohne Registereintrag oder eine Erbengemeinschaft. Geht als eigene Struktur (`NameVereinigung`) ans KBA, mit optionalem Vertreter. Ein eingetragener Verein ist dagegen eine juristische Person. Erweiterung gegenüber kennzeichen.dev.
NATURAL_PERSON · LEGAL_PERSON · AUTHORITY · SOLE_TRADER · ASSOCIATION
associationRepresentative object
Der benannte Vertreter einer Vereinigung — nur bei `partyType: ASSOCIATION` und dort freiwillig (seit XKfz 6.0 optional). In `POST /powerOfAttorneys` gibt es ihn nicht: Für eine Vereinigung lässt sich über uns keine Vollmacht unterschreiben (siehe `principal`).
firstName string
lastName string
companyName string
dateOfBirth string (date)
Streng als JJJJ-MM-TT. Nur bei natürlichen Personen. Zulässiger Bereich 1880–2099.
placeOfBirth string
Nur bei natürlichen Personen.
occupationKey string
Berufs- bzw. Wirtschaftszweigschlüssel, drei Stellen. Beim Halter einer Zulassung (UG, WG, WZ, NZ, TZ) Pflicht (KBA-Wissensartikel „Angabe des Berufsschlüssels bzw. Wirtschaftszweigs"). Firmen und juristische Personen nehmen den Schlüssel aus dem KBA-Verzeichnis SV 5, etwa `G01` für den Handel mit Kraftfahrzeugen; fehlt er, `400`. Privatpersonen ohne Angabe erhalten "888"; Freiberufler und Einzelunternehmer geben ihren Schlüssel an. Geprüft wird nur die Form. Bei der Halteränderung, beim Bevollmächtigten und beim Lieferungsempfänger optional.
documentBase64 string (byte)
Das unterschriebene Vollmacht-PDF, Base64-kodiert — selbst mitgebracht.
processId integer
Nummer eines Vollmachtsvorgangs, der über diesen Dienst unterschrieben wurde (siehe Self-Service-Bereich, „Vollmachtsvorgänge"). Wir hängen das signierte Dokument dann selbst an und gleichen die Vollmacht vorab gegen die Antragsdaten ab. Ist der Vorgang unbekannt oder gehört er einem anderen Mandanten: 404. Ist er noch nicht unterschrieben: 409, mit seinem Stand in der Meldung — und zwar vor jeder Feldprüfung: Feldfehler und der Abgleich mit der Vollmacht melden sich erst nach der Unterschrift. Ein 400 danach verbraucht den Vorgang nicht; der korrigierte Antrag darf dieselbe processId nennen.
email* string (email)
externalOrderId string
Ihre eigene Auftragsreferenz. Wird in Webhook-Events zurückgegeben — und ist zugleich der Schutz gegen den doppelt gestellten Antrag: Derselbe Mandant, dieselbe `externalOrderId`, dieselbe FIN UND derselbe Geschäftsvorfall (Endpunkt) innerhalb von 15 Minuten gelten als Wiederholungsversuch. Es geht dann NICHTS erneut an das KBA, und die Antwort nennt den bestehenden Vorgang (HTTP 200, dieselbe `order.id`). So führt eine Zeitüberschreitung samt automatischer Wiederholung Ihres Clients nicht zu zwei Anträgen und zwei Gebühren. Ohne Referenz greift der Schutz nicht — dann fehlt die Aussage „das ist derselbe Auftrag". **Weichen die Daten ab, ist es kein Wiederholungsversuch:** Dieselbe Referenz und FIN mit geändertem Inhalt beantwortet der Dienst mit **409** und ändert nichts. Weder darf er die Korrektur still verwerfen noch ungefragt einen zweiten Antrag samt Gebühr auslösen. Für einen weiteren Antrag eine eigene Referenz vergeben; für eine Berichtigung den bestehenden Vorgang korrigieren. **Dieselbe Referenz an einem anderen Endpunkt** — etwa NZ statt TZ oder WG statt WZ — ist kein Wiederholungsversuch, sondern ein neuer Antrag samt Gebühr. Ein falsch gewählter Endpunkt lässt sich nicht durch erneutes Senden unter derselben Referenz berichtigen.
correctionOf integer (int64)
Vorgangsnummer eines abgewiesenen oder fehlgeschlagenen Auftrags, der mit diesem Rumpf korrigiert werden soll. Es entsteht ein neuer KBA-Versuch am selben Auftrag; die Antwort nennt `attemptOf` und `attempt`. Laufende oder beschiedene Aufträge sowie ein anderer Geschäftsvorfall ergeben 409.
gksConfigurationId string (uuid)
{
  "externalOrderId": "umzug-4711",
  "email": "kunde@example.de",
  "customization": {
    "licensePlateNumberComponents": {
      "usageType": "EURO",
      "city": "HN",
      "middle": "LL",
      "end": "2418"
    },
    "vehicleIdentificationNumber": "WBA65432113218654",
    "vehicleRegistrationCertificateSecurityCode": "8407251",
    "vehicleRegistrationCertificateNumber": "HN-K-0-215/21-00008",
    "deliveryToHolder": true
  },
  "vehicleHolder": {
    "address": {
      "firstName": "Max",
      "lastName": "Muster",
      "gender": "MALE",
      "streetName": "Neue Straße",
      "houseNumber": "7",
      "zipCode": "74072",
      "cityName": "Heilbronn",
      "countryCode": "D"
    },
    "dateOfBirth": "1980-05-04",
    "placeOfBirth": "Heilbronn"
  }
}

Antworten

200 Der Antrag wurde angenommen.
order* object
id* integer (int64)
attemptOf integer (int64)
Nur bei einer Korrektur — die Auftragsnummer der Versuchskette.
attempt integer
Nur bei einer Korrektur — die laufende Nummer des neuen Versuchs.
{
  "order": {
    "id": 1
  }
}
400
401
403
404
409
413
415
500
503
default
GET/vehicleHolderChanges/ordersDie eigenen Aufträge auflisten

Alle `…/orders`-Pfade liefern dieselbe Liste, unabhängig vom Geschäftsvorfall — welcher es ist, nennt das Feld `businessTransaction`, und danach grenzt der gleichnamige Filter ein. Der Pfad, unter dem Sie fragen, ändert die Antwort nicht; er ist nur dort einsortiert, wo Sie ihn suchen. Filter, Grenzen und Zähler stehen bei `/vehicleDeregistrations/orders`.

Parameter

externalIdquery
statequeryEiner oder mehrere, mit Komma verbunden. Siehe `/vehicleDeregistrations/orders`.
businessTransactionqueryEiner oder mehrere, mit Komma verbunden; unbekannt oder leer ⇒ 400. Siehe `/vehicleDeregistrations/orders`.
createdSincequery
changedSincequery
limitquery
offsetquery

Antworten

200 Die Aufträge, neueste zuerst.
orders* VehicleDeregistrationOrderSummary[]
order object
id integer
externalId string
attemptOf integer
Id des Auftrags. In dieser Liste stehen nur Auftragsköpfe, also immer die eigene Id.
businessTransaction string
state enum
angelegt · eingereicht · inBearbeitung · weitergeleitet · beschieden · abgelehnt · fehlgeschlagen
derivedStatus enum
PENDING · SUCCESS · FAILURE · VEHICLE_UNKNOWN · VEHICLE_ALREADY_DEREGISTERED · LICENSE_PLATE_CODE_INVALID · REGISTRATION_CERTIFICATE_CODE_INVALID · LICENSE_PLATE_CODE_QTY_INVALID · INPUT_INVALID · RESERVATION_IMPOSSIBLE · ERROR_UNHANDLED
applicationId string
vehicleIdentificationNumber string
licensePlate string
createdAt string (date-time)
changedAt string (date-time)
Der Wert, gegen den `changedSince` filtert.
limit* integer
Das angewandte Limit. Höchstens 200, auch wenn Sie mehr anfragen.
offset* integer
total* integer
Wie viele Aufträge der Filter insgesamt trifft — nicht die Seitengröße.
hasMore* boolean
Ob nach dieser Seite noch etwas kommt. Steht ausdrücklich da, statt sie aus `total > offset + limit` ableiten zu lassen: Diese Rechnung stellt jeder Aufrufer selbst an, und einer stellt sie falsch.
400 Ein Filterwert war unbrauchbar.
401
403
500
default
GET/vehicleHolderChanges/orders/{orderId}Auskunft zu einem Vorgang

Alle `…/orders/{orderId}`-Pfade liefern dieselbe Auskunft zu jedem Vorgang, unabhängig vom Geschäftsvorfall — welcher es ist, nennt das Feld `businessTransaction`. Der Pfad, unter dem Sie fragen, ändert die Antwort nicht; er ist nur dort einsortiert, wo Sie ihn suchen.

Parameter

orderId*path

Antworten

200 Aktueller Stand des Vorgangs
order object
id integer
Vorgangsnummer in diesem System.
externalId string
Ihre eigene Referenz aus dem Antrag.
attempt integer
Laufende Nummer des Versuchs. Ein korrigierter Antrag entsteht als NEUER Vorgang mit derselben `externalId` — beim KBA ist jeder Versuch ein eigener Antrag mit eigener Antragsnummer.
attemptOf integer
Id des Auftrags, zu dem dieser Versuch gehört; beim ersten Versuch die eigene Id. **Wer über die Schnittstelle abrechnet, gruppiert danach** — sonst zählt derselbe Auftrag mehrfach. Abgerechnet wird er einmal (die Übermittlungsgebühr je abgewiesenem Versuch bleibt davon unberührt).
state enum
Der Stand des Vorgangs. **Endzustand heisst: Endzustand des VERSUCHS, nicht des Auftrags.** `beschieden`, `abgelehnt` und `fehlgeschlagen` beenden den einzelnen Antrag beim KBA. Der Auftrag darüber kann weitergehen: Wird ein abgewiesener Antrag korrigiert, entsteht ein zweiter Versuch, und der Auftragskopf folgt dem jüngsten — er wechselt dann von `fehlgeschlagen` zurück nach `inBearbeitung`. Wer auf „Endzustand" vertraut und den Auftrag in seinem System abschliesst, verpasst die Korrektur und meldet ein Fahrzeug als nicht abgemeldet, obwohl es abgemeldet wird. Der Rücksprung sieht dabei aus wie ein Fehler des Systems und ist keiner. Fragen Sie den Versuch ab, wenn Sie einen Endzustand brauchen — `attempt` und `attemptOf` sagen Ihnen, was Sie vor sich haben. Die Webhook-Ereignisse führen für denselben Sachverhalt eigene, englische Werte (`ACCEPTED`, `APPROVED_WITH_DOCUMENTS`, `REJECTED_WITH_DOCUMENTS`) samt `derivedStatus`.
angelegt · eingereicht · inBearbeitung · weitergeleitet · beschieden · abgelehnt · fehlgeschlagen
derivedStatus enum
Die grobe Einordnung: läuft noch, erledigt, gescheitert. `state` hat sieben Werte, und welche davon Endzustände sind, steht in dieser Spezifikation — ein Aufrufer müsste die Liste bei jeder Erweiterung nachziehen. Wenn Ihr System nur wissen will, ob es weiter warten muss, werten Sie dieses Feld aus. Es ist dieselbe Abbildung, die auch das Webhook-Ereignis führt.
PENDING · SUCCESS · FAILURE · VEHICLE_UNKNOWN · VEHICLE_ALREADY_DEREGISTERED · LICENSE_PLATE_CODE_INVALID · REGISTRATION_CERTIFICATE_CODE_INVALID · LICENSE_PLATE_CODE_QTY_INVALID · INPUT_INVALID · RESERVATION_IMPOSSIBLE · ERROR_UNHANDLED
applicationId string
Antragsnummer des KBA — der Schlüssel für jede Rückfrage dort. Erst gesetzt, nachdem die Quittung eingetroffen ist; bei einem Antrag, der das KBA nicht erreicht hat, bleibt sie leer.
vehicleIdentificationNumber string
Die FIN des Vorgangs, immer in Großschreibung. **Am Auftragskopf kann sie sich ändern.** Eine Korrektur darf eine falsch abgetippte FIN berichtigen; der Kopf folgt dem jüngsten Versuch und trägt danach die neue. Die `externalId` bleibt dabei dieselbe. Wer Fahrzeuge über die FIN führt, sollte das wissen — sonst liest es sich wie eine Verwechslung von Fahrzeugen.
licensePlate string
Kennzeichen in der Anzeigeform, z. B. `HN-LL 2418`.
files object[]
Belege aus dem Rückkanal. Der Gebührenbescheid erscheint nur, wenn Sie selbst beim KBA registriert sind. Am Auftragskopf stehen die Belege aller Versuche (Kopf und `attempts[].id`), ohne Dubletten und in der Reihenfolge ihres Eingangs; die Auskunft zu einer Versuchs-Id führt nur dessen eigene.
purposeType string
mediaType string
fileAccessKey string
Einzulösen über `/vehicleDeregistrations/files/content/{fileAccessKey}`.
expirationTime string (date-time)
Bis dahin ist der Schlüssel gültig — beim Ablegen eines Vorgangsbelegs 72 Stunden; danach im Self-Service erneut freigeben. **Format:** vollständiger ISO-8601-Zeitstempel MIT Zonenangabe und Millisekunden (`2026-09-19T14:38:22.558Z`). Das Webhook-Ereignis nennt denselben Zeitpunkt als `LocalDateTime` — in UTC, aber ohne Zone und sekundengenau (`2026-09-19T14:38:22`); dieses Format schreibt der Webhook-Vertrag vor (`spec/webhooks.yaml`, Vorbild kennzeichen.dev). Wer beide Quellen vergleicht, liest den Wert des Ereignisses als UTC.
filename string
Der Name, unter dem der Abruf die Datei ausliefert (`Content-Disposition`), z. B. `Vorgang-17_KBA-NZ-123_Zulassungsbescheid.pdf`. Zwei Belege mit `purposeType: CERTIFICATE` — Zulassungsbescheid und vorläufiger Zulassungsnachweis — sind daran zu unterscheiden.
costBreakdown object
Die Gebührenaufstellung aus der Entscheidung (0709) — derselbe Wert wie `costBreakdown` im Webhook-Ereignis, für den Abgleich nach einem verlorenen Ereignis. **Nur bei eigener KBA-Registrierung** (Selbstabrechner); ein Vertragspartner unter unserer Registrierung sieht die amtlichen Beträge weder hier noch im Ereignis noch im Dashboard. Fehlt, solange keine Entscheidung vorliegt.
kbaCost integer
Nutzungsgebühr des KBA nach Nr. 129 GebOSt, in Cent. Steht da, wenn das KBA sie mit Quittungscode 07085 angekündigt hat oder der Antrag beschieden bzw. abgelehnt ist; sonst fehlt das Feld.
registrationOfficeCosts object
items* VehicleDeregistrationOrderCostBreakdownItem[]
number* integer
code string
Gebührennummer nach GebOSt, z. B. 224.2.
name string
amount* integer
Betrag in kleinster Währungseinheit (Cent).
note string
total* VehicleDeregistrationOrderCostBreakdownItem
number* integer
code string
Gebührennummer nach GebOSt, z. B. 224.2.
name string
amount* integer
Betrag in kleinster Währungseinheit (Cent).
note string
registrationData object
Über sechzig Angaben aus den Zulassungsbescheinigungen, sofern die Rückmeldung sie führt.
registrationDocumentsReady boolean
Erweiterung gegenüber kennzeichen.dev. `true`, wenn die Zulassungsbehörde meldet, dass die Zulassungsunterlagen (ZB I, ZB II, Stempelplaketten, Feinstaubplakette) wie gewünscht versandt wurden oder zur Abholung bereitliegen — derselbe Wert wie `registrationDocumentsReady` im Webhook-Ereignis. Nur bei Zulassungsvorfällen und nur in der automatisierten Bearbeitung nach einer antragsgemäßen Entscheidung. **Fehlt das Feld, ist nichts gesagt** — nicht „nicht versandt": Die Behörde führt die Angabe nicht in jeder Nachricht. Löst die abschliessende Rückmeldung weder einen Zustandswechsel noch neue Belege aus, kommt kein weiteres Ereignis; dann steht die Angabe nur hier.
parties object[]
Beteiligte laut Rückmeldung, etwa der Halter — bei allen Geschäftsvorfällen. Dieselbe Struktur wie im Webhook-Ereignis (spec/webhooks.yaml, …Party): `role` (Codeliste `rolle`, `2` ist der Halter), `roleName` (Klartext der Rolle, fehlt wenn die Nachricht keinen führt), `kind` (natural, legal, association), `name` und bei einer Vereinigung `representative`.
messages object[]
Meldungen des KBA mit Klartext und Begründung. `code` ist nicht immer ein fünfstelliger Quittungscode: Eine Ablehnung führt dort ihren kurzen Ablehnungsgrund; trägt sie keinen — der Regelfall —, steht im `code` der Antragsstatus in Worten. **Bis zum 19.08.2026 stand hier `{code, text, zusatz}`.** Geliefert wurden schon immer fünf Felder, und `zusatz` heisst in Wahrheit `additional` — Codegenerierung gegen den Vertrag erzeugte damit ein Feld, das nie befüllt wird, und übersah drei, die kommen. Die Webhook-Spezifikation beschrieb dieselbe Struktur die ganze Zeit richtig; beide sagen jetzt dasselbe, weil beide Wege dieselbe Funktion benutzen.
type* string
Herkunft der Meldung — `QUITTUNG` für jede Meldung des KBA, aus der Quittung (0002) wie aus der Entscheidung (0709).
kind enum
Quittungsart in Worten (Codeliste quittungsart 0/1/2). Fehlt bei den Ablehnungsgründen der 0709 — sie tragen keine Quittungsart.
Hinweis · Warnung · Fehler
code string
**Nicht immer fünfstellig.** Drei Ausprägungen kommen vor: der fünfstellige Quittungscode des KBA (`07077`); der kurze, numerische Ablehnungsgrund der 0709 (Codeliste `grundablehnungzulassungsantrag`, etwa `1` für Steuerrückstände, `2` für Gebührenrückstände); und — bei einer Ablehnung ohne Ablehnungsgrund, dem Regelfall — der Antragsstatus in Worten (Codeliste `statuselektronischerantrag`: neu, geprueft, wartend, weitergeleitet, bearbeitet, abgeschlossen, abgelehnt, eskaliert). Prüfen Sie den Wert nicht auf fünf Stellen.
text string
additional string
Der Zusatztext des KBA. Bei einer abgelehnten Zulassung trägt er den GRUND — die 0709 führt ihn ausdrücklich nicht.
createdAt string (date-time)
updatedAt string (date-time)
businessTransaction enum
Geschaeftsvorfall des Vorgangs — einer der sieben Codes. Wird in jeder Auskunft geliefert; derselbe Wert steht als `businessTransaction` im Webhook-Ereignis.
AB · HA · UG · WG · WZ · NZ · TZ
paymentReference string
Kassenzeichen aus dem Sammelgebuehrenbescheid (0103) — die Zahlungsreferenz. Erst gesetzt, nachdem der Bescheid eingetroffen ist. **Unabhängig von `feeAmountCents`.** Beide stammen aus demselben Bescheid, werden aber einzeln gesetzt: Ein Betrag ohne Kassenzeichen kommt vor. Wer seine Abrechnung auf „wenn `paymentReference` da, dann `feeAmountCents` lesen" baut, verliert diese Beträge.
feeAmountCents integer
Abgerechneter Betrag in ganzen Cent, aus demselben Bescheid. Kann gesetzt sein, ohne dass `paymentReference` es ist — siehe dort.
attempts object[]
**Alle Versuche dieses Auftrags** — der Weg vom Auftrag zu seinen Versuchen. `attemptOf` führt vom Ereignis oder vom Versuch zum Auftrag; dies ist die Gegenrichtung. Sie wird gebraucht, weil die **Übermittlungsgebühr je Versuch anfällt** und der Auftragskopf die Versuche mischt: `state` und `vehicleIdentificationNumber` folgen dem jüngsten Versuch, `paymentReference` und `feeAmountCents` können von einem älteren stammen. Wer über den Kopf abrechnet, bucht die Gebühr des einen und übersieht die des anderen. Die Auftragsliste (`GET …/orders`) führt ausschliesslich Auftragsköpfe — ein Versuch ist dort nicht zu finden, und einen Filter darauf gibt es nicht. Ohne dieses Feld bliebe das Webhook-Ereignis der einzige Weg an eine Versuchs-Id; damit hinge die Abrechnung wieder an dem Kanal, für dessen Ausfall die Auftragsliste gebaut wurde, und ein verlorenes Ereignis wäre dauerhaft nicht heilbar. Ältester Versuch zuerst. Bei einem Auftrag ohne Korrektur enthält die Liste genau einen Eintrag — den Auftrag selbst. Die amtlichen Gebührenangaben stehen hier unter derselben Sichtbarkeitsregel wie am Auftrag: Wer sie dort nicht sieht, sieht sie auch hier nicht.
id* integer
Id dieses Versuchs. Über `GET …/orders/{id}` abrufbar, in `GET …/orders` NICHT enthalten.
attempt* integer
state* enum
angelegt · eingereicht · inBearbeitung · weitergeleitet · beschieden · abgelehnt · fehlgeschlagen
derivedStatus* enum
PENDING · SUCCESS · FAILURE · VEHICLE_UNKNOWN · VEHICLE_ALREADY_DEREGISTERED · LICENSE_PLATE_CODE_INVALID · REGISTRATION_CERTIFICATE_CODE_INVALID · LICENSE_PLATE_CODE_QTY_INVALID · INPUT_INVALID · RESERVATION_IMPOSSIBLE · ERROR_UNHANDLED
applicationId string
Die eigene Antragsnummer dieses Versuchs. Jeder Versuch bekommt beim KBA eine neue — darüber läuft die Rückfrage.
vehicleIdentificationNumber* string
paymentReference string
feeAmountCents integer
retryable boolean
Gesetzt, wenn der Vorgang nur voruebergehend gescheitert ist (Portalausfall, Registerauskunft derzeit nicht moeglich). Derselbe Antrag hat spaeter Aussicht auf Erfolg.
holderDataProvenance object
Der Herkunftsnachweis der Halterdaten — nur bei Anträgen, die sich über `powerOfAttorney.processId` auf einen Vollmachtsvorgang mit Nachweis berufen. Der Fingerabdruck ist derselbe wie am Vollmachtsvorgang; `unchanged` ist hier immer `true`, denn eine Abweichung führt zur Ablehnung, bevor ein Vorgang entsteht.
provider enum
Der Dienst, der die Halterdaten geliefert hat.
nect-sign · nect-business-sign · yousign
providerProcessId string
Kennung des Vorgangs beim Anbieter — darüber kann er ihn im Prüfverfahren bestätigen.
verifiedAt string (date-time)
Zeitpunkt laut Anbieter (die Unterschrift); nennt er keinen, der Eingang des Ergebnisses bei uns.
identitySource string
Was der Anbieter zur Quelle meldet — bei Business Sign `Handelsregister`. Nur vorhanden, wenn er etwas nennt; Nect Sign nennt keine Ausweisart.
fingerprint string
powerOfAttorneyProcessId integer (int64)
Nur an der Vorgangsauskunft — der Vollmachtsvorgang, auf den sich der Antrag beruft.
unchanged boolean
Nur an der Vorgangsauskunft. Ob die Halterdaten des Antrags den gelieferten entsprechen. Verglichen wird, was in die XKfz-Nachricht geht; zulässig sind allein das Entfernen führender und nachgestellter Leerzeichen, die Umwandlung des Datumsformats und die Umschlüsselung des Staats von ISO „DE" auf KBA „D".
deviatingFields string[]
Nur an der Vorgangsauskunft. Leer, wenn `unchanged` — siehe oben.
checkedAt string (date-time)
Nur an der Vorgangsauskunft — Zeitpunkt des Abgleichs.
401
403
404 Vorgang unbekannt.
error* string
Fehlerbeschreibung einschließlich TraceId.
traceId string
Auch im Header X-Trace-Id enthalten. Bei Rückfragen an den Support anzugeben.
500
default
GET/vehicleHolderChanges/files/content/{fileAccessKey}Beleg abrufen

Identisch zu `/vehicleDeregistrations/files/content/{fileAccessKey}`. Der Abruf hängt am Zugriffsschlüssel, nicht am Geschäftsvorfall.

Parameter

fileAccessKey*path

Antworten

200 Der Beleg als Datei.

Schema: string (binary)

401
403
404 Schlüssel unbekannt oder abgelaufen.
error* string
Fehlerbeschreibung einschließlich TraceId.
traceId string
Auch im Header X-Trace-Id enthalten. Bei Rückfragen an den Support anzugeben.
500
default
GET/vehicleTransfers/ordersDie eigenen Aufträge auflisten

Alle `…/orders`-Pfade liefern dieselbe Liste, unabhängig vom Geschäftsvorfall — welcher es ist, nennt das Feld `businessTransaction`, und danach grenzt der gleichnamige Filter ein. Der Pfad, unter dem Sie fragen, ändert die Antwort nicht; er ist nur dort einsortiert, wo Sie ihn suchen. Filter, Grenzen und Zähler stehen bei `/vehicleDeregistrations/orders`.

Parameter

externalIdquery
statequeryEiner oder mehrere, mit Komma verbunden. Siehe `/vehicleDeregistrations/orders`.
businessTransactionqueryEiner oder mehrere, mit Komma verbunden; unbekannt oder leer ⇒ 400. Siehe `/vehicleDeregistrations/orders`.
createdSincequery
changedSincequery
limitquery
offsetquery

Antworten

200 Die Aufträge, neueste zuerst.
orders* VehicleDeregistrationOrderSummary[]
order object
id integer
externalId string
attemptOf integer
Id des Auftrags. In dieser Liste stehen nur Auftragsköpfe, also immer die eigene Id.
businessTransaction string
state enum
angelegt · eingereicht · inBearbeitung · weitergeleitet · beschieden · abgelehnt · fehlgeschlagen
derivedStatus enum
PENDING · SUCCESS · FAILURE · VEHICLE_UNKNOWN · VEHICLE_ALREADY_DEREGISTERED · LICENSE_PLATE_CODE_INVALID · REGISTRATION_CERTIFICATE_CODE_INVALID · LICENSE_PLATE_CODE_QTY_INVALID · INPUT_INVALID · RESERVATION_IMPOSSIBLE · ERROR_UNHANDLED
applicationId string
vehicleIdentificationNumber string
licensePlate string
createdAt string (date-time)
changedAt string (date-time)
Der Wert, gegen den `changedSince` filtert.
limit* integer
Das angewandte Limit. Höchstens 200, auch wenn Sie mehr anfragen.
offset* integer
total* integer
Wie viele Aufträge der Filter insgesamt trifft — nicht die Seitengröße.
hasMore* boolean
Ob nach dieser Seite noch etwas kommt. Steht ausdrücklich da, statt sie aus `total > offset + limit` ableiten zu lassen: Diese Rechnung stellt jeder Aufrufer selbst an, und einer stellt sie falsch.
400 Ein Filterwert war unbrauchbar.
401
403
500
default
GET/vehicleTransfers/orders/{orderId}Auskunft zu einem Vorgang

Alle `…/orders/{orderId}`-Pfade liefern dieselbe Auskunft zu jedem Vorgang, unabhängig vom Geschäftsvorfall — welcher es ist, nennt das Feld `businessTransaction`. Der Pfad, unter dem Sie fragen, ändert die Antwort nicht; er ist nur dort einsortiert, wo Sie ihn suchen.

Parameter

orderId*path

Antworten

200 Aktueller Stand des Vorgangs
order object
id integer
Vorgangsnummer in diesem System.
externalId string
Ihre eigene Referenz aus dem Antrag.
attempt integer
Laufende Nummer des Versuchs. Ein korrigierter Antrag entsteht als NEUER Vorgang mit derselben `externalId` — beim KBA ist jeder Versuch ein eigener Antrag mit eigener Antragsnummer.
attemptOf integer
Id des Auftrags, zu dem dieser Versuch gehört; beim ersten Versuch die eigene Id. **Wer über die Schnittstelle abrechnet, gruppiert danach** — sonst zählt derselbe Auftrag mehrfach. Abgerechnet wird er einmal (die Übermittlungsgebühr je abgewiesenem Versuch bleibt davon unberührt).
state enum
Der Stand des Vorgangs. **Endzustand heisst: Endzustand des VERSUCHS, nicht des Auftrags.** `beschieden`, `abgelehnt` und `fehlgeschlagen` beenden den einzelnen Antrag beim KBA. Der Auftrag darüber kann weitergehen: Wird ein abgewiesener Antrag korrigiert, entsteht ein zweiter Versuch, und der Auftragskopf folgt dem jüngsten — er wechselt dann von `fehlgeschlagen` zurück nach `inBearbeitung`. Wer auf „Endzustand" vertraut und den Auftrag in seinem System abschliesst, verpasst die Korrektur und meldet ein Fahrzeug als nicht abgemeldet, obwohl es abgemeldet wird. Der Rücksprung sieht dabei aus wie ein Fehler des Systems und ist keiner. Fragen Sie den Versuch ab, wenn Sie einen Endzustand brauchen — `attempt` und `attemptOf` sagen Ihnen, was Sie vor sich haben. Die Webhook-Ereignisse führen für denselben Sachverhalt eigene, englische Werte (`ACCEPTED`, `APPROVED_WITH_DOCUMENTS`, `REJECTED_WITH_DOCUMENTS`) samt `derivedStatus`.
angelegt · eingereicht · inBearbeitung · weitergeleitet · beschieden · abgelehnt · fehlgeschlagen
derivedStatus enum
Die grobe Einordnung: läuft noch, erledigt, gescheitert. `state` hat sieben Werte, und welche davon Endzustände sind, steht in dieser Spezifikation — ein Aufrufer müsste die Liste bei jeder Erweiterung nachziehen. Wenn Ihr System nur wissen will, ob es weiter warten muss, werten Sie dieses Feld aus. Es ist dieselbe Abbildung, die auch das Webhook-Ereignis führt.
PENDING · SUCCESS · FAILURE · VEHICLE_UNKNOWN · VEHICLE_ALREADY_DEREGISTERED · LICENSE_PLATE_CODE_INVALID · REGISTRATION_CERTIFICATE_CODE_INVALID · LICENSE_PLATE_CODE_QTY_INVALID · INPUT_INVALID · RESERVATION_IMPOSSIBLE · ERROR_UNHANDLED
applicationId string
Antragsnummer des KBA — der Schlüssel für jede Rückfrage dort. Erst gesetzt, nachdem die Quittung eingetroffen ist; bei einem Antrag, der das KBA nicht erreicht hat, bleibt sie leer.
vehicleIdentificationNumber string
Die FIN des Vorgangs, immer in Großschreibung. **Am Auftragskopf kann sie sich ändern.** Eine Korrektur darf eine falsch abgetippte FIN berichtigen; der Kopf folgt dem jüngsten Versuch und trägt danach die neue. Die `externalId` bleibt dabei dieselbe. Wer Fahrzeuge über die FIN führt, sollte das wissen — sonst liest es sich wie eine Verwechslung von Fahrzeugen.
licensePlate string
Kennzeichen in der Anzeigeform, z. B. `HN-LL 2418`.
files object[]
Belege aus dem Rückkanal. Der Gebührenbescheid erscheint nur, wenn Sie selbst beim KBA registriert sind. Am Auftragskopf stehen die Belege aller Versuche (Kopf und `attempts[].id`), ohne Dubletten und in der Reihenfolge ihres Eingangs; die Auskunft zu einer Versuchs-Id führt nur dessen eigene.
purposeType string
mediaType string
fileAccessKey string
Einzulösen über `/vehicleDeregistrations/files/content/{fileAccessKey}`.
expirationTime string (date-time)
Bis dahin ist der Schlüssel gültig — beim Ablegen eines Vorgangsbelegs 72 Stunden; danach im Self-Service erneut freigeben. **Format:** vollständiger ISO-8601-Zeitstempel MIT Zonenangabe und Millisekunden (`2026-09-19T14:38:22.558Z`). Das Webhook-Ereignis nennt denselben Zeitpunkt als `LocalDateTime` — in UTC, aber ohne Zone und sekundengenau (`2026-09-19T14:38:22`); dieses Format schreibt der Webhook-Vertrag vor (`spec/webhooks.yaml`, Vorbild kennzeichen.dev). Wer beide Quellen vergleicht, liest den Wert des Ereignisses als UTC.
filename string
Der Name, unter dem der Abruf die Datei ausliefert (`Content-Disposition`), z. B. `Vorgang-17_KBA-NZ-123_Zulassungsbescheid.pdf`. Zwei Belege mit `purposeType: CERTIFICATE` — Zulassungsbescheid und vorläufiger Zulassungsnachweis — sind daran zu unterscheiden.
costBreakdown object
Die Gebührenaufstellung aus der Entscheidung (0709) — derselbe Wert wie `costBreakdown` im Webhook-Ereignis, für den Abgleich nach einem verlorenen Ereignis. **Nur bei eigener KBA-Registrierung** (Selbstabrechner); ein Vertragspartner unter unserer Registrierung sieht die amtlichen Beträge weder hier noch im Ereignis noch im Dashboard. Fehlt, solange keine Entscheidung vorliegt.
kbaCost integer
Nutzungsgebühr des KBA nach Nr. 129 GebOSt, in Cent. Steht da, wenn das KBA sie mit Quittungscode 07085 angekündigt hat oder der Antrag beschieden bzw. abgelehnt ist; sonst fehlt das Feld.
registrationOfficeCosts object
items* VehicleDeregistrationOrderCostBreakdownItem[]
number* integer
code string
Gebührennummer nach GebOSt, z. B. 224.2.
name string
amount* integer
Betrag in kleinster Währungseinheit (Cent).
note string
total* VehicleDeregistrationOrderCostBreakdownItem
number* integer
code string
Gebührennummer nach GebOSt, z. B. 224.2.
name string
amount* integer
Betrag in kleinster Währungseinheit (Cent).
note string
registrationData object
Über sechzig Angaben aus den Zulassungsbescheinigungen, sofern die Rückmeldung sie führt.
registrationDocumentsReady boolean
Erweiterung gegenüber kennzeichen.dev. `true`, wenn die Zulassungsbehörde meldet, dass die Zulassungsunterlagen (ZB I, ZB II, Stempelplaketten, Feinstaubplakette) wie gewünscht versandt wurden oder zur Abholung bereitliegen — derselbe Wert wie `registrationDocumentsReady` im Webhook-Ereignis. Nur bei Zulassungsvorfällen und nur in der automatisierten Bearbeitung nach einer antragsgemäßen Entscheidung. **Fehlt das Feld, ist nichts gesagt** — nicht „nicht versandt": Die Behörde führt die Angabe nicht in jeder Nachricht. Löst die abschliessende Rückmeldung weder einen Zustandswechsel noch neue Belege aus, kommt kein weiteres Ereignis; dann steht die Angabe nur hier.
parties object[]
Beteiligte laut Rückmeldung, etwa der Halter — bei allen Geschäftsvorfällen. Dieselbe Struktur wie im Webhook-Ereignis (spec/webhooks.yaml, …Party): `role` (Codeliste `rolle`, `2` ist der Halter), `roleName` (Klartext der Rolle, fehlt wenn die Nachricht keinen führt), `kind` (natural, legal, association), `name` und bei einer Vereinigung `representative`.
messages object[]
Meldungen des KBA mit Klartext und Begründung. `code` ist nicht immer ein fünfstelliger Quittungscode: Eine Ablehnung führt dort ihren kurzen Ablehnungsgrund; trägt sie keinen — der Regelfall —, steht im `code` der Antragsstatus in Worten. **Bis zum 19.08.2026 stand hier `{code, text, zusatz}`.** Geliefert wurden schon immer fünf Felder, und `zusatz` heisst in Wahrheit `additional` — Codegenerierung gegen den Vertrag erzeugte damit ein Feld, das nie befüllt wird, und übersah drei, die kommen. Die Webhook-Spezifikation beschrieb dieselbe Struktur die ganze Zeit richtig; beide sagen jetzt dasselbe, weil beide Wege dieselbe Funktion benutzen.
type* string
Herkunft der Meldung — `QUITTUNG` für jede Meldung des KBA, aus der Quittung (0002) wie aus der Entscheidung (0709).
kind enum
Quittungsart in Worten (Codeliste quittungsart 0/1/2). Fehlt bei den Ablehnungsgründen der 0709 — sie tragen keine Quittungsart.
Hinweis · Warnung · Fehler
code string
**Nicht immer fünfstellig.** Drei Ausprägungen kommen vor: der fünfstellige Quittungscode des KBA (`07077`); der kurze, numerische Ablehnungsgrund der 0709 (Codeliste `grundablehnungzulassungsantrag`, etwa `1` für Steuerrückstände, `2` für Gebührenrückstände); und — bei einer Ablehnung ohne Ablehnungsgrund, dem Regelfall — der Antragsstatus in Worten (Codeliste `statuselektronischerantrag`: neu, geprueft, wartend, weitergeleitet, bearbeitet, abgeschlossen, abgelehnt, eskaliert). Prüfen Sie den Wert nicht auf fünf Stellen.
text string
additional string
Der Zusatztext des KBA. Bei einer abgelehnten Zulassung trägt er den GRUND — die 0709 führt ihn ausdrücklich nicht.
createdAt string (date-time)
updatedAt string (date-time)
businessTransaction enum
Geschaeftsvorfall des Vorgangs — einer der sieben Codes. Wird in jeder Auskunft geliefert; derselbe Wert steht als `businessTransaction` im Webhook-Ereignis.
AB · HA · UG · WG · WZ · NZ · TZ
paymentReference string
Kassenzeichen aus dem Sammelgebuehrenbescheid (0103) — die Zahlungsreferenz. Erst gesetzt, nachdem der Bescheid eingetroffen ist. **Unabhängig von `feeAmountCents`.** Beide stammen aus demselben Bescheid, werden aber einzeln gesetzt: Ein Betrag ohne Kassenzeichen kommt vor. Wer seine Abrechnung auf „wenn `paymentReference` da, dann `feeAmountCents` lesen" baut, verliert diese Beträge.
feeAmountCents integer
Abgerechneter Betrag in ganzen Cent, aus demselben Bescheid. Kann gesetzt sein, ohne dass `paymentReference` es ist — siehe dort.
attempts object[]
**Alle Versuche dieses Auftrags** — der Weg vom Auftrag zu seinen Versuchen. `attemptOf` führt vom Ereignis oder vom Versuch zum Auftrag; dies ist die Gegenrichtung. Sie wird gebraucht, weil die **Übermittlungsgebühr je Versuch anfällt** und der Auftragskopf die Versuche mischt: `state` und `vehicleIdentificationNumber` folgen dem jüngsten Versuch, `paymentReference` und `feeAmountCents` können von einem älteren stammen. Wer über den Kopf abrechnet, bucht die Gebühr des einen und übersieht die des anderen. Die Auftragsliste (`GET …/orders`) führt ausschliesslich Auftragsköpfe — ein Versuch ist dort nicht zu finden, und einen Filter darauf gibt es nicht. Ohne dieses Feld bliebe das Webhook-Ereignis der einzige Weg an eine Versuchs-Id; damit hinge die Abrechnung wieder an dem Kanal, für dessen Ausfall die Auftragsliste gebaut wurde, und ein verlorenes Ereignis wäre dauerhaft nicht heilbar. Ältester Versuch zuerst. Bei einem Auftrag ohne Korrektur enthält die Liste genau einen Eintrag — den Auftrag selbst. Die amtlichen Gebührenangaben stehen hier unter derselben Sichtbarkeitsregel wie am Auftrag: Wer sie dort nicht sieht, sieht sie auch hier nicht.
id* integer
Id dieses Versuchs. Über `GET …/orders/{id}` abrufbar, in `GET …/orders` NICHT enthalten.
attempt* integer
state* enum
angelegt · eingereicht · inBearbeitung · weitergeleitet · beschieden · abgelehnt · fehlgeschlagen
derivedStatus* enum
PENDING · SUCCESS · FAILURE · VEHICLE_UNKNOWN · VEHICLE_ALREADY_DEREGISTERED · LICENSE_PLATE_CODE_INVALID · REGISTRATION_CERTIFICATE_CODE_INVALID · LICENSE_PLATE_CODE_QTY_INVALID · INPUT_INVALID · RESERVATION_IMPOSSIBLE · ERROR_UNHANDLED
applicationId string
Die eigene Antragsnummer dieses Versuchs. Jeder Versuch bekommt beim KBA eine neue — darüber läuft die Rückfrage.
vehicleIdentificationNumber* string
paymentReference string
feeAmountCents integer
retryable boolean
Gesetzt, wenn der Vorgang nur voruebergehend gescheitert ist (Portalausfall, Registerauskunft derzeit nicht moeglich). Derselbe Antrag hat spaeter Aussicht auf Erfolg.
holderDataProvenance object
Der Herkunftsnachweis der Halterdaten — nur bei Anträgen, die sich über `powerOfAttorney.processId` auf einen Vollmachtsvorgang mit Nachweis berufen. Der Fingerabdruck ist derselbe wie am Vollmachtsvorgang; `unchanged` ist hier immer `true`, denn eine Abweichung führt zur Ablehnung, bevor ein Vorgang entsteht.
provider enum
Der Dienst, der die Halterdaten geliefert hat.
nect-sign · nect-business-sign · yousign
providerProcessId string
Kennung des Vorgangs beim Anbieter — darüber kann er ihn im Prüfverfahren bestätigen.
verifiedAt string (date-time)
Zeitpunkt laut Anbieter (die Unterschrift); nennt er keinen, der Eingang des Ergebnisses bei uns.
identitySource string
Was der Anbieter zur Quelle meldet — bei Business Sign `Handelsregister`. Nur vorhanden, wenn er etwas nennt; Nect Sign nennt keine Ausweisart.
fingerprint string
powerOfAttorneyProcessId integer (int64)
Nur an der Vorgangsauskunft — der Vollmachtsvorgang, auf den sich der Antrag beruft.
unchanged boolean
Nur an der Vorgangsauskunft. Ob die Halterdaten des Antrags den gelieferten entsprechen. Verglichen wird, was in die XKfz-Nachricht geht; zulässig sind allein das Entfernen führender und nachgestellter Leerzeichen, die Umwandlung des Datumsformats und die Umschlüsselung des Staats von ISO „DE" auf KBA „D".
deviatingFields string[]
Nur an der Vorgangsauskunft. Leer, wenn `unchanged` — siehe oben.
checkedAt string (date-time)
Nur an der Vorgangsauskunft — Zeitpunkt des Abgleichs.
401
403
404 Vorgang unbekannt.
error* string
Fehlerbeschreibung einschließlich TraceId.
traceId string
Auch im Header X-Trace-Id enthalten. Bei Rückfragen an den Support anzugeben.
500
default
GET/vehicleTransfers/files/content/{fileAccessKey}Beleg abrufen

Identisch zu `/vehicleDeregistrations/files/content/{fileAccessKey}`. Der Abruf hängt am Zugriffsschlüssel, nicht am Geschäftsvorfall.

Parameter

fileAccessKey*path

Antworten

200 Der Beleg als Datei.

Schema: string (binary)

401
403
404 Schlüssel unbekannt oder abgelaufen.
error* string
Fehlerbeschreibung einschließlich TraceId.
traceId string
Auch im Header X-Trace-Id enthalten. Bei Rückfragen an den Support anzugeben.
500
default
GET/vehicleReRegistrations/ordersDie eigenen Aufträge auflisten

Alle `…/orders`-Pfade liefern dieselbe Liste, unabhängig vom Geschäftsvorfall — welcher es ist, nennt das Feld `businessTransaction`, und danach grenzt der gleichnamige Filter ein. Der Pfad, unter dem Sie fragen, ändert die Antwort nicht; er ist nur dort einsortiert, wo Sie ihn suchen. Filter, Grenzen und Zähler stehen bei `/vehicleDeregistrations/orders`.

Parameter

externalIdquery
statequeryEiner oder mehrere, mit Komma verbunden. Siehe `/vehicleDeregistrations/orders`.
businessTransactionqueryEiner oder mehrere, mit Komma verbunden; unbekannt oder leer ⇒ 400. Siehe `/vehicleDeregistrations/orders`.
createdSincequery
changedSincequery
limitquery
offsetquery

Antworten

200 Die Aufträge, neueste zuerst.
orders* VehicleDeregistrationOrderSummary[]
order object
id integer
externalId string
attemptOf integer
Id des Auftrags. In dieser Liste stehen nur Auftragsköpfe, also immer die eigene Id.
businessTransaction string
state enum
angelegt · eingereicht · inBearbeitung · weitergeleitet · beschieden · abgelehnt · fehlgeschlagen
derivedStatus enum
PENDING · SUCCESS · FAILURE · VEHICLE_UNKNOWN · VEHICLE_ALREADY_DEREGISTERED · LICENSE_PLATE_CODE_INVALID · REGISTRATION_CERTIFICATE_CODE_INVALID · LICENSE_PLATE_CODE_QTY_INVALID · INPUT_INVALID · RESERVATION_IMPOSSIBLE · ERROR_UNHANDLED
applicationId string
vehicleIdentificationNumber string
licensePlate string
createdAt string (date-time)
changedAt string (date-time)
Der Wert, gegen den `changedSince` filtert.
limit* integer
Das angewandte Limit. Höchstens 200, auch wenn Sie mehr anfragen.
offset* integer
total* integer
Wie viele Aufträge der Filter insgesamt trifft — nicht die Seitengröße.
hasMore* boolean
Ob nach dieser Seite noch etwas kommt. Steht ausdrücklich da, statt sie aus `total > offset + limit` ableiten zu lassen: Diese Rechnung stellt jeder Aufrufer selbst an, und einer stellt sie falsch.
400 Ein Filterwert war unbrauchbar.
401
403
500
default
GET/vehicleReRegistrations/orders/{orderId}Auskunft zu einem Vorgang

Alle `…/orders/{orderId}`-Pfade liefern dieselbe Auskunft zu jedem Vorgang, unabhängig vom Geschäftsvorfall — welcher es ist, nennt das Feld `businessTransaction`. Der Pfad, unter dem Sie fragen, ändert die Antwort nicht; er ist nur dort einsortiert, wo Sie ihn suchen.

Parameter

orderId*path

Antworten

200 Aktueller Stand des Vorgangs
order object
id integer
Vorgangsnummer in diesem System.
externalId string
Ihre eigene Referenz aus dem Antrag.
attempt integer
Laufende Nummer des Versuchs. Ein korrigierter Antrag entsteht als NEUER Vorgang mit derselben `externalId` — beim KBA ist jeder Versuch ein eigener Antrag mit eigener Antragsnummer.
attemptOf integer
Id des Auftrags, zu dem dieser Versuch gehört; beim ersten Versuch die eigene Id. **Wer über die Schnittstelle abrechnet, gruppiert danach** — sonst zählt derselbe Auftrag mehrfach. Abgerechnet wird er einmal (die Übermittlungsgebühr je abgewiesenem Versuch bleibt davon unberührt).
state enum
Der Stand des Vorgangs. **Endzustand heisst: Endzustand des VERSUCHS, nicht des Auftrags.** `beschieden`, `abgelehnt` und `fehlgeschlagen` beenden den einzelnen Antrag beim KBA. Der Auftrag darüber kann weitergehen: Wird ein abgewiesener Antrag korrigiert, entsteht ein zweiter Versuch, und der Auftragskopf folgt dem jüngsten — er wechselt dann von `fehlgeschlagen` zurück nach `inBearbeitung`. Wer auf „Endzustand" vertraut und den Auftrag in seinem System abschliesst, verpasst die Korrektur und meldet ein Fahrzeug als nicht abgemeldet, obwohl es abgemeldet wird. Der Rücksprung sieht dabei aus wie ein Fehler des Systems und ist keiner. Fragen Sie den Versuch ab, wenn Sie einen Endzustand brauchen — `attempt` und `attemptOf` sagen Ihnen, was Sie vor sich haben. Die Webhook-Ereignisse führen für denselben Sachverhalt eigene, englische Werte (`ACCEPTED`, `APPROVED_WITH_DOCUMENTS`, `REJECTED_WITH_DOCUMENTS`) samt `derivedStatus`.
angelegt · eingereicht · inBearbeitung · weitergeleitet · beschieden · abgelehnt · fehlgeschlagen
derivedStatus enum
Die grobe Einordnung: läuft noch, erledigt, gescheitert. `state` hat sieben Werte, und welche davon Endzustände sind, steht in dieser Spezifikation — ein Aufrufer müsste die Liste bei jeder Erweiterung nachziehen. Wenn Ihr System nur wissen will, ob es weiter warten muss, werten Sie dieses Feld aus. Es ist dieselbe Abbildung, die auch das Webhook-Ereignis führt.
PENDING · SUCCESS · FAILURE · VEHICLE_UNKNOWN · VEHICLE_ALREADY_DEREGISTERED · LICENSE_PLATE_CODE_INVALID · REGISTRATION_CERTIFICATE_CODE_INVALID · LICENSE_PLATE_CODE_QTY_INVALID · INPUT_INVALID · RESERVATION_IMPOSSIBLE · ERROR_UNHANDLED
applicationId string
Antragsnummer des KBA — der Schlüssel für jede Rückfrage dort. Erst gesetzt, nachdem die Quittung eingetroffen ist; bei einem Antrag, der das KBA nicht erreicht hat, bleibt sie leer.
vehicleIdentificationNumber string
Die FIN des Vorgangs, immer in Großschreibung. **Am Auftragskopf kann sie sich ändern.** Eine Korrektur darf eine falsch abgetippte FIN berichtigen; der Kopf folgt dem jüngsten Versuch und trägt danach die neue. Die `externalId` bleibt dabei dieselbe. Wer Fahrzeuge über die FIN führt, sollte das wissen — sonst liest es sich wie eine Verwechslung von Fahrzeugen.
licensePlate string
Kennzeichen in der Anzeigeform, z. B. `HN-LL 2418`.
files object[]
Belege aus dem Rückkanal. Der Gebührenbescheid erscheint nur, wenn Sie selbst beim KBA registriert sind. Am Auftragskopf stehen die Belege aller Versuche (Kopf und `attempts[].id`), ohne Dubletten und in der Reihenfolge ihres Eingangs; die Auskunft zu einer Versuchs-Id führt nur dessen eigene.
purposeType string
mediaType string
fileAccessKey string
Einzulösen über `/vehicleDeregistrations/files/content/{fileAccessKey}`.
expirationTime string (date-time)
Bis dahin ist der Schlüssel gültig — beim Ablegen eines Vorgangsbelegs 72 Stunden; danach im Self-Service erneut freigeben. **Format:** vollständiger ISO-8601-Zeitstempel MIT Zonenangabe und Millisekunden (`2026-09-19T14:38:22.558Z`). Das Webhook-Ereignis nennt denselben Zeitpunkt als `LocalDateTime` — in UTC, aber ohne Zone und sekundengenau (`2026-09-19T14:38:22`); dieses Format schreibt der Webhook-Vertrag vor (`spec/webhooks.yaml`, Vorbild kennzeichen.dev). Wer beide Quellen vergleicht, liest den Wert des Ereignisses als UTC.
filename string
Der Name, unter dem der Abruf die Datei ausliefert (`Content-Disposition`), z. B. `Vorgang-17_KBA-NZ-123_Zulassungsbescheid.pdf`. Zwei Belege mit `purposeType: CERTIFICATE` — Zulassungsbescheid und vorläufiger Zulassungsnachweis — sind daran zu unterscheiden.
costBreakdown object
Die Gebührenaufstellung aus der Entscheidung (0709) — derselbe Wert wie `costBreakdown` im Webhook-Ereignis, für den Abgleich nach einem verlorenen Ereignis. **Nur bei eigener KBA-Registrierung** (Selbstabrechner); ein Vertragspartner unter unserer Registrierung sieht die amtlichen Beträge weder hier noch im Ereignis noch im Dashboard. Fehlt, solange keine Entscheidung vorliegt.
kbaCost integer
Nutzungsgebühr des KBA nach Nr. 129 GebOSt, in Cent. Steht da, wenn das KBA sie mit Quittungscode 07085 angekündigt hat oder der Antrag beschieden bzw. abgelehnt ist; sonst fehlt das Feld.
registrationOfficeCosts object
items* VehicleDeregistrationOrderCostBreakdownItem[]
number* integer
code string
Gebührennummer nach GebOSt, z. B. 224.2.
name string
amount* integer
Betrag in kleinster Währungseinheit (Cent).
note string
total* VehicleDeregistrationOrderCostBreakdownItem
number* integer
code string
Gebührennummer nach GebOSt, z. B. 224.2.
name string
amount* integer
Betrag in kleinster Währungseinheit (Cent).
note string
registrationData object
Über sechzig Angaben aus den Zulassungsbescheinigungen, sofern die Rückmeldung sie führt.
registrationDocumentsReady boolean
Erweiterung gegenüber kennzeichen.dev. `true`, wenn die Zulassungsbehörde meldet, dass die Zulassungsunterlagen (ZB I, ZB II, Stempelplaketten, Feinstaubplakette) wie gewünscht versandt wurden oder zur Abholung bereitliegen — derselbe Wert wie `registrationDocumentsReady` im Webhook-Ereignis. Nur bei Zulassungsvorfällen und nur in der automatisierten Bearbeitung nach einer antragsgemäßen Entscheidung. **Fehlt das Feld, ist nichts gesagt** — nicht „nicht versandt": Die Behörde führt die Angabe nicht in jeder Nachricht. Löst die abschliessende Rückmeldung weder einen Zustandswechsel noch neue Belege aus, kommt kein weiteres Ereignis; dann steht die Angabe nur hier.
parties object[]
Beteiligte laut Rückmeldung, etwa der Halter — bei allen Geschäftsvorfällen. Dieselbe Struktur wie im Webhook-Ereignis (spec/webhooks.yaml, …Party): `role` (Codeliste `rolle`, `2` ist der Halter), `roleName` (Klartext der Rolle, fehlt wenn die Nachricht keinen führt), `kind` (natural, legal, association), `name` und bei einer Vereinigung `representative`.
messages object[]
Meldungen des KBA mit Klartext und Begründung. `code` ist nicht immer ein fünfstelliger Quittungscode: Eine Ablehnung führt dort ihren kurzen Ablehnungsgrund; trägt sie keinen — der Regelfall —, steht im `code` der Antragsstatus in Worten. **Bis zum 19.08.2026 stand hier `{code, text, zusatz}`.** Geliefert wurden schon immer fünf Felder, und `zusatz` heisst in Wahrheit `additional` — Codegenerierung gegen den Vertrag erzeugte damit ein Feld, das nie befüllt wird, und übersah drei, die kommen. Die Webhook-Spezifikation beschrieb dieselbe Struktur die ganze Zeit richtig; beide sagen jetzt dasselbe, weil beide Wege dieselbe Funktion benutzen.
type* string
Herkunft der Meldung — `QUITTUNG` für jede Meldung des KBA, aus der Quittung (0002) wie aus der Entscheidung (0709).
kind enum
Quittungsart in Worten (Codeliste quittungsart 0/1/2). Fehlt bei den Ablehnungsgründen der 0709 — sie tragen keine Quittungsart.
Hinweis · Warnung · Fehler
code string
**Nicht immer fünfstellig.** Drei Ausprägungen kommen vor: der fünfstellige Quittungscode des KBA (`07077`); der kurze, numerische Ablehnungsgrund der 0709 (Codeliste `grundablehnungzulassungsantrag`, etwa `1` für Steuerrückstände, `2` für Gebührenrückstände); und — bei einer Ablehnung ohne Ablehnungsgrund, dem Regelfall — der Antragsstatus in Worten (Codeliste `statuselektronischerantrag`: neu, geprueft, wartend, weitergeleitet, bearbeitet, abgeschlossen, abgelehnt, eskaliert). Prüfen Sie den Wert nicht auf fünf Stellen.
text string
additional string
Der Zusatztext des KBA. Bei einer abgelehnten Zulassung trägt er den GRUND — die 0709 führt ihn ausdrücklich nicht.
createdAt string (date-time)
updatedAt string (date-time)
businessTransaction enum
Geschaeftsvorfall des Vorgangs — einer der sieben Codes. Wird in jeder Auskunft geliefert; derselbe Wert steht als `businessTransaction` im Webhook-Ereignis.
AB · HA · UG · WG · WZ · NZ · TZ
paymentReference string
Kassenzeichen aus dem Sammelgebuehrenbescheid (0103) — die Zahlungsreferenz. Erst gesetzt, nachdem der Bescheid eingetroffen ist. **Unabhängig von `feeAmountCents`.** Beide stammen aus demselben Bescheid, werden aber einzeln gesetzt: Ein Betrag ohne Kassenzeichen kommt vor. Wer seine Abrechnung auf „wenn `paymentReference` da, dann `feeAmountCents` lesen" baut, verliert diese Beträge.
feeAmountCents integer
Abgerechneter Betrag in ganzen Cent, aus demselben Bescheid. Kann gesetzt sein, ohne dass `paymentReference` es ist — siehe dort.
attempts object[]
**Alle Versuche dieses Auftrags** — der Weg vom Auftrag zu seinen Versuchen. `attemptOf` führt vom Ereignis oder vom Versuch zum Auftrag; dies ist die Gegenrichtung. Sie wird gebraucht, weil die **Übermittlungsgebühr je Versuch anfällt** und der Auftragskopf die Versuche mischt: `state` und `vehicleIdentificationNumber` folgen dem jüngsten Versuch, `paymentReference` und `feeAmountCents` können von einem älteren stammen. Wer über den Kopf abrechnet, bucht die Gebühr des einen und übersieht die des anderen. Die Auftragsliste (`GET …/orders`) führt ausschliesslich Auftragsköpfe — ein Versuch ist dort nicht zu finden, und einen Filter darauf gibt es nicht. Ohne dieses Feld bliebe das Webhook-Ereignis der einzige Weg an eine Versuchs-Id; damit hinge die Abrechnung wieder an dem Kanal, für dessen Ausfall die Auftragsliste gebaut wurde, und ein verlorenes Ereignis wäre dauerhaft nicht heilbar. Ältester Versuch zuerst. Bei einem Auftrag ohne Korrektur enthält die Liste genau einen Eintrag — den Auftrag selbst. Die amtlichen Gebührenangaben stehen hier unter derselben Sichtbarkeitsregel wie am Auftrag: Wer sie dort nicht sieht, sieht sie auch hier nicht.
id* integer
Id dieses Versuchs. Über `GET …/orders/{id}` abrufbar, in `GET …/orders` NICHT enthalten.
attempt* integer
state* enum
angelegt · eingereicht · inBearbeitung · weitergeleitet · beschieden · abgelehnt · fehlgeschlagen
derivedStatus* enum
PENDING · SUCCESS · FAILURE · VEHICLE_UNKNOWN · VEHICLE_ALREADY_DEREGISTERED · LICENSE_PLATE_CODE_INVALID · REGISTRATION_CERTIFICATE_CODE_INVALID · LICENSE_PLATE_CODE_QTY_INVALID · INPUT_INVALID · RESERVATION_IMPOSSIBLE · ERROR_UNHANDLED
applicationId string
Die eigene Antragsnummer dieses Versuchs. Jeder Versuch bekommt beim KBA eine neue — darüber läuft die Rückfrage.
vehicleIdentificationNumber* string
paymentReference string
feeAmountCents integer
retryable boolean
Gesetzt, wenn der Vorgang nur voruebergehend gescheitert ist (Portalausfall, Registerauskunft derzeit nicht moeglich). Derselbe Antrag hat spaeter Aussicht auf Erfolg.
holderDataProvenance object
Der Herkunftsnachweis der Halterdaten — nur bei Anträgen, die sich über `powerOfAttorney.processId` auf einen Vollmachtsvorgang mit Nachweis berufen. Der Fingerabdruck ist derselbe wie am Vollmachtsvorgang; `unchanged` ist hier immer `true`, denn eine Abweichung führt zur Ablehnung, bevor ein Vorgang entsteht.
provider enum
Der Dienst, der die Halterdaten geliefert hat.
nect-sign · nect-business-sign · yousign
providerProcessId string
Kennung des Vorgangs beim Anbieter — darüber kann er ihn im Prüfverfahren bestätigen.
verifiedAt string (date-time)
Zeitpunkt laut Anbieter (die Unterschrift); nennt er keinen, der Eingang des Ergebnisses bei uns.
identitySource string
Was der Anbieter zur Quelle meldet — bei Business Sign `Handelsregister`. Nur vorhanden, wenn er etwas nennt; Nect Sign nennt keine Ausweisart.
fingerprint string
powerOfAttorneyProcessId integer (int64)
Nur an der Vorgangsauskunft — der Vollmachtsvorgang, auf den sich der Antrag beruft.
unchanged boolean
Nur an der Vorgangsauskunft. Ob die Halterdaten des Antrags den gelieferten entsprechen. Verglichen wird, was in die XKfz-Nachricht geht; zulässig sind allein das Entfernen führender und nachgestellter Leerzeichen, die Umwandlung des Datumsformats und die Umschlüsselung des Staats von ISO „DE" auf KBA „D".
deviatingFields string[]
Nur an der Vorgangsauskunft. Leer, wenn `unchanged` — siehe oben.
checkedAt string (date-time)
Nur an der Vorgangsauskunft — Zeitpunkt des Abgleichs.
401
403
404 Vorgang unbekannt.
error* string
Fehlerbeschreibung einschließlich TraceId.
traceId string
Auch im Header X-Trace-Id enthalten. Bei Rückfragen an den Support anzugeben.
500
default
GET/vehicleReRegistrations/files/content/{fileAccessKey}Beleg abrufen

Identisch zu `/vehicleDeregistrations/files/content/{fileAccessKey}`. Der Abruf hängt am Zugriffsschlüssel, nicht am Geschäftsvorfall.

Parameter

fileAccessKey*path

Antworten

200 Der Beleg als Datei.

Schema: string (binary)

401
403
404 Schlüssel unbekannt oder abgelaufen.
error* string
Fehlerbeschreibung einschließlich TraceId.
traceId string
Auch im Header X-Trace-Id enthalten. Bei Rückfragen an den Support anzugeben.
500
default
GET/vehicleRegistrations/ordersDie eigenen Aufträge auflisten

Alle `…/orders`-Pfade liefern dieselbe Liste, unabhängig vom Geschäftsvorfall — welcher es ist, nennt das Feld `businessTransaction`, und danach grenzt der gleichnamige Filter ein. Der Pfad, unter dem Sie fragen, ändert die Antwort nicht; er ist nur dort einsortiert, wo Sie ihn suchen. Filter, Grenzen und Zähler stehen bei `/vehicleDeregistrations/orders`.

Parameter

externalIdquery
statequeryEiner oder mehrere, mit Komma verbunden. Siehe `/vehicleDeregistrations/orders`.
businessTransactionqueryEiner oder mehrere, mit Komma verbunden; unbekannt oder leer ⇒ 400. Siehe `/vehicleDeregistrations/orders`.
createdSincequery
changedSincequery
limitquery
offsetquery

Antworten

200 Die Aufträge, neueste zuerst.
orders* VehicleDeregistrationOrderSummary[]
order object
id integer
externalId string
attemptOf integer
Id des Auftrags. In dieser Liste stehen nur Auftragsköpfe, also immer die eigene Id.
businessTransaction string
state enum
angelegt · eingereicht · inBearbeitung · weitergeleitet · beschieden · abgelehnt · fehlgeschlagen
derivedStatus enum
PENDING · SUCCESS · FAILURE · VEHICLE_UNKNOWN · VEHICLE_ALREADY_DEREGISTERED · LICENSE_PLATE_CODE_INVALID · REGISTRATION_CERTIFICATE_CODE_INVALID · LICENSE_PLATE_CODE_QTY_INVALID · INPUT_INVALID · RESERVATION_IMPOSSIBLE · ERROR_UNHANDLED
applicationId string
vehicleIdentificationNumber string
licensePlate string
createdAt string (date-time)
changedAt string (date-time)
Der Wert, gegen den `changedSince` filtert.
limit* integer
Das angewandte Limit. Höchstens 200, auch wenn Sie mehr anfragen.
offset* integer
total* integer
Wie viele Aufträge der Filter insgesamt trifft — nicht die Seitengröße.
hasMore* boolean
Ob nach dieser Seite noch etwas kommt. Steht ausdrücklich da, statt sie aus `total > offset + limit` ableiten zu lassen: Diese Rechnung stellt jeder Aufrufer selbst an, und einer stellt sie falsch.
400 Ein Filterwert war unbrauchbar.
401
403
500
default
GET/vehicleRegistrations/orders/{orderId}Auskunft zu einem Vorgang

Alle `…/orders/{orderId}`-Pfade liefern dieselbe Auskunft zu jedem Vorgang, unabhängig vom Geschäftsvorfall — welcher es ist, nennt das Feld `businessTransaction`. Der Pfad, unter dem Sie fragen, ändert die Antwort nicht; er ist nur dort einsortiert, wo Sie ihn suchen.

Parameter

orderId*path

Antworten

200 Aktueller Stand des Vorgangs
order object
id integer
Vorgangsnummer in diesem System.
externalId string
Ihre eigene Referenz aus dem Antrag.
attempt integer
Laufende Nummer des Versuchs. Ein korrigierter Antrag entsteht als NEUER Vorgang mit derselben `externalId` — beim KBA ist jeder Versuch ein eigener Antrag mit eigener Antragsnummer.
attemptOf integer
Id des Auftrags, zu dem dieser Versuch gehört; beim ersten Versuch die eigene Id. **Wer über die Schnittstelle abrechnet, gruppiert danach** — sonst zählt derselbe Auftrag mehrfach. Abgerechnet wird er einmal (die Übermittlungsgebühr je abgewiesenem Versuch bleibt davon unberührt).
state enum
Der Stand des Vorgangs. **Endzustand heisst: Endzustand des VERSUCHS, nicht des Auftrags.** `beschieden`, `abgelehnt` und `fehlgeschlagen` beenden den einzelnen Antrag beim KBA. Der Auftrag darüber kann weitergehen: Wird ein abgewiesener Antrag korrigiert, entsteht ein zweiter Versuch, und der Auftragskopf folgt dem jüngsten — er wechselt dann von `fehlgeschlagen` zurück nach `inBearbeitung`. Wer auf „Endzustand" vertraut und den Auftrag in seinem System abschliesst, verpasst die Korrektur und meldet ein Fahrzeug als nicht abgemeldet, obwohl es abgemeldet wird. Der Rücksprung sieht dabei aus wie ein Fehler des Systems und ist keiner. Fragen Sie den Versuch ab, wenn Sie einen Endzustand brauchen — `attempt` und `attemptOf` sagen Ihnen, was Sie vor sich haben. Die Webhook-Ereignisse führen für denselben Sachverhalt eigene, englische Werte (`ACCEPTED`, `APPROVED_WITH_DOCUMENTS`, `REJECTED_WITH_DOCUMENTS`) samt `derivedStatus`.
angelegt · eingereicht · inBearbeitung · weitergeleitet · beschieden · abgelehnt · fehlgeschlagen
derivedStatus enum
Die grobe Einordnung: läuft noch, erledigt, gescheitert. `state` hat sieben Werte, und welche davon Endzustände sind, steht in dieser Spezifikation — ein Aufrufer müsste die Liste bei jeder Erweiterung nachziehen. Wenn Ihr System nur wissen will, ob es weiter warten muss, werten Sie dieses Feld aus. Es ist dieselbe Abbildung, die auch das Webhook-Ereignis führt.
PENDING · SUCCESS · FAILURE · VEHICLE_UNKNOWN · VEHICLE_ALREADY_DEREGISTERED · LICENSE_PLATE_CODE_INVALID · REGISTRATION_CERTIFICATE_CODE_INVALID · LICENSE_PLATE_CODE_QTY_INVALID · INPUT_INVALID · RESERVATION_IMPOSSIBLE · ERROR_UNHANDLED
applicationId string
Antragsnummer des KBA — der Schlüssel für jede Rückfrage dort. Erst gesetzt, nachdem die Quittung eingetroffen ist; bei einem Antrag, der das KBA nicht erreicht hat, bleibt sie leer.
vehicleIdentificationNumber string
Die FIN des Vorgangs, immer in Großschreibung. **Am Auftragskopf kann sie sich ändern.** Eine Korrektur darf eine falsch abgetippte FIN berichtigen; der Kopf folgt dem jüngsten Versuch und trägt danach die neue. Die `externalId` bleibt dabei dieselbe. Wer Fahrzeuge über die FIN führt, sollte das wissen — sonst liest es sich wie eine Verwechslung von Fahrzeugen.
licensePlate string
Kennzeichen in der Anzeigeform, z. B. `HN-LL 2418`.
files object[]
Belege aus dem Rückkanal. Der Gebührenbescheid erscheint nur, wenn Sie selbst beim KBA registriert sind. Am Auftragskopf stehen die Belege aller Versuche (Kopf und `attempts[].id`), ohne Dubletten und in der Reihenfolge ihres Eingangs; die Auskunft zu einer Versuchs-Id führt nur dessen eigene.
purposeType string
mediaType string
fileAccessKey string
Einzulösen über `/vehicleDeregistrations/files/content/{fileAccessKey}`.
expirationTime string (date-time)
Bis dahin ist der Schlüssel gültig — beim Ablegen eines Vorgangsbelegs 72 Stunden; danach im Self-Service erneut freigeben. **Format:** vollständiger ISO-8601-Zeitstempel MIT Zonenangabe und Millisekunden (`2026-09-19T14:38:22.558Z`). Das Webhook-Ereignis nennt denselben Zeitpunkt als `LocalDateTime` — in UTC, aber ohne Zone und sekundengenau (`2026-09-19T14:38:22`); dieses Format schreibt der Webhook-Vertrag vor (`spec/webhooks.yaml`, Vorbild kennzeichen.dev). Wer beide Quellen vergleicht, liest den Wert des Ereignisses als UTC.
filename string
Der Name, unter dem der Abruf die Datei ausliefert (`Content-Disposition`), z. B. `Vorgang-17_KBA-NZ-123_Zulassungsbescheid.pdf`. Zwei Belege mit `purposeType: CERTIFICATE` — Zulassungsbescheid und vorläufiger Zulassungsnachweis — sind daran zu unterscheiden.
costBreakdown object
Die Gebührenaufstellung aus der Entscheidung (0709) — derselbe Wert wie `costBreakdown` im Webhook-Ereignis, für den Abgleich nach einem verlorenen Ereignis. **Nur bei eigener KBA-Registrierung** (Selbstabrechner); ein Vertragspartner unter unserer Registrierung sieht die amtlichen Beträge weder hier noch im Ereignis noch im Dashboard. Fehlt, solange keine Entscheidung vorliegt.
kbaCost integer
Nutzungsgebühr des KBA nach Nr. 129 GebOSt, in Cent. Steht da, wenn das KBA sie mit Quittungscode 07085 angekündigt hat oder der Antrag beschieden bzw. abgelehnt ist; sonst fehlt das Feld.
registrationOfficeCosts object
items* VehicleDeregistrationOrderCostBreakdownItem[]
number* integer
code string
Gebührennummer nach GebOSt, z. B. 224.2.
name string
amount* integer
Betrag in kleinster Währungseinheit (Cent).
note string
total* VehicleDeregistrationOrderCostBreakdownItem
number* integer
code string
Gebührennummer nach GebOSt, z. B. 224.2.
name string
amount* integer
Betrag in kleinster Währungseinheit (Cent).
note string
registrationData object
Über sechzig Angaben aus den Zulassungsbescheinigungen, sofern die Rückmeldung sie führt.
registrationDocumentsReady boolean
Erweiterung gegenüber kennzeichen.dev. `true`, wenn die Zulassungsbehörde meldet, dass die Zulassungsunterlagen (ZB I, ZB II, Stempelplaketten, Feinstaubplakette) wie gewünscht versandt wurden oder zur Abholung bereitliegen — derselbe Wert wie `registrationDocumentsReady` im Webhook-Ereignis. Nur bei Zulassungsvorfällen und nur in der automatisierten Bearbeitung nach einer antragsgemäßen Entscheidung. **Fehlt das Feld, ist nichts gesagt** — nicht „nicht versandt": Die Behörde führt die Angabe nicht in jeder Nachricht. Löst die abschliessende Rückmeldung weder einen Zustandswechsel noch neue Belege aus, kommt kein weiteres Ereignis; dann steht die Angabe nur hier.
parties object[]
Beteiligte laut Rückmeldung, etwa der Halter — bei allen Geschäftsvorfällen. Dieselbe Struktur wie im Webhook-Ereignis (spec/webhooks.yaml, …Party): `role` (Codeliste `rolle`, `2` ist der Halter), `roleName` (Klartext der Rolle, fehlt wenn die Nachricht keinen führt), `kind` (natural, legal, association), `name` und bei einer Vereinigung `representative`.
messages object[]
Meldungen des KBA mit Klartext und Begründung. `code` ist nicht immer ein fünfstelliger Quittungscode: Eine Ablehnung führt dort ihren kurzen Ablehnungsgrund; trägt sie keinen — der Regelfall —, steht im `code` der Antragsstatus in Worten. **Bis zum 19.08.2026 stand hier `{code, text, zusatz}`.** Geliefert wurden schon immer fünf Felder, und `zusatz` heisst in Wahrheit `additional` — Codegenerierung gegen den Vertrag erzeugte damit ein Feld, das nie befüllt wird, und übersah drei, die kommen. Die Webhook-Spezifikation beschrieb dieselbe Struktur die ganze Zeit richtig; beide sagen jetzt dasselbe, weil beide Wege dieselbe Funktion benutzen.
type* string
Herkunft der Meldung — `QUITTUNG` für jede Meldung des KBA, aus der Quittung (0002) wie aus der Entscheidung (0709).
kind enum
Quittungsart in Worten (Codeliste quittungsart 0/1/2). Fehlt bei den Ablehnungsgründen der 0709 — sie tragen keine Quittungsart.
Hinweis · Warnung · Fehler
code string
**Nicht immer fünfstellig.** Drei Ausprägungen kommen vor: der fünfstellige Quittungscode des KBA (`07077`); der kurze, numerische Ablehnungsgrund der 0709 (Codeliste `grundablehnungzulassungsantrag`, etwa `1` für Steuerrückstände, `2` für Gebührenrückstände); und — bei einer Ablehnung ohne Ablehnungsgrund, dem Regelfall — der Antragsstatus in Worten (Codeliste `statuselektronischerantrag`: neu, geprueft, wartend, weitergeleitet, bearbeitet, abgeschlossen, abgelehnt, eskaliert). Prüfen Sie den Wert nicht auf fünf Stellen.
text string
additional string
Der Zusatztext des KBA. Bei einer abgelehnten Zulassung trägt er den GRUND — die 0709 führt ihn ausdrücklich nicht.
createdAt string (date-time)
updatedAt string (date-time)
businessTransaction enum
Geschaeftsvorfall des Vorgangs — einer der sieben Codes. Wird in jeder Auskunft geliefert; derselbe Wert steht als `businessTransaction` im Webhook-Ereignis.
AB · HA · UG · WG · WZ · NZ · TZ
paymentReference string
Kassenzeichen aus dem Sammelgebuehrenbescheid (0103) — die Zahlungsreferenz. Erst gesetzt, nachdem der Bescheid eingetroffen ist. **Unabhängig von `feeAmountCents`.** Beide stammen aus demselben Bescheid, werden aber einzeln gesetzt: Ein Betrag ohne Kassenzeichen kommt vor. Wer seine Abrechnung auf „wenn `paymentReference` da, dann `feeAmountCents` lesen" baut, verliert diese Beträge.
feeAmountCents integer
Abgerechneter Betrag in ganzen Cent, aus demselben Bescheid. Kann gesetzt sein, ohne dass `paymentReference` es ist — siehe dort.
attempts object[]
**Alle Versuche dieses Auftrags** — der Weg vom Auftrag zu seinen Versuchen. `attemptOf` führt vom Ereignis oder vom Versuch zum Auftrag; dies ist die Gegenrichtung. Sie wird gebraucht, weil die **Übermittlungsgebühr je Versuch anfällt** und der Auftragskopf die Versuche mischt: `state` und `vehicleIdentificationNumber` folgen dem jüngsten Versuch, `paymentReference` und `feeAmountCents` können von einem älteren stammen. Wer über den Kopf abrechnet, bucht die Gebühr des einen und übersieht die des anderen. Die Auftragsliste (`GET …/orders`) führt ausschliesslich Auftragsköpfe — ein Versuch ist dort nicht zu finden, und einen Filter darauf gibt es nicht. Ohne dieses Feld bliebe das Webhook-Ereignis der einzige Weg an eine Versuchs-Id; damit hinge die Abrechnung wieder an dem Kanal, für dessen Ausfall die Auftragsliste gebaut wurde, und ein verlorenes Ereignis wäre dauerhaft nicht heilbar. Ältester Versuch zuerst. Bei einem Auftrag ohne Korrektur enthält die Liste genau einen Eintrag — den Auftrag selbst. Die amtlichen Gebührenangaben stehen hier unter derselben Sichtbarkeitsregel wie am Auftrag: Wer sie dort nicht sieht, sieht sie auch hier nicht.
id* integer
Id dieses Versuchs. Über `GET …/orders/{id}` abrufbar, in `GET …/orders` NICHT enthalten.
attempt* integer
state* enum
angelegt · eingereicht · inBearbeitung · weitergeleitet · beschieden · abgelehnt · fehlgeschlagen
derivedStatus* enum
PENDING · SUCCESS · FAILURE · VEHICLE_UNKNOWN · VEHICLE_ALREADY_DEREGISTERED · LICENSE_PLATE_CODE_INVALID · REGISTRATION_CERTIFICATE_CODE_INVALID · LICENSE_PLATE_CODE_QTY_INVALID · INPUT_INVALID · RESERVATION_IMPOSSIBLE · ERROR_UNHANDLED
applicationId string
Die eigene Antragsnummer dieses Versuchs. Jeder Versuch bekommt beim KBA eine neue — darüber läuft die Rückfrage.
vehicleIdentificationNumber* string
paymentReference string
feeAmountCents integer
retryable boolean
Gesetzt, wenn der Vorgang nur voruebergehend gescheitert ist (Portalausfall, Registerauskunft derzeit nicht moeglich). Derselbe Antrag hat spaeter Aussicht auf Erfolg.
holderDataProvenance object
Der Herkunftsnachweis der Halterdaten — nur bei Anträgen, die sich über `powerOfAttorney.processId` auf einen Vollmachtsvorgang mit Nachweis berufen. Der Fingerabdruck ist derselbe wie am Vollmachtsvorgang; `unchanged` ist hier immer `true`, denn eine Abweichung führt zur Ablehnung, bevor ein Vorgang entsteht.
provider enum
Der Dienst, der die Halterdaten geliefert hat.
nect-sign · nect-business-sign · yousign
providerProcessId string
Kennung des Vorgangs beim Anbieter — darüber kann er ihn im Prüfverfahren bestätigen.
verifiedAt string (date-time)
Zeitpunkt laut Anbieter (die Unterschrift); nennt er keinen, der Eingang des Ergebnisses bei uns.
identitySource string
Was der Anbieter zur Quelle meldet — bei Business Sign `Handelsregister`. Nur vorhanden, wenn er etwas nennt; Nect Sign nennt keine Ausweisart.
fingerprint string
powerOfAttorneyProcessId integer (int64)
Nur an der Vorgangsauskunft — der Vollmachtsvorgang, auf den sich der Antrag beruft.
unchanged boolean
Nur an der Vorgangsauskunft. Ob die Halterdaten des Antrags den gelieferten entsprechen. Verglichen wird, was in die XKfz-Nachricht geht; zulässig sind allein das Entfernen führender und nachgestellter Leerzeichen, die Umwandlung des Datumsformats und die Umschlüsselung des Staats von ISO „DE" auf KBA „D".
deviatingFields string[]
Nur an der Vorgangsauskunft. Leer, wenn `unchanged` — siehe oben.
checkedAt string (date-time)
Nur an der Vorgangsauskunft — Zeitpunkt des Abgleichs.
401
403
404 Vorgang unbekannt.
error* string
Fehlerbeschreibung einschließlich TraceId.
traceId string
Auch im Header X-Trace-Id enthalten. Bei Rückfragen an den Support anzugeben.
500
default
POST/powerOfAttorneysVollmachtsvorgang anstoßen

Legt einen Vollmachtsvorgang beim Vertrauensdienst an. Die Antwort enthält den Link zur Unterschrift (`signatureUrl`). **Die Einladung ist nicht zugesagt.** Nect lädt den Vollmachtgeber nicht selbst ein. Eine Einladung per Mail, unter dem Namen des Großkunden, schickt die Schnittstelle nur, wenn auf der Instanz ein Mailversand eingerichtet ist; scheitert sie, steht der Grund in `note`. Geben Sie den Link aus der Antwort deshalb selbst an den Vollmachtgeber weiter. Zurück kommt eine `id`. Mit ihr beruft sich der spätere Zulassungsantrag auf die unterschriebene Vollmacht (`powerOfAttorney.processId`); das PDF muss dann nicht noch einmal den Weg über Sie nehmen. `representative` verlangen wir hier und nicht aus einer Einrichtung: Derselbe Wert steht später im Zulassungsantrag, und der Abgleich vergleicht beide. **Wiederholen ohne zweiten Vorgang.** Kommt dieselbe Anfrage mit derselben `externalOrderId` noch einmal, während der Vorgang dazu `offen` ist, antwortet die Schnittstelle mit `200` und diesem Vorgang — dieselbe `id`, kein neuer Vorgang bei Nect, keine zweite Einladung. Gleich heißt: derselbe Mandant und dieselbe Vollmacht (alle Angaben, die in das Formular gehen) samt E-Mail-Adresse (ohne Rücksicht auf Groß- und Kleinschreibung) und `bankAccount` (das SEPA-Mandat; neu, fehlend oder anders zählt als andere Angabe). Mit anderen Angaben: `409`. Ohne `externalOrderId` oder nach einem anderen Stand als `offen` legt jeder Aufruf einen neuen Vorgang an. Eine Frist gibt es nicht. **Juristische Personen in der Produktion.** Nect Business Sign ist auf der Produktionsinstanz vorerst nicht freigegeben: Für einen juristischen Vollmachtgeber antwortet die Schnittstelle mit `409` und legt nichts an. Die Firma reicht ihre eigene, qualifiziert gesiegelte PDF im Antrag als `powerOfAttorney.documentBase64` ein. Den Stand zeigt `/health` in `trustServiceLegalPersons`. **SEPA-Mandat mit unterschreiben.** Mit `bankAccount` erzeugen wir das SEPA-Lastschriftmandat für die Kfz-Steuer aus der amtlichen Vorlage und legen es als zweites PDF in denselben Nect-Vorgang: eine Identifizierung, beide Dokumente qualifiziert signiert. Der Antrag mit `powerOfAttorney.processId` braucht dann kein `sepaMandateBase64`. Nur für natürliche Personen; der Kontoinhaber muss der Vollmachtgeber sein (Halter = Kontoinhaber).

Request application/json

principal* object
Der Vollmachtgeber — der künftige Halter. Ein `companyName` ohne `lastName` bedeutet eine juristische Person; das amtliche Formular hat dafür eine eigene Vorlage. `partyType: ASSOCIATION` ergibt hier `400`: Der Vertrauensdienst stellt keine Vereinigung fest, der Antrag über `processId` führte deshalb zwangsläufig einen anderen Halter als die unterschriebene Vollmacht. Eine Vereinigung bringt ihre gesiegelte Vollmacht als `powerOfAttorney.documentBase64` mit. Mit `partyType` wird daraus die passende Variante des Formulars: `LEGAL_PERSON`, `AUTHORITY`, `SOLE_TRADER` (mit Unternehmensnamen) oder `ASSOCIATION`. Ein Einzelunternehmer ohne Unternehmensnamen bekommt die Vorlage für natürliche Personen.
address* HolderAddress
firstName string
lastName string
companyName string
gender enum
Nur bei natürlichen Personen zulässig.
FEMALE · MALE · DIVERSE · UNSPECIFIED
streetName string
houseNumber string
Laut XKfz-Schema NUR Ziffern, höchstens vier. Ein Zusatz wie "7a" ist dort nicht vorgesehen und gehört in addressSuffix.
zipCode string
cityName string
countryCode string
KBA-Staatsschlüssel. Ohne Angabe D.
addressSuffix string
partyType enum
Die Art des Beteiligten. **Freiwillig und zusätzlich** — ohne Angabe gilt wie bisher der Name: `companyName` heisst juristische Person, sonst natürliche Person. - `NATURAL_PERSON`, `LEGAL_PERSON` — die beiden bisherigen Arten, ausdrücklich benannt. - `AUTHORITY` — eine Behörde. Geht im XML als juristische Person hinaus; das Schema kennt keine eigene Art. - `SOLE_TRADER` — Einzelunternehmer. MIT `companyName` juristische Person, OHNE natürliche Person (amtliche Dokumentation zur Vollmacht: „Status als juristische Person wird nur dann zuerkannt, wenn ‚Name des Unternehmens' ausgefüllt ist"). Der Berufs-/Wirtschaftszweigschlüssel ist in beiden Fällen anzugeben — `888` gilt nur für Privatpersonen. - `ASSOCIATION` — eine nicht rechtsfähige Vereinigung, etwa eine GbR ohne Registereintrag oder eine Erbengemeinschaft. Geht als eigene Struktur (`NameVereinigung`) ans KBA, mit optionalem Vertreter. Ein eingetragener Verein ist dagegen eine juristische Person. Erweiterung gegenüber kennzeichen.dev.
NATURAL_PERSON · LEGAL_PERSON · AUTHORITY · SOLE_TRADER · ASSOCIATION
associationRepresentative object
Der benannte Vertreter einer Vereinigung — nur bei `partyType: ASSOCIATION` und dort freiwillig (seit XKfz 6.0 optional). In `POST /powerOfAttorneys` gibt es ihn nicht: Für eine Vereinigung lässt sich über uns keine Vollmacht unterschreiben (siehe `principal`).
firstName string
lastName string
companyName string
dateOfBirth string (date)
Streng als JJJJ-MM-TT. Nur bei natürlichen Personen. Zulässiger Bereich 1880–2099.
placeOfBirth string
Nur bei natürlichen Personen.
occupationKey string
Berufs- bzw. Wirtschaftszweigschlüssel, drei Stellen. Beim Halter einer Zulassung (UG, WG, WZ, NZ, TZ) Pflicht (KBA-Wissensartikel „Angabe des Berufsschlüssels bzw. Wirtschaftszweigs"). Firmen und juristische Personen nehmen den Schlüssel aus dem KBA-Verzeichnis SV 5, etwa `G01` für den Handel mit Kraftfahrzeugen; fehlt er, `400`. Privatpersonen ohne Angabe erhalten "888"; Freiberufler und Einzelunternehmer geben ihren Schlüssel an. Geprüft wird nur die Form. Bei der Halteränderung, beim Bevollmächtigten und beim Lieferungsempfänger optional.
representative* object
Der Bevollmächtigte — Sie.
address* HolderAddress
firstName string
lastName string
companyName string
gender enum
Nur bei natürlichen Personen zulässig.
FEMALE · MALE · DIVERSE · UNSPECIFIED
streetName string
houseNumber string
Laut XKfz-Schema NUR Ziffern, höchstens vier. Ein Zusatz wie "7a" ist dort nicht vorgesehen und gehört in addressSuffix.
zipCode string
cityName string
countryCode string
KBA-Staatsschlüssel. Ohne Angabe D.
addressSuffix string
partyType enum
Die Art des Beteiligten. **Freiwillig und zusätzlich** — ohne Angabe gilt wie bisher der Name: `companyName` heisst juristische Person, sonst natürliche Person. - `NATURAL_PERSON`, `LEGAL_PERSON` — die beiden bisherigen Arten, ausdrücklich benannt. - `AUTHORITY` — eine Behörde. Geht im XML als juristische Person hinaus; das Schema kennt keine eigene Art. - `SOLE_TRADER` — Einzelunternehmer. MIT `companyName` juristische Person, OHNE natürliche Person (amtliche Dokumentation zur Vollmacht: „Status als juristische Person wird nur dann zuerkannt, wenn ‚Name des Unternehmens' ausgefüllt ist"). Der Berufs-/Wirtschaftszweigschlüssel ist in beiden Fällen anzugeben — `888` gilt nur für Privatpersonen. - `ASSOCIATION` — eine nicht rechtsfähige Vereinigung, etwa eine GbR ohne Registereintrag oder eine Erbengemeinschaft. Geht als eigene Struktur (`NameVereinigung`) ans KBA, mit optionalem Vertreter. Ein eingetragener Verein ist dagegen eine juristische Person. Erweiterung gegenüber kennzeichen.dev.
NATURAL_PERSON · LEGAL_PERSON · AUTHORITY · SOLE_TRADER · ASSOCIATION
associationRepresentative object
Der benannte Vertreter einer Vereinigung — nur bei `partyType: ASSOCIATION` und dort freiwillig (seit XKfz 6.0 optional). In `POST /powerOfAttorneys` gibt es ihn nicht: Für eine Vereinigung lässt sich über uns keine Vollmacht unterschreiben (siehe `principal`).
firstName string
lastName string
companyName string
dateOfBirth string (date)
Streng als JJJJ-MM-TT. Nur bei natürlichen Personen. Zulässiger Bereich 1880–2099.
placeOfBirth string
Nur bei natürlichen Personen.
occupationKey string
Berufs- bzw. Wirtschaftszweigschlüssel, drei Stellen. Beim Halter einer Zulassung (UG, WG, WZ, NZ, TZ) Pflicht (KBA-Wissensartikel „Angabe des Berufsschlüssels bzw. Wirtschaftszweigs"). Firmen und juristische Personen nehmen den Schlüssel aus dem KBA-Verzeichnis SV 5, etwa `G01` für den Handel mit Kraftfahrzeugen; fehlt er, `400`. Privatpersonen ohne Angabe erhalten "888"; Freiberufler und Einzelunternehmer geben ihren Schlüssel an. Geprüft wird nur die Form. Bei der Halteränderung, beim Bevollmächtigten und beim Lieferungsempfänger optional.
email* string (email)
Die Adresse des Vollmachtgebers. Dorthin geht die Einladung zur Unterschrift, wenn auf der Instanz ein Mailversand eingerichtet ist.
vehicles* object[]
Höchstens zehn — so viele fasst die Fahrzeugtabelle des amtlichen Formulars. Jede FIN des späteren Antrags muss hier stehen (Fehlercode 00301).
vehicleIdentificationNumber* string
Wie im Antrag: Ziffern und Buchstaben, höchstens 25 Stellen (`typ-Fahrzeugidentifizierungsnummer`). Sonderzeichen, Steuerzeichen oder Überlänge ⇒ **400** mit Feldnamen und Index.
certificatePartIINumber string
Angenommen, aber nicht ins Formular übernommen — es führt genau eine Identifikation, die FIN (sonst 00306).
manufacturerKey string
Wie certificatePartIINumber.
typeKey string
Wie certificatePartIINumber.
customerNumber string
Großkunden-ID der Zollverwaltung des Vollmachtgebers, sofern vorhanden (ersetzt das SEPA-Mandat); nur Vorlage für juristische Personen. Form drei Ziffern, Großbuchstabe, vier Ziffern — derselbe Wert wie taxDetails.taxLargeCustomerId im späteren Antrag. Nicht die KBA-Kennung und nicht customization.customerNumber (Referenz 27).
certificatePartIRecipient enum
Empfänger der ZB I samt Plaketten. Ohne Angabe HOLDER — so stellt das KBA ohne Lieferinformation zu. Die deliveries des späteren Antrags müssen dazu passen, sonst 400.
HOLDER · REPRESENTATIVE · THIRD_PARTY
certificatePartIIRecipient enum
Empfänger der ZB II; wie certificatePartIRecipient.
HOLDER · REPRESENTATIVE · THIRD_PARTY
pickup boolean
Unterlagen werden abgeholt statt versandt — vom Bevollmächtigten, mit deliveryRecipient von diesem Dritten. Abholung durch einen Dritten (pickup zusammen mit deliveryRecipient) geht nur bei GENAU EINEM Fahrzeug in vehicles: Die Fahrzeugtabelle des amtlichen Formulars trägt je Zeile nur den Buchstaben und führt keinen Abholer. Mit mehreren Fahrzeugen 400 — dann je Fahrzeug ein eigener Vorgang. Holt der Bevollmächtigte selbst ab, bleiben zehn Fahrzeuge möglich.
deliveryRecipient object
Der Dritte bei THIRD_PARTY (Pflicht) oder der abholende Dritte bei pickup. Name und Anschrift müssen zu deliveryRecipient im Antrag passen.
address* HolderAddress
firstName string
lastName string
companyName string
gender enum
Nur bei natürlichen Personen zulässig.
FEMALE · MALE · DIVERSE · UNSPECIFIED
streetName string
houseNumber string
Laut XKfz-Schema NUR Ziffern, höchstens vier. Ein Zusatz wie "7a" ist dort nicht vorgesehen und gehört in addressSuffix.
zipCode string
cityName string
countryCode string
KBA-Staatsschlüssel. Ohne Angabe D.
addressSuffix string
partyType enum
Die Art des Beteiligten. **Freiwillig und zusätzlich** — ohne Angabe gilt wie bisher der Name: `companyName` heisst juristische Person, sonst natürliche Person. - `NATURAL_PERSON`, `LEGAL_PERSON` — die beiden bisherigen Arten, ausdrücklich benannt. - `AUTHORITY` — eine Behörde. Geht im XML als juristische Person hinaus; das Schema kennt keine eigene Art. - `SOLE_TRADER` — Einzelunternehmer. MIT `companyName` juristische Person, OHNE natürliche Person (amtliche Dokumentation zur Vollmacht: „Status als juristische Person wird nur dann zuerkannt, wenn ‚Name des Unternehmens' ausgefüllt ist"). Der Berufs-/Wirtschaftszweigschlüssel ist in beiden Fällen anzugeben — `888` gilt nur für Privatpersonen. - `ASSOCIATION` — eine nicht rechtsfähige Vereinigung, etwa eine GbR ohne Registereintrag oder eine Erbengemeinschaft. Geht als eigene Struktur (`NameVereinigung`) ans KBA, mit optionalem Vertreter. Ein eingetragener Verein ist dagegen eine juristische Person. Erweiterung gegenüber kennzeichen.dev.
NATURAL_PERSON · LEGAL_PERSON · AUTHORITY · SOLE_TRADER · ASSOCIATION
associationRepresentative object
Der benannte Vertreter einer Vereinigung — nur bei `partyType: ASSOCIATION` und dort freiwillig (seit XKfz 6.0 optional). In `POST /powerOfAttorneys` gibt es ihn nicht: Für eine Vereinigung lässt sich über uns keine Vollmacht unterschreiben (siehe `principal`).
firstName string
lastName string
companyName string
dateOfBirth string (date)
Streng als JJJJ-MM-TT. Nur bei natürlichen Personen. Zulässiger Bereich 1880–2099.
placeOfBirth string
Nur bei natürlichen Personen.
occupationKey string
Berufs- bzw. Wirtschaftszweigschlüssel, drei Stellen. Beim Halter einer Zulassung (UG, WG, WZ, NZ, TZ) Pflicht (KBA-Wissensartikel „Angabe des Berufsschlüssels bzw. Wirtschaftszweigs"). Firmen und juristische Personen nehmen den Schlüssel aus dem KBA-Verzeichnis SV 5, etwa `G01` für den Handel mit Kraftfahrzeugen; fehlt er, `400`. Privatpersonen ohne Angabe erhalten "888"; Freiberufler und Einzelunternehmer geben ihren Schlüssel an. Geprüft wird nur die Form. Bei der Halteränderung, beim Bevollmächtigten und beim Lieferungsempfänger optional.
extendedDataProvision boolean
Erlaubt den Empfang der vollständigen ZB-Daten über den Rückkanal. Ohne dieses Kreuz gibt es keinen ZB-Datenrückkanal: Ein späterer Antrag mit requestRegistrationData: true wird dann mit 400 abgewiesen, bevor etwas an das KBA geht (§ 39 Abs. 3 Satz 2 FZV — die Übermittlung braucht die Einwilligung des Halters).
externalOrderId string
bankAccount object
Konto für die Kfz-Steuer — dieselbe Form wie `bankAccount` im Zulassungsantrag, dazu `bic`. Wir befüllen daraus das SEPA-Lastschriftmandat (Vorlage der Generalzolldirektion) und lassen es im selben Nect-Vorgang wie die Vollmacht unterschreiben. Der Antrag mit `processId` hängt es als Dokumentart 44 an, wenn er `bankAccount` mit derselben IBAN und demselben Kontoinhaber führt; eine abweichende Angabe ergibt dort `400`, ein mitgeschicktes `sepaMandateBase64` hat Vorrang. `400`: bei einer juristischen Person (Business Sign — dort `sepaMandateBase64` oder `taxDetails.taxLargeCustomerId` im Antrag), wenn der Kontoinhaber nicht zum Vollmachtgeber passt (jeder Nachname, mindestens ein Vorname, kein weiteres Wort; Groß-/Kleinschreibung und Komma egal), bei ungültiger IBAN oder BIC, `usage` außer `Steuer` und `directDebitMandateGranted: false`. `503`, solange die Vorlage fehlt.
iban* string
Leerzeichen werden entfernt.
bic string
accountHolder* string
usage enum
Steuer
directDebitMandateGranted enum
true
{
  "principal": {
    "address": {
      "firstName": "Erika",
      "lastName": "Musterfrau",
      "gender": "FEMALE",
      "streetName": "Große Straße",
      "houseNumber": "1",
      "zipCode": "24937",
      "cityName": "Flensburg",
      "countryCode": "D"
    },
    "dateOfBirth": "1988-03-15",
    "placeOfBirth": "Rom"
  },
  "representative": {
    "address": {
      "companyName": "POWR GmbH",
      "streetName": "Musterweg",
      "houseNumber": "2",
      "zipCode": "20095",
      "cityName": "Hamburg",
      "countryCode": "D"
    }
  },
  "email": "erika@example.de",
  "vehicles": [
    {
      "vehicleIdentificationNumber": "WVWZZZ7HZ8H123456"
    }
  ],
  "externalOrderId": "vollmacht-4711"
}

Antworten

200 Vorgang angelegt — oder, bei einer Wiederholung mit derselben `externalOrderId` und denselben Angaben, der schon offene Vorgang. Der Signaturlink steht in der Antwort.
powerOfAttorney PowerOfAttorneyProcess
id integer (int64)
Diese Nummer gehört in `powerOfAttorney.processId`.
status enum
offen · signiert · abgelehnt · verfallen · fehlgeschlagen
provider string
signatureUrl string
Der Link, unter dem der Vollmachtgeber unterschreibt. Geben Sie ihn selbst weiter: Per Mail verschickt ihn die Schnittstelle nur, wenn auf der Instanz ein Mailversand eingerichtet ist, und Nect lädt nicht selbst ein.
validUntil string
Frist, bis zu der über `signatureUrl` unterschrieben werden kann; verstreicht sie ohne Unterschrift, wird der Vorgang `verfallen`. `null`, wenn die Instanz keine Frist gesetzt hat — bei Business Sign immer. Nicht die Laufzeit der Vollmacht.
externalOrderId string
vehicleIdentificationNumber string
Die FIN des ersten Eintrags in `vehicles`. Die Vollmacht gilt trotzdem für alle angegebenen Fahrzeuge.
createdAt string
updatedAt string
readyForApplication boolean
Ob der Vorgang für einen Zulassungsantrag taugt. `status: signiert` allein genügt NICHT. Ein Vorgang kann unterschrieben und trotzdem unbrauchbar sein: Bei Identifizierung per Reisepass liefert der Vertrauensdienst keine Anschrift, weil ein Pass keine führt. Seltener, aber möglich: das signierte Dokument oder die Feldbelegung fehlt — dann steht der Grund in `blockingIssues`. Nach dem BMDV-Schreiben vom 25.04.2024 darf sie dann nicht aus Ihren Angaben ergänzt werden — dort ist zusätzlich eine Meldebescheinigung zu prüfen. Prüfen Sie dieses Feld, bevor Sie sich im Zulassungsantrag auf `processId` berufen. Andernfalls antwortet der Antrag mit 409, und der Kunde hat die Identifizierung bereits durchlaufen. **Was es NICHT abdeckt:** den inhaltlichen Abgleich der unterschriebenen Vollmacht gegen die festgestellte Identität. Weicht etwas ab — der Kunde hat sich unter einem anderen Namen ausgewiesen, oder das Formular führt einen Geburtsort, den der Ausweis nicht hergibt —, meldet das erst der Antrag, und zwar mit **400** samt Angabe des betroffenen Feldes. `readyForApplication` sagt aus, dass der Vorgang **vollständig** ist, nicht dass er **stimmig** ist.
missingHolderFields string[]
Welche Pflichtfelder der Anschrift der Vertrauensdienst nicht festgestellt hat. Nur vorhanden, wenn etwas fehlt. Aussagekräftig erst bei `status: signiert` — bei einem offenen Vorgang hat der Dienst noch nichts festgestellt, und die Liste kann alle Felder nennen, bei einer Firma auch Vorname und Nachname. Genannt werden ausschliesslich FELDNAMEN, keine Werte: Die festgestellten Personendaten geben wir nicht heraus. Der Zulassungsantrag zieht den Halter selbst aus dem Vorgang.
blockingIssues string[]
Was dem unterschriebenen Vorgang zum Antrag sonst noch fehlt — im Unterschied zu `missingHolderFields` keine Feldnamen, sondern Zustände des Vorgangs selbst: ein fehlendes signiertes Dokument, eine fehlende oder unlesbare Feldbelegung. Nur vorhanden, wenn `status: signiert` ist und etwas fehlt. Beides sind Fälle für den Support — ein erneutes Abrufen des Standes hilft beim ersten, beim zweiten muss der Vorgang neu angestossen werden.
note string
Ein Hinweis zum Vorgang — etwa dass die Einladung nicht versendet werden konnte, oder womit der Vertrauensdienst eine Ablehnung begründet hat. Der Vorgang steht trotzdem.
holderDataProvenance object
Der Herkunftsnachweis der Halterdaten: welcher Vertrauensdienst sie wann geliefert hat, und der Fingerabdruck über die gelieferten Felder. Nur bei `status: signiert` und nur, wenn der Anbieter sich zu erkennen gegeben hat — Vorgänge von vor dem 12.09.2026 führen keinen. `unchanged` und `deviatingFields` gibt es erst am Zulassungsantrag, der sich auf den Vorgang beruft.
provider enum
Der Dienst, der die Halterdaten geliefert hat.
nect-sign · nect-business-sign · yousign
providerProcessId string
Kennung des Vorgangs beim Anbieter — darüber kann er ihn im Prüfverfahren bestätigen.
verifiedAt string (date-time)
Zeitpunkt laut Anbieter (die Unterschrift); nennt er keinen, der Eingang des Ergebnisses bei uns.
identitySource string
Was der Anbieter zur Quelle meldet — bei Business Sign `Handelsregister`. Nur vorhanden, wenn er etwas nennt; Nect Sign nennt keine Ausweisart.
fingerprint string
powerOfAttorneyProcessId integer (int64)
Nur an der Vorgangsauskunft — der Vollmachtsvorgang, auf den sich der Antrag beruft.
unchanged boolean
Nur an der Vorgangsauskunft. Ob die Halterdaten des Antrags den gelieferten entsprechen. Verglichen wird, was in die XKfz-Nachricht geht; zulässig sind allein das Entfernen führender und nachgestellter Leerzeichen, die Umwandlung des Datumsformats und die Umschlüsselung des Staats von ISO „DE" auf KBA „D".
deviatingFields string[]
Nur an der Vorgangsauskunft. Leer, wenn `unchanged` — siehe oben.
checkedAt string (date-time)
Nur an der Vorgangsauskunft — Zeitpunkt des Abgleichs.
400 Angaben unvollständig oder widersprüchlich. Auch: Nect findet die Firma beim Anlegen nicht im Handelsregister — dann steht der Vorgang als `fehlgeschlagen`, seine Nummer in `powerOfAttorneyId`. Den Firmennamen genau wie im Register angeben und neu anstoßen.
error* string
Fehlerbeschreibung einschließlich TraceId.
traceId string
Auch im Header X-Trace-Id enthalten. Bei Rückfragen an den Support anzugeben.
powerOfAttorneyId integer (int64)
Der Vollmachtsvorgang, um den es geht: der beim Anlegen gescheiterte (`status: fehlgeschlagen`) oder der schon offene unter derselben `externalOrderId`. Fehlt, wenn nichts angelegt wurde.
401
403 Benutzer nicht für den Mandanten im Pfad berechtigt — oder, auf der Produktionsinstanz, die Produktion für den Mandanten nicht freigegeben bzw. der Mandant abgeschaltet. Es wird nichts angelegt, auch nicht bei Nect.
error* string
Fehlerbeschreibung einschließlich TraceId.
traceId string
Auch im Header X-Trace-Id enthalten. Bei Rückfragen an den Support anzugeben.
409 Für einen juristischen Vollmachtgeber ist kein Vorgang möglich: Nect Business Sign ist nicht eingerichtet oder in der Produktion noch nicht freigegeben. Es wird nichts angelegt; die Firma reicht ihre eigene, qualifiziert gesiegelte PDF im Antrag als `powerOfAttorney.documentBase64` ein. — Oder: Unter derselben `externalOrderId` liegt ein offener Vorgang mit anderen Angaben; `powerOfAttorneyId` nennt ihn, angelegt wird nichts.
error* string
Fehlerbeschreibung einschließlich TraceId.
traceId string
Auch im Header X-Trace-Id enthalten. Bei Rückfragen an den Support anzugeben.
powerOfAttorneyId integer (int64)
Der Vollmachtsvorgang, um den es geht: der beim Anlegen gescheiterte (`status: fehlgeschlagen`) oder der schon offene unter derselben `externalOrderId`. Fehlt, wenn nichts angelegt wurde.
413
415
500
502 Der Vertrauensdiensteanbieter ist gestört, nicht erreichbar oder hat die Anfrage abgewiesen. Der Vorgang bleibt mit Begründung als `fehlgeschlagen` stehen, seine Nummer steht in `powerOfAttorneyId`.
error* string
Fehlerbeschreibung einschließlich TraceId.
traceId string
Auch im Header X-Trace-Id enthalten. Bei Rückfragen an den Support anzugeben.
powerOfAttorneyId integer (int64)
Der Vollmachtsvorgang, um den es geht: der beim Anlegen gescheiterte (`status: fehlgeschlagen`) oder der schon offene unter derselben `externalOrderId`. Fehlt, wenn nichts angelegt wurde.
503 Kein Vertrauensdiensteanbieter eingerichtet — oder er ist fehlerhaft eingerichtet (`/health`: `trustService: misconfigured`). Anträge auf EIGENE Fahrzeuge und Anträge mit eigener PDF (`documentBase64`) sind davon nicht betroffen. Ebenso mit `bankAccount`, solange die Vorlage des SEPA-Mandats auf der Instanz fehlt („SEPA-Mandat-Vorlage nicht eingerichtet", in `/health` als `sepaMandateTemplate: missing`); es entsteht dann kein Vorgang. Ohne `bankAccount` ist der Vorgang möglich.
default
GET/powerOfAttorneys/{processId}Stand eines Vollmachtsvorgangs

Fragt bei einem noch offenen Vorgang zuerst beim Anbieter nach und liefert dann den aktuellen Stand. `status` ist `offen`, `signiert`, `abgelehnt`, `verfallen` oder `fehlgeschlagen`. Erst bei `signiert` nimmt ein Zulassungsantrag die Nummer an.

Parameter

processId*path

Antworten

200 Aktueller Stand
powerOfAttorney PowerOfAttorneyProcess
id integer (int64)
Diese Nummer gehört in `powerOfAttorney.processId`.
status enum
offen · signiert · abgelehnt · verfallen · fehlgeschlagen
provider string
signatureUrl string
Der Link, unter dem der Vollmachtgeber unterschreibt. Geben Sie ihn selbst weiter: Per Mail verschickt ihn die Schnittstelle nur, wenn auf der Instanz ein Mailversand eingerichtet ist, und Nect lädt nicht selbst ein.
validUntil string
Frist, bis zu der über `signatureUrl` unterschrieben werden kann; verstreicht sie ohne Unterschrift, wird der Vorgang `verfallen`. `null`, wenn die Instanz keine Frist gesetzt hat — bei Business Sign immer. Nicht die Laufzeit der Vollmacht.
externalOrderId string
vehicleIdentificationNumber string
Die FIN des ersten Eintrags in `vehicles`. Die Vollmacht gilt trotzdem für alle angegebenen Fahrzeuge.
createdAt string
updatedAt string
readyForApplication boolean
Ob der Vorgang für einen Zulassungsantrag taugt. `status: signiert` allein genügt NICHT. Ein Vorgang kann unterschrieben und trotzdem unbrauchbar sein: Bei Identifizierung per Reisepass liefert der Vertrauensdienst keine Anschrift, weil ein Pass keine führt. Seltener, aber möglich: das signierte Dokument oder die Feldbelegung fehlt — dann steht der Grund in `blockingIssues`. Nach dem BMDV-Schreiben vom 25.04.2024 darf sie dann nicht aus Ihren Angaben ergänzt werden — dort ist zusätzlich eine Meldebescheinigung zu prüfen. Prüfen Sie dieses Feld, bevor Sie sich im Zulassungsantrag auf `processId` berufen. Andernfalls antwortet der Antrag mit 409, und der Kunde hat die Identifizierung bereits durchlaufen. **Was es NICHT abdeckt:** den inhaltlichen Abgleich der unterschriebenen Vollmacht gegen die festgestellte Identität. Weicht etwas ab — der Kunde hat sich unter einem anderen Namen ausgewiesen, oder das Formular führt einen Geburtsort, den der Ausweis nicht hergibt —, meldet das erst der Antrag, und zwar mit **400** samt Angabe des betroffenen Feldes. `readyForApplication` sagt aus, dass der Vorgang **vollständig** ist, nicht dass er **stimmig** ist.
missingHolderFields string[]
Welche Pflichtfelder der Anschrift der Vertrauensdienst nicht festgestellt hat. Nur vorhanden, wenn etwas fehlt. Aussagekräftig erst bei `status: signiert` — bei einem offenen Vorgang hat der Dienst noch nichts festgestellt, und die Liste kann alle Felder nennen, bei einer Firma auch Vorname und Nachname. Genannt werden ausschliesslich FELDNAMEN, keine Werte: Die festgestellten Personendaten geben wir nicht heraus. Der Zulassungsantrag zieht den Halter selbst aus dem Vorgang.
blockingIssues string[]
Was dem unterschriebenen Vorgang zum Antrag sonst noch fehlt — im Unterschied zu `missingHolderFields` keine Feldnamen, sondern Zustände des Vorgangs selbst: ein fehlendes signiertes Dokument, eine fehlende oder unlesbare Feldbelegung. Nur vorhanden, wenn `status: signiert` ist und etwas fehlt. Beides sind Fälle für den Support — ein erneutes Abrufen des Standes hilft beim ersten, beim zweiten muss der Vorgang neu angestossen werden.
note string
Ein Hinweis zum Vorgang — etwa dass die Einladung nicht versendet werden konnte, oder womit der Vertrauensdienst eine Ablehnung begründet hat. Der Vorgang steht trotzdem.
holderDataProvenance object
Der Herkunftsnachweis der Halterdaten: welcher Vertrauensdienst sie wann geliefert hat, und der Fingerabdruck über die gelieferten Felder. Nur bei `status: signiert` und nur, wenn der Anbieter sich zu erkennen gegeben hat — Vorgänge von vor dem 12.09.2026 führen keinen. `unchanged` und `deviatingFields` gibt es erst am Zulassungsantrag, der sich auf den Vorgang beruft.
provider enum
Der Dienst, der die Halterdaten geliefert hat.
nect-sign · nect-business-sign · yousign
providerProcessId string
Kennung des Vorgangs beim Anbieter — darüber kann er ihn im Prüfverfahren bestätigen.
verifiedAt string (date-time)
Zeitpunkt laut Anbieter (die Unterschrift); nennt er keinen, der Eingang des Ergebnisses bei uns.
identitySource string
Was der Anbieter zur Quelle meldet — bei Business Sign `Handelsregister`. Nur vorhanden, wenn er etwas nennt; Nect Sign nennt keine Ausweisart.
fingerprint string
powerOfAttorneyProcessId integer (int64)
Nur an der Vorgangsauskunft — der Vollmachtsvorgang, auf den sich der Antrag beruft.
unchanged boolean
Nur an der Vorgangsauskunft. Ob die Halterdaten des Antrags den gelieferten entsprechen. Verglichen wird, was in die XKfz-Nachricht geht; zulässig sind allein das Entfernen führender und nachgestellter Leerzeichen, die Umwandlung des Datumsformats und die Umschlüsselung des Staats von ISO „DE" auf KBA „D".
deviatingFields string[]
Nur an der Vorgangsauskunft. Leer, wenn `unchanged` — siehe oben.
checkedAt string (date-time)
Nur an der Vorgangsauskunft — Zeitpunkt des Abgleichs.
400 `processId` ist keine ganze Zahl.
401
403
404 Vorgang unbekannt oder nicht Ihrer.
error* string
Fehlerbeschreibung einschließlich TraceId.
traceId string
Auch im Header X-Trace-Id enthalten. Bei Rückfragen an den Support anzugeben.
500
default
GET/vehicleRegistrations/files/content/{fileAccessKey}Beleg abrufen

Identisch zu `/vehicleDeregistrations/files/content/{fileAccessKey}`. Der Abruf hängt am Zugriffsschlüssel, nicht am Geschäftsvorfall.

Parameter

fileAccessKey*path

Antworten

200 Der Beleg als Datei.

Schema: string (binary)

401
403
404 Schlüssel unbekannt oder abgelaufen.
error* string
Fehlerbeschreibung einschließlich TraceId.
traceId string
Auch im Header X-Trace-Id enthalten. Bei Rückfragen an den Support anzugeben.
500
default
POST/vehicleTransfers/transfersUmschreibung beauftragen

Umschreibung eines zugelassenen Fahrzeugs — Halterwechsel, Wechsel des Zulassungsbezirks oder beides. Pflicht über die gemeinsamen Angaben hinaus (siehe `VehicleRegistrationRequest`): das **bisherige Kennzeichen** (`customization.licensePlateNumberComponents`), der Sicherheitscode der **ZB I** (`customization.vehicleRegistrationCertificateSecurityCode`) und der der **ZB II** (`customization.vehicleRegistrationCertificatePartII.securityCode`). Die Sicherheitscodes der Stempelplaketten (`licensePlateSeals`) sind nachzuweisen, wenn sich das Kennzeichen oder seine Merkmale ändern. Ereignistyp: `VEHICLE_TRANSFER_XKFZ_EVENT`.

Request application/json

requestRegistrationData boolean
Fordert die strukturierten Zulassungsdaten an (ZB I und ZB II, ueber sechzig Angaben). Ohne sie kommt nur der Bescheid als PDF zurueck. Die Daten erscheinen als `registrationData` in der Vorgangsauskunft und im Webhook-Ereignis. Bei einem Antrag mit Vollmacht muss sie das Kreuz „erweiterte Datenbereitstellung" tragen (`extendedDataProvision` im Vollmachtsvorgang), sonst antwortet der Antrag mit 400 — geprüft, sofern sich die Vollmacht als Formular lesen lässt.
orderEmissionSticker boolean
Feinstaubplakette mitbestellen; erweitert die Lieferung um eine Position (Festlegungen zum elektronischen Antrag, Blatt „GK NZ").
customization* VehicleRegistrationCustomization
vehicleIdentificationNumber* string
licensePlateNumberComponents object
Bisheriges Kennzeichen — bei Umschreibung Pflicht.
usageType enum
Kennzeichenmerkmal — für alle Anträge mit bisherigem Kennzeichen (AB, HA, UG, WG, WZ): EURO (Normalfall), ELECTRIC (Elektrokennzeichen) und HISTORIC (Oldtimerkennzeichen); andere Werte werden mit HTTP 400 abgewiesen.
EURO · ELECTRIC · HISTORIC
city* string
Unterscheidungszeichen, 1–3 Buchstaben (Umlaute zulässig). Kleinbuchstaben werden großgeschrieben; das Muster lässt sie deshalb zu.
middle* string
Erkennungsbuchstaben, 1–2 Buchstaben ohne Umlaute. Kleinbuchstaben werden großgeschrieben.
end* string
Erkennungsnummer, 1–4 Ziffern.
licensePlateSeals LicensePlateSeal[]
Codes der Stempelplaketten des bisherigen Kennzeichens — nur zusammen mit licensePlateNumberComponents wirksam. Ohne bisheriges Kennzeichen (immer bei NZ und TZ) werden die Einträge geprüft, aber nicht übermittelt.
position* enum
vorn · hinten · beide
securityCode string
Dreistelliger Code unter der Stempelplakette.
licensePlateAssignment object
Neues Kennzeichen zuteilen. Ein Wunschkennzeichen lässt sich über die GKS NICHT reservieren — entweder eine vorab bei der Zulassungsbehörde erwirkte Reservierung samt PIN, oder das nächste freie Kennzeichen.
reservation object
licensePlate* string
pin* string
plateType enum
Kennzeichenart nach dem amtlichen Schema (typ-MerkmalKennzeichenart-ZFZR). Z ist der Regelfall, B das Behördenkennzeichen. Pflicht, sobald das nächste freie Kennzeichen angefordert wird (keine `reservation`); fehlt sie, antworten wir mit 400. Saisonkennzeichen (ZS, BS) sind vorerst nicht beantragbar und werden mit 400 abgewiesen: Der Betriebszeitraum lässt sich im Antrag nicht angeben, und die Frage dazu ist beim KBA offen. Die übrigen Arten des Schemas — Ausfuhrkennzeichen (A), rotes Kennzeichen (R), Kurzzeitkennzeichen (RK) und Versicherungskennzeichen (V, VR) — lassen sich über die GKS nicht beantragen. Bescheide des KBA können dennoch jede Art melden.
B · Z
electric boolean
historic boolean
vehicleRegistrationCertificateSecurityCode string
vehicleRegistrationCertificateNumber string
Nummer der ZB I, 18–20 Zeichen, Buchstabe am Anfang. Kleinbuchstaben werden großgeschrieben.
vehicleRegistrationCertificateImprintNumber string
Druckstücknummer der ZB I. Acht Zeichen: Großbuchstabe, sechs Ziffern oder Großbuchstaben, zuletzt Ziffer oder X (Schema XKfz 6.0, Type.Druckstuecknummer).
vehicleRegistrationCertificatePartII object
number string
Nummer der ZB II. Kleinbuchstaben werden großgeschrieben. OHNEZBII und ohne-ZF- sind die amtlichen Platzhalter für Fahrzeuge ohne Teil II.
securityCode string
Zwölfstellig, Modulo-11-geprüft. Wird bereits hier vorgeprüft, verbindlich prüft das KBA.
insuranceConfirmationNumber* string
eVB-Nummer. Ohne sie ist keine Zulassung möglich.
vehicleUsage enum
Fahrzeugverwendung nach dem amtlichen Schema (typ-VerwendungFahrzeug). Muss zur eVB passen.
B · C · D · E · F · G · K · L · M · S · T · X
customerNumber string
contractPartner ContractPartner
vehicleHolder object
Der künftige Halter. Pflicht — AUSSER der Antrag beruft sich über `powerOfAttorney.processId` auf einen Vollmachtsvorgang, zu dem der Vertrauensdienst die Person bereits festgestellt hat. Dann setzen wir den Halter aus dessen Daten ein, und mitgeschickte Angaben werden überschrieben. Grund ist das BMDV-Schreiben vom 25.04.2024 (Az. 7362.8/1): Die Halterdaten stammen ausschliesslich vom Vertrauensdiensteanbieter, nicht aus der Kundeneingabe. § 38 Abs. 4 FZV sagt dasselbe — die Halterangaben sind der das Vollmachtsformular verarbeitenden Nachricht zu entnehmen. Bei Zulassungen (UG, WG, WZ, NZ, TZ) ersetzen wir mitgeschickte Halterangaben deshalb durch die des Vertrauensdienstes — es gibt dafür kein 400; Vorgangsauskunft und Dashboard zeigen den gesendeten Halter. Ergänzt wird nur, was kein Vertrauensdienst feststellt (`occupationKey`, `address.gender`; bei einer Firma nur `occupationKey`). Ohne `occupationKey` gilt der in der Vollmacht unterschriebene Wirtschaftszweig; `vehicleHolder: { occupationKey }` allein genügt. 400 kommt nur, wenn die Daten des Vertrauensdienstes nicht zur unterschriebenen Vollmacht passen, der mitgeschickte `occupationKey` vom in der Vollmacht unterschriebenen Wirtschaftszweig abweicht oder eine Firma an beiden Stellen keinen `occupationKey` führt. Anders die Halteränderung: Dort ist die neue Anschrift der Antrag selbst und muss der festgestellten entsprechen, sonst 400 (siehe `VehicleHolderChangeRequest`).
address* HolderAddress
firstName string
lastName string
companyName string
gender enum
Nur bei natürlichen Personen zulässig.
FEMALE · MALE · DIVERSE · UNSPECIFIED
streetName string
houseNumber string
Laut XKfz-Schema NUR Ziffern, höchstens vier. Ein Zusatz wie "7a" ist dort nicht vorgesehen und gehört in addressSuffix.
zipCode string
cityName string
countryCode string
KBA-Staatsschlüssel. Ohne Angabe D.
addressSuffix string
partyType enum
Die Art des Beteiligten. **Freiwillig und zusätzlich** — ohne Angabe gilt wie bisher der Name: `companyName` heisst juristische Person, sonst natürliche Person. - `NATURAL_PERSON`, `LEGAL_PERSON` — die beiden bisherigen Arten, ausdrücklich benannt. - `AUTHORITY` — eine Behörde. Geht im XML als juristische Person hinaus; das Schema kennt keine eigene Art. - `SOLE_TRADER` — Einzelunternehmer. MIT `companyName` juristische Person, OHNE natürliche Person (amtliche Dokumentation zur Vollmacht: „Status als juristische Person wird nur dann zuerkannt, wenn ‚Name des Unternehmens' ausgefüllt ist"). Der Berufs-/Wirtschaftszweigschlüssel ist in beiden Fällen anzugeben — `888` gilt nur für Privatpersonen. - `ASSOCIATION` — eine nicht rechtsfähige Vereinigung, etwa eine GbR ohne Registereintrag oder eine Erbengemeinschaft. Geht als eigene Struktur (`NameVereinigung`) ans KBA, mit optionalem Vertreter. Ein eingetragener Verein ist dagegen eine juristische Person. Erweiterung gegenüber kennzeichen.dev.
NATURAL_PERSON · LEGAL_PERSON · AUTHORITY · SOLE_TRADER · ASSOCIATION
associationRepresentative object
Der benannte Vertreter einer Vereinigung — nur bei `partyType: ASSOCIATION` und dort freiwillig (seit XKfz 6.0 optional). In `POST /powerOfAttorneys` gibt es ihn nicht: Für eine Vereinigung lässt sich über uns keine Vollmacht unterschreiben (siehe `principal`).
firstName string
lastName string
companyName string
dateOfBirth string (date)
Streng als JJJJ-MM-TT. Nur bei natürlichen Personen. Zulässiger Bereich 1880–2099.
placeOfBirth string
Nur bei natürlichen Personen.
occupationKey string
Berufs- bzw. Wirtschaftszweigschlüssel, drei Stellen. Beim Halter einer Zulassung (UG, WG, WZ, NZ, TZ) Pflicht (KBA-Wissensartikel „Angabe des Berufsschlüssels bzw. Wirtschaftszweigs"). Firmen und juristische Personen nehmen den Schlüssel aus dem KBA-Verzeichnis SV 5, etwa `G01` für den Handel mit Kraftfahrzeugen; fehlt er, `400`. Privatpersonen ohne Angabe erhalten "888"; Freiberufler und Einzelunternehmer geben ihren Schlüssel an. Geprüft wird nur die Form. Bei der Halteränderung, beim Bevollmächtigten und beim Lieferungsempfänger optional.
powerOfAttorney PowerOfAttorney
representative HolderParty
address* HolderAddress
firstName string
lastName string
companyName string
gender enum
Nur bei natürlichen Personen zulässig.
FEMALE · MALE · DIVERSE · UNSPECIFIED
streetName string
houseNumber string
Laut XKfz-Schema NUR Ziffern, höchstens vier. Ein Zusatz wie "7a" ist dort nicht vorgesehen und gehört in addressSuffix.
zipCode string
cityName string
countryCode string
KBA-Staatsschlüssel. Ohne Angabe D.
addressSuffix string
partyType enum
Die Art des Beteiligten. **Freiwillig und zusätzlich** — ohne Angabe gilt wie bisher der Name: `companyName` heisst juristische Person, sonst natürliche Person. - `NATURAL_PERSON`, `LEGAL_PERSON` — die beiden bisherigen Arten, ausdrücklich benannt. - `AUTHORITY` — eine Behörde. Geht im XML als juristische Person hinaus; das Schema kennt keine eigene Art. - `SOLE_TRADER` — Einzelunternehmer. MIT `companyName` juristische Person, OHNE natürliche Person (amtliche Dokumentation zur Vollmacht: „Status als juristische Person wird nur dann zuerkannt, wenn ‚Name des Unternehmens' ausgefüllt ist"). Der Berufs-/Wirtschaftszweigschlüssel ist in beiden Fällen anzugeben — `888` gilt nur für Privatpersonen. - `ASSOCIATION` — eine nicht rechtsfähige Vereinigung, etwa eine GbR ohne Registereintrag oder eine Erbengemeinschaft. Geht als eigene Struktur (`NameVereinigung`) ans KBA, mit optionalem Vertreter. Ein eingetragener Verein ist dagegen eine juristische Person. Erweiterung gegenüber kennzeichen.dev.
NATURAL_PERSON · LEGAL_PERSON · AUTHORITY · SOLE_TRADER · ASSOCIATION
associationRepresentative object
Der benannte Vertreter einer Vereinigung — nur bei `partyType: ASSOCIATION` und dort freiwillig (seit XKfz 6.0 optional). In `POST /powerOfAttorneys` gibt es ihn nicht: Für eine Vereinigung lässt sich über uns keine Vollmacht unterschreiben (siehe `principal`).
firstName string
lastName string
companyName string
dateOfBirth string (date)
Streng als JJJJ-MM-TT. Nur bei natürlichen Personen. Zulässiger Bereich 1880–2099.
placeOfBirth string
Nur bei natürlichen Personen.
occupationKey string
Berufs- bzw. Wirtschaftszweigschlüssel, drei Stellen. Beim Halter einer Zulassung (UG, WG, WZ, NZ, TZ) Pflicht (KBA-Wissensartikel „Angabe des Berufsschlüssels bzw. Wirtschaftszweigs"). Firmen und juristische Personen nehmen den Schlüssel aus dem KBA-Verzeichnis SV 5, etwa `G01` für den Handel mit Kraftfahrzeugen; fehlt er, `400`. Privatpersonen ohne Angabe erhalten "888"; Freiberufler und Einzelunternehmer geben ihren Schlüssel an. Geprüft wird nur die Form. Bei der Halteränderung, beim Bevollmächtigten und beim Lieferungsempfänger optional.
documentBase64 string (byte)
Das unterschriebene Vollmacht-PDF, Base64-kodiert — selbst mitgebracht.
processId integer
Nummer eines Vollmachtsvorgangs, der über diesen Dienst unterschrieben wurde (siehe Self-Service-Bereich, „Vollmachtsvorgänge"). Wir hängen das signierte Dokument dann selbst an und gleichen die Vollmacht vorab gegen die Antragsdaten ab. Ist der Vorgang unbekannt oder gehört er einem anderen Mandanten: 404. Ist er noch nicht unterschrieben: 409, mit seinem Stand in der Meldung — und zwar vor jeder Feldprüfung: Feldfehler und der Abgleich mit der Vollmacht melden sich erst nach der Unterschrift. Ein 400 danach verbraucht den Vorgang nicht; der korrigierte Antrag darf dieselbe processId nennen.
deliveryRecipient object
Abweichender Empfänger der Zulassungsunterlagen.
address* HolderAddress
firstName string
lastName string
companyName string
gender enum
Nur bei natürlichen Personen zulässig.
FEMALE · MALE · DIVERSE · UNSPECIFIED
streetName string
houseNumber string
Laut XKfz-Schema NUR Ziffern, höchstens vier. Ein Zusatz wie "7a" ist dort nicht vorgesehen und gehört in addressSuffix.
zipCode string
cityName string
countryCode string
KBA-Staatsschlüssel. Ohne Angabe D.
addressSuffix string
partyType enum
Die Art des Beteiligten. **Freiwillig und zusätzlich** — ohne Angabe gilt wie bisher der Name: `companyName` heisst juristische Person, sonst natürliche Person. - `NATURAL_PERSON`, `LEGAL_PERSON` — die beiden bisherigen Arten, ausdrücklich benannt. - `AUTHORITY` — eine Behörde. Geht im XML als juristische Person hinaus; das Schema kennt keine eigene Art. - `SOLE_TRADER` — Einzelunternehmer. MIT `companyName` juristische Person, OHNE natürliche Person (amtliche Dokumentation zur Vollmacht: „Status als juristische Person wird nur dann zuerkannt, wenn ‚Name des Unternehmens' ausgefüllt ist"). Der Berufs-/Wirtschaftszweigschlüssel ist in beiden Fällen anzugeben — `888` gilt nur für Privatpersonen. - `ASSOCIATION` — eine nicht rechtsfähige Vereinigung, etwa eine GbR ohne Registereintrag oder eine Erbengemeinschaft. Geht als eigene Struktur (`NameVereinigung`) ans KBA, mit optionalem Vertreter. Ein eingetragener Verein ist dagegen eine juristische Person. Erweiterung gegenüber kennzeichen.dev.
NATURAL_PERSON · LEGAL_PERSON · AUTHORITY · SOLE_TRADER · ASSOCIATION
associationRepresentative object
Der benannte Vertreter einer Vereinigung — nur bei `partyType: ASSOCIATION` und dort freiwillig (seit XKfz 6.0 optional). In `POST /powerOfAttorneys` gibt es ihn nicht: Für eine Vereinigung lässt sich über uns keine Vollmacht unterschreiben (siehe `principal`).
firstName string
lastName string
companyName string
dateOfBirth string (date)
Streng als JJJJ-MM-TT. Nur bei natürlichen Personen. Zulässiger Bereich 1880–2099.
placeOfBirth string
Nur bei natürlichen Personen.
occupationKey string
Berufs- bzw. Wirtschaftszweigschlüssel, drei Stellen. Beim Halter einer Zulassung (UG, WG, WZ, NZ, TZ) Pflicht (KBA-Wissensartikel „Angabe des Berufsschlüssels bzw. Wirtschaftszweigs"). Firmen und juristische Personen nehmen den Schlüssel aus dem KBA-Verzeichnis SV 5, etwa `G01` für den Handel mit Kraftfahrzeugen; fehlt er, `400`. Privatpersonen ohne Angabe erhalten "888"; Freiberufler und Einzelunternehmer geben ihren Schlüssel an. Geprüft wird nur die Form. Bei der Halteränderung, beim Bevollmächtigten und beim Lieferungsempfänger optional.
sepaMandateBase64 string (byte)
SEPA-Mandat als PDF. Anders als bei der Vollmacht ist hier ein Scan zulässig. Entfällt, wenn sich der Antrag über `powerOfAttorney.processId` auf einen Vollmachtsvorgang mit `bankAccount` beruft: Dann hängen wir das dort signierte Mandat an — sofern `bankAccount` hier dieselbe IBAN und denselben Kontoinhaber nennt, sonst `400`. Mitgeschickt hat dieses Feld Vorrang.
bankAccount BankAccount
iban* string
accountHolder* string
usage enum
Steuer · Gebuehren
directDebitMandateGranted boolean
taxDetails TaxDetails
paymentInterval* enum
jaehrlich · halbjaehrlich · vierteljaehrlich
taxLargeCustomerId string
Großkunden-ID der Steuer. Liegt sie vor, entfällt das SEPA-Mandat. Zollform — drei Ziffern, ein Großbuchstabe, vier Ziffern —, seit XKfz 6.0 verbindlich; andere Formen weisen wir mit 400 ab.
taxExemptionRequested boolean
Befreiung von der Kfz-Steuer beantragen. Ohne diese Angabe lässt sich ein Fahrzeug mit Steuerbefreiung — etwa bei Schwerbehinderung — nicht anmelden.
taxExemptionReason string
Grund der Steuerbefreiung. Wird unverändert durchgereicht und nicht gegen eine Liste geprüft: Welche Gründe es gibt, sagen die vorliegenden KBA-Unterlagen nicht; im amtlichen Beispiel steht `18`.
inspections InspectionDetails[]
reportDate string (date)
nextInspection* string
Fälligkeit der nächsten Untersuchung als MMJJJJ.
inspectionType enum
Ohne Angabe wird HU gesendet (Codeliste artderuntersuchung, Klartext „Hauptuntersuchung“). Eine Sicherheitsprüfung muss ausdrücklich SP setzen.
HU · SP
institutionKey string
Schlüsselnummer der Überwachungsinstitution oder des ZDK. Wird ungeprüft durchgereicht und als schluesselnummerDerUeberwachungsinstitutionOderZDK gesendet.
inspectionDate string (date)
expressProcedure boolean
checkDigit string
deliveries DeliveryInstruction[]
deliveryService* enum
Zustellweg (Codeliste lieferdienst). AbholungBevollmaechtigter ist die Abholung durch den Bevollmächtigten — vom KBA am 14.05.2024 bestätigt, in keinem amtlichen Beispiel enthalten.
ZusendungHalter · ZusendungBevollmaechtigter · ZusendungDritter · Abholung · AbholungHalter · AbholungBevollmaechtigter
deliverTo enum
Wessen Anschrift gilt — hat Vorrang vor dem deliveryService. Ohne Angabe benennt der deliveryService den Empfänger (ZusendungHalter und AbholungHalter den Halter, ZusendungDritter den deliveryRecipient und so fort); benennt auch er niemanden (Abholung), gilt der deliveryRecipient, sonst der Bevollmächtigte, sonst der Halter. Verglichen wird gegen die Vollmacht, wer nach dieser Regel wirklich beliefert wird: ZusendungHalter mit deliverTo RECIPIENT gilt als Lieferung an den Dritten und ergibt gegen eine Vollmacht „an den Halter" 400.
HOLDER · REPRESENTATIVE · RECIPIENT
orderedAt string (date)
items* DeliveryItem[]
documentType* string
Codeliste artderunterlage — 2 ZB I, 3 ZB II, 27 HU-Plakette, 37 Siegelplakette, 39 HU-Plakettenträger, 42 Beiblatt zur ZB I, 40 Stempelplakettenträger (44 in älteren Beispielen, wird weiter angenommen).
quantity* integer
email* string (email)
externalOrderId string
Ihre eigene Auftragsreferenz. Wird in Webhook-Events zurückgegeben — und ist zugleich der Schutz gegen den doppelt gestellten Antrag: Derselbe Mandant, dieselbe `externalOrderId`, dieselbe FIN UND derselbe Geschäftsvorfall (Endpunkt) innerhalb von 15 Minuten gelten als Wiederholungsversuch. Es geht dann NICHTS erneut an das KBA, und die Antwort nennt den bestehenden Vorgang (HTTP 200, dieselbe `order.id`). So führt eine Zeitüberschreitung samt automatischer Wiederholung Ihres Clients nicht zu zwei Anträgen und zwei Gebühren. Ohne Referenz greift der Schutz nicht — dann fehlt die Aussage „das ist derselbe Auftrag". **Weichen die Daten ab, ist es kein Wiederholungsversuch:** Dieselbe Referenz und FIN mit geändertem Inhalt beantwortet der Dienst mit **409** und ändert nichts. Weder darf er die Korrektur still verwerfen noch ungefragt einen zweiten Antrag samt Gebühr auslösen. Für einen weiteren Antrag eine eigene Referenz vergeben; für eine Berichtigung den bestehenden Vorgang korrigieren. **Dieselbe Referenz an einem anderen Endpunkt** — etwa NZ statt TZ oder WG statt WZ — ist kein Wiederholungsversuch, sondern ein neuer Antrag samt Gebühr. Ein falsch gewählter Endpunkt lässt sich nicht durch erneutes Senden unter derselben Referenz berichtigen.
correctionOf integer (int64)
Vorgangsnummer eines abgewiesenen oder fehlgeschlagenen Auftrags, der mit diesem Rumpf korrigiert werden soll. Es entsteht ein neuer KBA-Versuch am selben Auftrag; die Antwort nennt `attemptOf` und `attempt`. Laufende oder beschiedene Aufträge sowie ein anderer Geschäftsvorfall ergeben 409.
gksConfigurationId string (uuid)
{
  "externalOrderId": "umschreibung-4711",
  "email": "kunde@example.de",
  "customization": {
    "vehicleIdentificationNumber": "WVWZZZ7HZ8H123456",
    "licensePlateNumberComponents": {
      "usageType": "EURO",
      "city": "SL",
      "middle": "OA",
      "end": "1417"
    },
    "vehicleRegistrationCertificateSecurityCode": "2H5Fktp",
    "vehicleRegistrationCertificatePartII": {
      "number": "ZZ112976",
      "securityCode": "BgDwroY6tly4"
    },
    "insuranceConfirmationNumber": "R245654"
  },
  "vehicleHolder": {
    "address": {
      "companyName": "Chaos-Klempnerei Wassermarsch OHG",
      "streetName": "Am Bahnhof",
      "houseNumber": "15",
      "zipCode": "24983",
      "cityName": "Handewitt",
      "countryCode": "D"
    },
    "occupationKey": "F00"
  },
  "taxDetails": {
    "paymentInterval": "jaehrlich",
    "taxLargeCustomerId": "123A4567"
  }
}

Antworten

200 Der Antrag wurde angenommen.
order* object
id* integer (int64)
attemptOf integer (int64)
Nur bei einer Korrektur — die Auftragsnummer der Versuchskette.
attempt integer
Nur bei einer Korrektur — die laufende Nummer des neuen Versuchs.
{
  "order": {
    "id": 1
  }
}
400
401
403
404
409
413
415
500
503
default
POST/vehicleReRegistrations/reRegistrationsWiederzulassung beauftragen

Wiederzulassung eines außer Betrieb gesetzten Fahrzeugs (höchstens sieben Jahre). Pflicht über die gemeinsamen Angaben hinaus (siehe `VehicleRegistrationRequest`): der Sicherheitscode der **ZB II** (`customization.vehicleRegistrationCertificatePartII.securityCode`) und **das bisherige Kennzeichen** laut Zulassungsbescheinigung Teil I in `licensePlateNumberComponents` — ohne es antworten wir mit 400. Die GKS verlangt es auch dann, wenn ein neues Kennzeichen zugeteilt wird. Die Codes der Stempelplaketten gehören in `licensePlateSeals`. - Ein bei der Außerbetriebsetzung reserviertes Kennzeichen ist an das Fahrzeug gebunden; dazu gibt es keine PIN. Das bisherige Kennzeichen allein genügt. - Soll ein anderes Kennzeichen zugeteilt werden, kommt `licensePlateAssignment` hinzu: `reservation` für eine bei der Zulassungsbehörde erwirkte Reservierung samt PIN, sonst `plateType` für das nächste freie Kennzeichen. Ereignistyp: `VEHICLE_REREGISTRATION_XKFZ_EVENT`.

Request application/json

requestRegistrationData boolean
Fordert die strukturierten Zulassungsdaten an (ZB I und ZB II, ueber sechzig Angaben). Ohne sie kommt nur der Bescheid als PDF zurueck. Die Daten erscheinen als `registrationData` in der Vorgangsauskunft und im Webhook-Ereignis. Bei einem Antrag mit Vollmacht muss sie das Kreuz „erweiterte Datenbereitstellung" tragen (`extendedDataProvision` im Vollmachtsvorgang), sonst antwortet der Antrag mit 400 — geprüft, sofern sich die Vollmacht als Formular lesen lässt.
orderEmissionSticker boolean
Feinstaubplakette mitbestellen; erweitert die Lieferung um eine Position (Festlegungen zum elektronischen Antrag, Blatt „GK NZ").
customization* VehicleRegistrationCustomization
vehicleIdentificationNumber* string
licensePlateNumberComponents object
Bisheriges Kennzeichen — bei Umschreibung Pflicht.
usageType enum
Kennzeichenmerkmal — für alle Anträge mit bisherigem Kennzeichen (AB, HA, UG, WG, WZ): EURO (Normalfall), ELECTRIC (Elektrokennzeichen) und HISTORIC (Oldtimerkennzeichen); andere Werte werden mit HTTP 400 abgewiesen.
EURO · ELECTRIC · HISTORIC
city* string
Unterscheidungszeichen, 1–3 Buchstaben (Umlaute zulässig). Kleinbuchstaben werden großgeschrieben; das Muster lässt sie deshalb zu.
middle* string
Erkennungsbuchstaben, 1–2 Buchstaben ohne Umlaute. Kleinbuchstaben werden großgeschrieben.
end* string
Erkennungsnummer, 1–4 Ziffern.
licensePlateSeals LicensePlateSeal[]
Codes der Stempelplaketten des bisherigen Kennzeichens — nur zusammen mit licensePlateNumberComponents wirksam. Ohne bisheriges Kennzeichen (immer bei NZ und TZ) werden die Einträge geprüft, aber nicht übermittelt.
position* enum
vorn · hinten · beide
securityCode string
Dreistelliger Code unter der Stempelplakette.
licensePlateAssignment object
Neues Kennzeichen zuteilen. Ein Wunschkennzeichen lässt sich über die GKS NICHT reservieren — entweder eine vorab bei der Zulassungsbehörde erwirkte Reservierung samt PIN, oder das nächste freie Kennzeichen.
reservation object
licensePlate* string
pin* string
plateType enum
Kennzeichenart nach dem amtlichen Schema (typ-MerkmalKennzeichenart-ZFZR). Z ist der Regelfall, B das Behördenkennzeichen. Pflicht, sobald das nächste freie Kennzeichen angefordert wird (keine `reservation`); fehlt sie, antworten wir mit 400. Saisonkennzeichen (ZS, BS) sind vorerst nicht beantragbar und werden mit 400 abgewiesen: Der Betriebszeitraum lässt sich im Antrag nicht angeben, und die Frage dazu ist beim KBA offen. Die übrigen Arten des Schemas — Ausfuhrkennzeichen (A), rotes Kennzeichen (R), Kurzzeitkennzeichen (RK) und Versicherungskennzeichen (V, VR) — lassen sich über die GKS nicht beantragen. Bescheide des KBA können dennoch jede Art melden.
B · Z
electric boolean
historic boolean
vehicleRegistrationCertificateSecurityCode string
vehicleRegistrationCertificateNumber string
Nummer der ZB I, 18–20 Zeichen, Buchstabe am Anfang. Kleinbuchstaben werden großgeschrieben.
vehicleRegistrationCertificateImprintNumber string
Druckstücknummer der ZB I. Acht Zeichen: Großbuchstabe, sechs Ziffern oder Großbuchstaben, zuletzt Ziffer oder X (Schema XKfz 6.0, Type.Druckstuecknummer).
vehicleRegistrationCertificatePartII object
number string
Nummer der ZB II. Kleinbuchstaben werden großgeschrieben. OHNEZBII und ohne-ZF- sind die amtlichen Platzhalter für Fahrzeuge ohne Teil II.
securityCode string
Zwölfstellig, Modulo-11-geprüft. Wird bereits hier vorgeprüft, verbindlich prüft das KBA.
insuranceConfirmationNumber* string
eVB-Nummer. Ohne sie ist keine Zulassung möglich.
vehicleUsage enum
Fahrzeugverwendung nach dem amtlichen Schema (typ-VerwendungFahrzeug). Muss zur eVB passen.
B · C · D · E · F · G · K · L · M · S · T · X
customerNumber string
contractPartner ContractPartner
vehicleHolder object
Der künftige Halter. Pflicht — AUSSER der Antrag beruft sich über `powerOfAttorney.processId` auf einen Vollmachtsvorgang, zu dem der Vertrauensdienst die Person bereits festgestellt hat. Dann setzen wir den Halter aus dessen Daten ein, und mitgeschickte Angaben werden überschrieben. Grund ist das BMDV-Schreiben vom 25.04.2024 (Az. 7362.8/1): Die Halterdaten stammen ausschliesslich vom Vertrauensdiensteanbieter, nicht aus der Kundeneingabe. § 38 Abs. 4 FZV sagt dasselbe — die Halterangaben sind der das Vollmachtsformular verarbeitenden Nachricht zu entnehmen. Bei Zulassungen (UG, WG, WZ, NZ, TZ) ersetzen wir mitgeschickte Halterangaben deshalb durch die des Vertrauensdienstes — es gibt dafür kein 400; Vorgangsauskunft und Dashboard zeigen den gesendeten Halter. Ergänzt wird nur, was kein Vertrauensdienst feststellt (`occupationKey`, `address.gender`; bei einer Firma nur `occupationKey`). Ohne `occupationKey` gilt der in der Vollmacht unterschriebene Wirtschaftszweig; `vehicleHolder: { occupationKey }` allein genügt. 400 kommt nur, wenn die Daten des Vertrauensdienstes nicht zur unterschriebenen Vollmacht passen, der mitgeschickte `occupationKey` vom in der Vollmacht unterschriebenen Wirtschaftszweig abweicht oder eine Firma an beiden Stellen keinen `occupationKey` führt. Anders die Halteränderung: Dort ist die neue Anschrift der Antrag selbst und muss der festgestellten entsprechen, sonst 400 (siehe `VehicleHolderChangeRequest`).
address* HolderAddress
firstName string
lastName string
companyName string
gender enum
Nur bei natürlichen Personen zulässig.
FEMALE · MALE · DIVERSE · UNSPECIFIED
streetName string
houseNumber string
Laut XKfz-Schema NUR Ziffern, höchstens vier. Ein Zusatz wie "7a" ist dort nicht vorgesehen und gehört in addressSuffix.
zipCode string
cityName string
countryCode string
KBA-Staatsschlüssel. Ohne Angabe D.
addressSuffix string
partyType enum
Die Art des Beteiligten. **Freiwillig und zusätzlich** — ohne Angabe gilt wie bisher der Name: `companyName` heisst juristische Person, sonst natürliche Person. - `NATURAL_PERSON`, `LEGAL_PERSON` — die beiden bisherigen Arten, ausdrücklich benannt. - `AUTHORITY` — eine Behörde. Geht im XML als juristische Person hinaus; das Schema kennt keine eigene Art. - `SOLE_TRADER` — Einzelunternehmer. MIT `companyName` juristische Person, OHNE natürliche Person (amtliche Dokumentation zur Vollmacht: „Status als juristische Person wird nur dann zuerkannt, wenn ‚Name des Unternehmens' ausgefüllt ist"). Der Berufs-/Wirtschaftszweigschlüssel ist in beiden Fällen anzugeben — `888` gilt nur für Privatpersonen. - `ASSOCIATION` — eine nicht rechtsfähige Vereinigung, etwa eine GbR ohne Registereintrag oder eine Erbengemeinschaft. Geht als eigene Struktur (`NameVereinigung`) ans KBA, mit optionalem Vertreter. Ein eingetragener Verein ist dagegen eine juristische Person. Erweiterung gegenüber kennzeichen.dev.
NATURAL_PERSON · LEGAL_PERSON · AUTHORITY · SOLE_TRADER · ASSOCIATION
associationRepresentative object
Der benannte Vertreter einer Vereinigung — nur bei `partyType: ASSOCIATION` und dort freiwillig (seit XKfz 6.0 optional). In `POST /powerOfAttorneys` gibt es ihn nicht: Für eine Vereinigung lässt sich über uns keine Vollmacht unterschreiben (siehe `principal`).
firstName string
lastName string
companyName string
dateOfBirth string (date)
Streng als JJJJ-MM-TT. Nur bei natürlichen Personen. Zulässiger Bereich 1880–2099.
placeOfBirth string
Nur bei natürlichen Personen.
occupationKey string
Berufs- bzw. Wirtschaftszweigschlüssel, drei Stellen. Beim Halter einer Zulassung (UG, WG, WZ, NZ, TZ) Pflicht (KBA-Wissensartikel „Angabe des Berufsschlüssels bzw. Wirtschaftszweigs"). Firmen und juristische Personen nehmen den Schlüssel aus dem KBA-Verzeichnis SV 5, etwa `G01` für den Handel mit Kraftfahrzeugen; fehlt er, `400`. Privatpersonen ohne Angabe erhalten "888"; Freiberufler und Einzelunternehmer geben ihren Schlüssel an. Geprüft wird nur die Form. Bei der Halteränderung, beim Bevollmächtigten und beim Lieferungsempfänger optional.
powerOfAttorney PowerOfAttorney
representative HolderParty
address* HolderAddress
firstName string
lastName string
companyName string
gender enum
Nur bei natürlichen Personen zulässig.
FEMALE · MALE · DIVERSE · UNSPECIFIED
streetName string
houseNumber string
Laut XKfz-Schema NUR Ziffern, höchstens vier. Ein Zusatz wie "7a" ist dort nicht vorgesehen und gehört in addressSuffix.
zipCode string
cityName string
countryCode string
KBA-Staatsschlüssel. Ohne Angabe D.
addressSuffix string
partyType enum
Die Art des Beteiligten. **Freiwillig und zusätzlich** — ohne Angabe gilt wie bisher der Name: `companyName` heisst juristische Person, sonst natürliche Person. - `NATURAL_PERSON`, `LEGAL_PERSON` — die beiden bisherigen Arten, ausdrücklich benannt. - `AUTHORITY` — eine Behörde. Geht im XML als juristische Person hinaus; das Schema kennt keine eigene Art. - `SOLE_TRADER` — Einzelunternehmer. MIT `companyName` juristische Person, OHNE natürliche Person (amtliche Dokumentation zur Vollmacht: „Status als juristische Person wird nur dann zuerkannt, wenn ‚Name des Unternehmens' ausgefüllt ist"). Der Berufs-/Wirtschaftszweigschlüssel ist in beiden Fällen anzugeben — `888` gilt nur für Privatpersonen. - `ASSOCIATION` — eine nicht rechtsfähige Vereinigung, etwa eine GbR ohne Registereintrag oder eine Erbengemeinschaft. Geht als eigene Struktur (`NameVereinigung`) ans KBA, mit optionalem Vertreter. Ein eingetragener Verein ist dagegen eine juristische Person. Erweiterung gegenüber kennzeichen.dev.
NATURAL_PERSON · LEGAL_PERSON · AUTHORITY · SOLE_TRADER · ASSOCIATION
associationRepresentative object
Der benannte Vertreter einer Vereinigung — nur bei `partyType: ASSOCIATION` und dort freiwillig (seit XKfz 6.0 optional). In `POST /powerOfAttorneys` gibt es ihn nicht: Für eine Vereinigung lässt sich über uns keine Vollmacht unterschreiben (siehe `principal`).
firstName string
lastName string
companyName string
dateOfBirth string (date)
Streng als JJJJ-MM-TT. Nur bei natürlichen Personen. Zulässiger Bereich 1880–2099.
placeOfBirth string
Nur bei natürlichen Personen.
occupationKey string
Berufs- bzw. Wirtschaftszweigschlüssel, drei Stellen. Beim Halter einer Zulassung (UG, WG, WZ, NZ, TZ) Pflicht (KBA-Wissensartikel „Angabe des Berufsschlüssels bzw. Wirtschaftszweigs"). Firmen und juristische Personen nehmen den Schlüssel aus dem KBA-Verzeichnis SV 5, etwa `G01` für den Handel mit Kraftfahrzeugen; fehlt er, `400`. Privatpersonen ohne Angabe erhalten "888"; Freiberufler und Einzelunternehmer geben ihren Schlüssel an. Geprüft wird nur die Form. Bei der Halteränderung, beim Bevollmächtigten und beim Lieferungsempfänger optional.
documentBase64 string (byte)
Das unterschriebene Vollmacht-PDF, Base64-kodiert — selbst mitgebracht.
processId integer
Nummer eines Vollmachtsvorgangs, der über diesen Dienst unterschrieben wurde (siehe Self-Service-Bereich, „Vollmachtsvorgänge"). Wir hängen das signierte Dokument dann selbst an und gleichen die Vollmacht vorab gegen die Antragsdaten ab. Ist der Vorgang unbekannt oder gehört er einem anderen Mandanten: 404. Ist er noch nicht unterschrieben: 409, mit seinem Stand in der Meldung — und zwar vor jeder Feldprüfung: Feldfehler und der Abgleich mit der Vollmacht melden sich erst nach der Unterschrift. Ein 400 danach verbraucht den Vorgang nicht; der korrigierte Antrag darf dieselbe processId nennen.
deliveryRecipient object
Abweichender Empfänger der Zulassungsunterlagen.
address* HolderAddress
firstName string
lastName string
companyName string
gender enum
Nur bei natürlichen Personen zulässig.
FEMALE · MALE · DIVERSE · UNSPECIFIED
streetName string
houseNumber string
Laut XKfz-Schema NUR Ziffern, höchstens vier. Ein Zusatz wie "7a" ist dort nicht vorgesehen und gehört in addressSuffix.
zipCode string
cityName string
countryCode string
KBA-Staatsschlüssel. Ohne Angabe D.
addressSuffix string
partyType enum
Die Art des Beteiligten. **Freiwillig und zusätzlich** — ohne Angabe gilt wie bisher der Name: `companyName` heisst juristische Person, sonst natürliche Person. - `NATURAL_PERSON`, `LEGAL_PERSON` — die beiden bisherigen Arten, ausdrücklich benannt. - `AUTHORITY` — eine Behörde. Geht im XML als juristische Person hinaus; das Schema kennt keine eigene Art. - `SOLE_TRADER` — Einzelunternehmer. MIT `companyName` juristische Person, OHNE natürliche Person (amtliche Dokumentation zur Vollmacht: „Status als juristische Person wird nur dann zuerkannt, wenn ‚Name des Unternehmens' ausgefüllt ist"). Der Berufs-/Wirtschaftszweigschlüssel ist in beiden Fällen anzugeben — `888` gilt nur für Privatpersonen. - `ASSOCIATION` — eine nicht rechtsfähige Vereinigung, etwa eine GbR ohne Registereintrag oder eine Erbengemeinschaft. Geht als eigene Struktur (`NameVereinigung`) ans KBA, mit optionalem Vertreter. Ein eingetragener Verein ist dagegen eine juristische Person. Erweiterung gegenüber kennzeichen.dev.
NATURAL_PERSON · LEGAL_PERSON · AUTHORITY · SOLE_TRADER · ASSOCIATION
associationRepresentative object
Der benannte Vertreter einer Vereinigung — nur bei `partyType: ASSOCIATION` und dort freiwillig (seit XKfz 6.0 optional). In `POST /powerOfAttorneys` gibt es ihn nicht: Für eine Vereinigung lässt sich über uns keine Vollmacht unterschreiben (siehe `principal`).
firstName string
lastName string
companyName string
dateOfBirth string (date)
Streng als JJJJ-MM-TT. Nur bei natürlichen Personen. Zulässiger Bereich 1880–2099.
placeOfBirth string
Nur bei natürlichen Personen.
occupationKey string
Berufs- bzw. Wirtschaftszweigschlüssel, drei Stellen. Beim Halter einer Zulassung (UG, WG, WZ, NZ, TZ) Pflicht (KBA-Wissensartikel „Angabe des Berufsschlüssels bzw. Wirtschaftszweigs"). Firmen und juristische Personen nehmen den Schlüssel aus dem KBA-Verzeichnis SV 5, etwa `G01` für den Handel mit Kraftfahrzeugen; fehlt er, `400`. Privatpersonen ohne Angabe erhalten "888"; Freiberufler und Einzelunternehmer geben ihren Schlüssel an. Geprüft wird nur die Form. Bei der Halteränderung, beim Bevollmächtigten und beim Lieferungsempfänger optional.
sepaMandateBase64 string (byte)
SEPA-Mandat als PDF. Anders als bei der Vollmacht ist hier ein Scan zulässig. Entfällt, wenn sich der Antrag über `powerOfAttorney.processId` auf einen Vollmachtsvorgang mit `bankAccount` beruft: Dann hängen wir das dort signierte Mandat an — sofern `bankAccount` hier dieselbe IBAN und denselben Kontoinhaber nennt, sonst `400`. Mitgeschickt hat dieses Feld Vorrang.
bankAccount BankAccount
iban* string
accountHolder* string
usage enum
Steuer · Gebuehren
directDebitMandateGranted boolean
taxDetails TaxDetails
paymentInterval* enum
jaehrlich · halbjaehrlich · vierteljaehrlich
taxLargeCustomerId string
Großkunden-ID der Steuer. Liegt sie vor, entfällt das SEPA-Mandat. Zollform — drei Ziffern, ein Großbuchstabe, vier Ziffern —, seit XKfz 6.0 verbindlich; andere Formen weisen wir mit 400 ab.
taxExemptionRequested boolean
Befreiung von der Kfz-Steuer beantragen. Ohne diese Angabe lässt sich ein Fahrzeug mit Steuerbefreiung — etwa bei Schwerbehinderung — nicht anmelden.
taxExemptionReason string
Grund der Steuerbefreiung. Wird unverändert durchgereicht und nicht gegen eine Liste geprüft: Welche Gründe es gibt, sagen die vorliegenden KBA-Unterlagen nicht; im amtlichen Beispiel steht `18`.
inspections InspectionDetails[]
reportDate string (date)
nextInspection* string
Fälligkeit der nächsten Untersuchung als MMJJJJ.
inspectionType enum
Ohne Angabe wird HU gesendet (Codeliste artderuntersuchung, Klartext „Hauptuntersuchung“). Eine Sicherheitsprüfung muss ausdrücklich SP setzen.
HU · SP
institutionKey string
Schlüsselnummer der Überwachungsinstitution oder des ZDK. Wird ungeprüft durchgereicht und als schluesselnummerDerUeberwachungsinstitutionOderZDK gesendet.
inspectionDate string (date)
expressProcedure boolean
checkDigit string
deliveries DeliveryInstruction[]
deliveryService* enum
Zustellweg (Codeliste lieferdienst). AbholungBevollmaechtigter ist die Abholung durch den Bevollmächtigten — vom KBA am 14.05.2024 bestätigt, in keinem amtlichen Beispiel enthalten.
ZusendungHalter · ZusendungBevollmaechtigter · ZusendungDritter · Abholung · AbholungHalter · AbholungBevollmaechtigter
deliverTo enum
Wessen Anschrift gilt — hat Vorrang vor dem deliveryService. Ohne Angabe benennt der deliveryService den Empfänger (ZusendungHalter und AbholungHalter den Halter, ZusendungDritter den deliveryRecipient und so fort); benennt auch er niemanden (Abholung), gilt der deliveryRecipient, sonst der Bevollmächtigte, sonst der Halter. Verglichen wird gegen die Vollmacht, wer nach dieser Regel wirklich beliefert wird: ZusendungHalter mit deliverTo RECIPIENT gilt als Lieferung an den Dritten und ergibt gegen eine Vollmacht „an den Halter" 400.
HOLDER · REPRESENTATIVE · RECIPIENT
orderedAt string (date)
items* DeliveryItem[]
documentType* string
Codeliste artderunterlage — 2 ZB I, 3 ZB II, 27 HU-Plakette, 37 Siegelplakette, 39 HU-Plakettenträger, 42 Beiblatt zur ZB I, 40 Stempelplakettenträger (44 in älteren Beispielen, wird weiter angenommen).
quantity* integer
email* string (email)
externalOrderId string
Ihre eigene Auftragsreferenz. Wird in Webhook-Events zurückgegeben — und ist zugleich der Schutz gegen den doppelt gestellten Antrag: Derselbe Mandant, dieselbe `externalOrderId`, dieselbe FIN UND derselbe Geschäftsvorfall (Endpunkt) innerhalb von 15 Minuten gelten als Wiederholungsversuch. Es geht dann NICHTS erneut an das KBA, und die Antwort nennt den bestehenden Vorgang (HTTP 200, dieselbe `order.id`). So führt eine Zeitüberschreitung samt automatischer Wiederholung Ihres Clients nicht zu zwei Anträgen und zwei Gebühren. Ohne Referenz greift der Schutz nicht — dann fehlt die Aussage „das ist derselbe Auftrag". **Weichen die Daten ab, ist es kein Wiederholungsversuch:** Dieselbe Referenz und FIN mit geändertem Inhalt beantwortet der Dienst mit **409** und ändert nichts. Weder darf er die Korrektur still verwerfen noch ungefragt einen zweiten Antrag samt Gebühr auslösen. Für einen weiteren Antrag eine eigene Referenz vergeben; für eine Berichtigung den bestehenden Vorgang korrigieren. **Dieselbe Referenz an einem anderen Endpunkt** — etwa NZ statt TZ oder WG statt WZ — ist kein Wiederholungsversuch, sondern ein neuer Antrag samt Gebühr. Ein falsch gewählter Endpunkt lässt sich nicht durch erneutes Senden unter derselben Referenz berichtigen.
correctionOf integer (int64)
Vorgangsnummer eines abgewiesenen oder fehlgeschlagenen Auftrags, der mit diesem Rumpf korrigiert werden soll. Es entsteht ein neuer KBA-Versuch am selben Auftrag; die Antwort nennt `attemptOf` und `attempt`. Laufende oder beschiedene Aufträge sowie ein anderer Geschäftsvorfall ergeben 409.
gksConfigurationId string (uuid)
{
  "externalOrderId": "wiederzulassung-4711",
  "email": "kunde@example.de",
  "customization": {
    "vehicleIdentificationNumber": "WVWZZZ7HZ8H111111",
    "licensePlateNumberComponents": {
      "city": "SL",
      "middle": "OA",
      "end": "1417"
    },
    "licensePlateSeals": [
      {
        "position": "vorn",
        "securityCode": "5t2"
      },
      {
        "position": "hinten",
        "securityCode": "6b4"
      }
    ],
    "licensePlateAssignment": {
      "plateType": "Z"
    },
    "vehicleRegistrationCertificatePartII": {
      "number": "ZZ112978",
      "securityCode": "BgDwroY6tly4"
    },
    "insuranceConfirmationNumber": "R245654"
  },
  "vehicleHolder": {
    "address": {
      "companyName": "Chaos-Klempnerei Wassermarsch OHG",
      "streetName": "Am Bahnhof",
      "houseNumber": "15",
      "zipCode": "24983",
      "cityName": "Handewitt",
      "countryCode": "D"
    },
    "occupationKey": "F00"
  },
  "taxDetails": {
    "paymentInterval": "jaehrlich",
    "taxLargeCustomerId": "123A4567"
  }
}

Antworten

200 Der Antrag wurde angenommen.
order* object
id* integer (int64)
attemptOf integer (int64)
Nur bei einer Korrektur — die Auftragsnummer der Versuchskette.
attempt integer
Nur bei einer Korrektur — die laufende Nummer des neuen Versuchs.
{
  "order": {
    "id": 1
  }
}
400
401
403
404
409
413
415
500
503
default
POST/vehicleReRegistrations/sameHolderReRegistrationsWiederzulassung auf denselben Halter beauftragen

Wiederzulassung eines außer Betrieb gesetzten Fahrzeugs, bei der sich **weder Halter noch Zulassungsbezirk noch Kennzeichen** ändern (Geschäftsvorfall WZ). Ändert sich eines davon, ist statt dessen `POST /vehicleReRegistrations/reRegistrations` zu verwenden (WG). Die Unterscheidung steckt bewusst im Endpunkt und nicht im Rumpf: Ein Aufrufer kann den Geschäftsvorfall so nicht versehentlich verstellen, und das KBA weist den falschen Vorfall zurück. Pflicht sind allein die gemeinsamen Angaben (siehe `VehicleRegistrationRequest`). Das bisherige Kennzeichen und die Zulassungsbescheinigung Teil II dürfen mitgegeben werden. Ereignistyp: `VEHICLE_REREGISTRATION_XKFZ_EVENT` — derselbe wie bei der Wiederzulassung mit Halterwechsel.

Request application/json

requestRegistrationData boolean
Fordert die strukturierten Zulassungsdaten an (ZB I und ZB II, ueber sechzig Angaben). Ohne sie kommt nur der Bescheid als PDF zurueck. Die Daten erscheinen als `registrationData` in der Vorgangsauskunft und im Webhook-Ereignis. Bei einem Antrag mit Vollmacht muss sie das Kreuz „erweiterte Datenbereitstellung" tragen (`extendedDataProvision` im Vollmachtsvorgang), sonst antwortet der Antrag mit 400 — geprüft, sofern sich die Vollmacht als Formular lesen lässt.
orderEmissionSticker boolean
Feinstaubplakette mitbestellen; erweitert die Lieferung um eine Position (Festlegungen zum elektronischen Antrag, Blatt „GK NZ").
customization* VehicleRegistrationCustomization
vehicleIdentificationNumber* string
licensePlateNumberComponents object
Bisheriges Kennzeichen — bei Umschreibung Pflicht.
usageType enum
Kennzeichenmerkmal — für alle Anträge mit bisherigem Kennzeichen (AB, HA, UG, WG, WZ): EURO (Normalfall), ELECTRIC (Elektrokennzeichen) und HISTORIC (Oldtimerkennzeichen); andere Werte werden mit HTTP 400 abgewiesen.
EURO · ELECTRIC · HISTORIC
city* string
Unterscheidungszeichen, 1–3 Buchstaben (Umlaute zulässig). Kleinbuchstaben werden großgeschrieben; das Muster lässt sie deshalb zu.
middle* string
Erkennungsbuchstaben, 1–2 Buchstaben ohne Umlaute. Kleinbuchstaben werden großgeschrieben.
end* string
Erkennungsnummer, 1–4 Ziffern.
licensePlateSeals LicensePlateSeal[]
Codes der Stempelplaketten des bisherigen Kennzeichens — nur zusammen mit licensePlateNumberComponents wirksam. Ohne bisheriges Kennzeichen (immer bei NZ und TZ) werden die Einträge geprüft, aber nicht übermittelt.
position* enum
vorn · hinten · beide
securityCode string
Dreistelliger Code unter der Stempelplakette.
licensePlateAssignment object
Neues Kennzeichen zuteilen. Ein Wunschkennzeichen lässt sich über die GKS NICHT reservieren — entweder eine vorab bei der Zulassungsbehörde erwirkte Reservierung samt PIN, oder das nächste freie Kennzeichen.
reservation object
licensePlate* string
pin* string
plateType enum
Kennzeichenart nach dem amtlichen Schema (typ-MerkmalKennzeichenart-ZFZR). Z ist der Regelfall, B das Behördenkennzeichen. Pflicht, sobald das nächste freie Kennzeichen angefordert wird (keine `reservation`); fehlt sie, antworten wir mit 400. Saisonkennzeichen (ZS, BS) sind vorerst nicht beantragbar und werden mit 400 abgewiesen: Der Betriebszeitraum lässt sich im Antrag nicht angeben, und die Frage dazu ist beim KBA offen. Die übrigen Arten des Schemas — Ausfuhrkennzeichen (A), rotes Kennzeichen (R), Kurzzeitkennzeichen (RK) und Versicherungskennzeichen (V, VR) — lassen sich über die GKS nicht beantragen. Bescheide des KBA können dennoch jede Art melden.
B · Z
electric boolean
historic boolean
vehicleRegistrationCertificateSecurityCode string
vehicleRegistrationCertificateNumber string
Nummer der ZB I, 18–20 Zeichen, Buchstabe am Anfang. Kleinbuchstaben werden großgeschrieben.
vehicleRegistrationCertificateImprintNumber string
Druckstücknummer der ZB I. Acht Zeichen: Großbuchstabe, sechs Ziffern oder Großbuchstaben, zuletzt Ziffer oder X (Schema XKfz 6.0, Type.Druckstuecknummer).
vehicleRegistrationCertificatePartII object
number string
Nummer der ZB II. Kleinbuchstaben werden großgeschrieben. OHNEZBII und ohne-ZF- sind die amtlichen Platzhalter für Fahrzeuge ohne Teil II.
securityCode string
Zwölfstellig, Modulo-11-geprüft. Wird bereits hier vorgeprüft, verbindlich prüft das KBA.
insuranceConfirmationNumber* string
eVB-Nummer. Ohne sie ist keine Zulassung möglich.
vehicleUsage enum
Fahrzeugverwendung nach dem amtlichen Schema (typ-VerwendungFahrzeug). Muss zur eVB passen.
B · C · D · E · F · G · K · L · M · S · T · X
customerNumber string
contractPartner ContractPartner
vehicleHolder object
Der künftige Halter. Pflicht — AUSSER der Antrag beruft sich über `powerOfAttorney.processId` auf einen Vollmachtsvorgang, zu dem der Vertrauensdienst die Person bereits festgestellt hat. Dann setzen wir den Halter aus dessen Daten ein, und mitgeschickte Angaben werden überschrieben. Grund ist das BMDV-Schreiben vom 25.04.2024 (Az. 7362.8/1): Die Halterdaten stammen ausschliesslich vom Vertrauensdiensteanbieter, nicht aus der Kundeneingabe. § 38 Abs. 4 FZV sagt dasselbe — die Halterangaben sind der das Vollmachtsformular verarbeitenden Nachricht zu entnehmen. Bei Zulassungen (UG, WG, WZ, NZ, TZ) ersetzen wir mitgeschickte Halterangaben deshalb durch die des Vertrauensdienstes — es gibt dafür kein 400; Vorgangsauskunft und Dashboard zeigen den gesendeten Halter. Ergänzt wird nur, was kein Vertrauensdienst feststellt (`occupationKey`, `address.gender`; bei einer Firma nur `occupationKey`). Ohne `occupationKey` gilt der in der Vollmacht unterschriebene Wirtschaftszweig; `vehicleHolder: { occupationKey }` allein genügt. 400 kommt nur, wenn die Daten des Vertrauensdienstes nicht zur unterschriebenen Vollmacht passen, der mitgeschickte `occupationKey` vom in der Vollmacht unterschriebenen Wirtschaftszweig abweicht oder eine Firma an beiden Stellen keinen `occupationKey` führt. Anders die Halteränderung: Dort ist die neue Anschrift der Antrag selbst und muss der festgestellten entsprechen, sonst 400 (siehe `VehicleHolderChangeRequest`).
address* HolderAddress
firstName string
lastName string
companyName string
gender enum
Nur bei natürlichen Personen zulässig.
FEMALE · MALE · DIVERSE · UNSPECIFIED
streetName string
houseNumber string
Laut XKfz-Schema NUR Ziffern, höchstens vier. Ein Zusatz wie "7a" ist dort nicht vorgesehen und gehört in addressSuffix.
zipCode string
cityName string
countryCode string
KBA-Staatsschlüssel. Ohne Angabe D.
addressSuffix string
partyType enum
Die Art des Beteiligten. **Freiwillig und zusätzlich** — ohne Angabe gilt wie bisher der Name: `companyName` heisst juristische Person, sonst natürliche Person. - `NATURAL_PERSON`, `LEGAL_PERSON` — die beiden bisherigen Arten, ausdrücklich benannt. - `AUTHORITY` — eine Behörde. Geht im XML als juristische Person hinaus; das Schema kennt keine eigene Art. - `SOLE_TRADER` — Einzelunternehmer. MIT `companyName` juristische Person, OHNE natürliche Person (amtliche Dokumentation zur Vollmacht: „Status als juristische Person wird nur dann zuerkannt, wenn ‚Name des Unternehmens' ausgefüllt ist"). Der Berufs-/Wirtschaftszweigschlüssel ist in beiden Fällen anzugeben — `888` gilt nur für Privatpersonen. - `ASSOCIATION` — eine nicht rechtsfähige Vereinigung, etwa eine GbR ohne Registereintrag oder eine Erbengemeinschaft. Geht als eigene Struktur (`NameVereinigung`) ans KBA, mit optionalem Vertreter. Ein eingetragener Verein ist dagegen eine juristische Person. Erweiterung gegenüber kennzeichen.dev.
NATURAL_PERSON · LEGAL_PERSON · AUTHORITY · SOLE_TRADER · ASSOCIATION
associationRepresentative object
Der benannte Vertreter einer Vereinigung — nur bei `partyType: ASSOCIATION` und dort freiwillig (seit XKfz 6.0 optional). In `POST /powerOfAttorneys` gibt es ihn nicht: Für eine Vereinigung lässt sich über uns keine Vollmacht unterschreiben (siehe `principal`).
firstName string
lastName string
companyName string
dateOfBirth string (date)
Streng als JJJJ-MM-TT. Nur bei natürlichen Personen. Zulässiger Bereich 1880–2099.
placeOfBirth string
Nur bei natürlichen Personen.
occupationKey string
Berufs- bzw. Wirtschaftszweigschlüssel, drei Stellen. Beim Halter einer Zulassung (UG, WG, WZ, NZ, TZ) Pflicht (KBA-Wissensartikel „Angabe des Berufsschlüssels bzw. Wirtschaftszweigs"). Firmen und juristische Personen nehmen den Schlüssel aus dem KBA-Verzeichnis SV 5, etwa `G01` für den Handel mit Kraftfahrzeugen; fehlt er, `400`. Privatpersonen ohne Angabe erhalten "888"; Freiberufler und Einzelunternehmer geben ihren Schlüssel an. Geprüft wird nur die Form. Bei der Halteränderung, beim Bevollmächtigten und beim Lieferungsempfänger optional.
powerOfAttorney PowerOfAttorney
representative HolderParty
address* HolderAddress
firstName string
lastName string
companyName string
gender enum
Nur bei natürlichen Personen zulässig.
FEMALE · MALE · DIVERSE · UNSPECIFIED
streetName string
houseNumber string
Laut XKfz-Schema NUR Ziffern, höchstens vier. Ein Zusatz wie "7a" ist dort nicht vorgesehen und gehört in addressSuffix.
zipCode string
cityName string
countryCode string
KBA-Staatsschlüssel. Ohne Angabe D.
addressSuffix string
partyType enum
Die Art des Beteiligten. **Freiwillig und zusätzlich** — ohne Angabe gilt wie bisher der Name: `companyName` heisst juristische Person, sonst natürliche Person. - `NATURAL_PERSON`, `LEGAL_PERSON` — die beiden bisherigen Arten, ausdrücklich benannt. - `AUTHORITY` — eine Behörde. Geht im XML als juristische Person hinaus; das Schema kennt keine eigene Art. - `SOLE_TRADER` — Einzelunternehmer. MIT `companyName` juristische Person, OHNE natürliche Person (amtliche Dokumentation zur Vollmacht: „Status als juristische Person wird nur dann zuerkannt, wenn ‚Name des Unternehmens' ausgefüllt ist"). Der Berufs-/Wirtschaftszweigschlüssel ist in beiden Fällen anzugeben — `888` gilt nur für Privatpersonen. - `ASSOCIATION` — eine nicht rechtsfähige Vereinigung, etwa eine GbR ohne Registereintrag oder eine Erbengemeinschaft. Geht als eigene Struktur (`NameVereinigung`) ans KBA, mit optionalem Vertreter. Ein eingetragener Verein ist dagegen eine juristische Person. Erweiterung gegenüber kennzeichen.dev.
NATURAL_PERSON · LEGAL_PERSON · AUTHORITY · SOLE_TRADER · ASSOCIATION
associationRepresentative object
Der benannte Vertreter einer Vereinigung — nur bei `partyType: ASSOCIATION` und dort freiwillig (seit XKfz 6.0 optional). In `POST /powerOfAttorneys` gibt es ihn nicht: Für eine Vereinigung lässt sich über uns keine Vollmacht unterschreiben (siehe `principal`).
firstName string
lastName string
companyName string
dateOfBirth string (date)
Streng als JJJJ-MM-TT. Nur bei natürlichen Personen. Zulässiger Bereich 1880–2099.
placeOfBirth string
Nur bei natürlichen Personen.
occupationKey string
Berufs- bzw. Wirtschaftszweigschlüssel, drei Stellen. Beim Halter einer Zulassung (UG, WG, WZ, NZ, TZ) Pflicht (KBA-Wissensartikel „Angabe des Berufsschlüssels bzw. Wirtschaftszweigs"). Firmen und juristische Personen nehmen den Schlüssel aus dem KBA-Verzeichnis SV 5, etwa `G01` für den Handel mit Kraftfahrzeugen; fehlt er, `400`. Privatpersonen ohne Angabe erhalten "888"; Freiberufler und Einzelunternehmer geben ihren Schlüssel an. Geprüft wird nur die Form. Bei der Halteränderung, beim Bevollmächtigten und beim Lieferungsempfänger optional.
documentBase64 string (byte)
Das unterschriebene Vollmacht-PDF, Base64-kodiert — selbst mitgebracht.
processId integer
Nummer eines Vollmachtsvorgangs, der über diesen Dienst unterschrieben wurde (siehe Self-Service-Bereich, „Vollmachtsvorgänge"). Wir hängen das signierte Dokument dann selbst an und gleichen die Vollmacht vorab gegen die Antragsdaten ab. Ist der Vorgang unbekannt oder gehört er einem anderen Mandanten: 404. Ist er noch nicht unterschrieben: 409, mit seinem Stand in der Meldung — und zwar vor jeder Feldprüfung: Feldfehler und der Abgleich mit der Vollmacht melden sich erst nach der Unterschrift. Ein 400 danach verbraucht den Vorgang nicht; der korrigierte Antrag darf dieselbe processId nennen.
deliveryRecipient object
Abweichender Empfänger der Zulassungsunterlagen.
address* HolderAddress
firstName string
lastName string
companyName string
gender enum
Nur bei natürlichen Personen zulässig.
FEMALE · MALE · DIVERSE · UNSPECIFIED
streetName string
houseNumber string
Laut XKfz-Schema NUR Ziffern, höchstens vier. Ein Zusatz wie "7a" ist dort nicht vorgesehen und gehört in addressSuffix.
zipCode string
cityName string
countryCode string
KBA-Staatsschlüssel. Ohne Angabe D.
addressSuffix string
partyType enum
Die Art des Beteiligten. **Freiwillig und zusätzlich** — ohne Angabe gilt wie bisher der Name: `companyName` heisst juristische Person, sonst natürliche Person. - `NATURAL_PERSON`, `LEGAL_PERSON` — die beiden bisherigen Arten, ausdrücklich benannt. - `AUTHORITY` — eine Behörde. Geht im XML als juristische Person hinaus; das Schema kennt keine eigene Art. - `SOLE_TRADER` — Einzelunternehmer. MIT `companyName` juristische Person, OHNE natürliche Person (amtliche Dokumentation zur Vollmacht: „Status als juristische Person wird nur dann zuerkannt, wenn ‚Name des Unternehmens' ausgefüllt ist"). Der Berufs-/Wirtschaftszweigschlüssel ist in beiden Fällen anzugeben — `888` gilt nur für Privatpersonen. - `ASSOCIATION` — eine nicht rechtsfähige Vereinigung, etwa eine GbR ohne Registereintrag oder eine Erbengemeinschaft. Geht als eigene Struktur (`NameVereinigung`) ans KBA, mit optionalem Vertreter. Ein eingetragener Verein ist dagegen eine juristische Person. Erweiterung gegenüber kennzeichen.dev.
NATURAL_PERSON · LEGAL_PERSON · AUTHORITY · SOLE_TRADER · ASSOCIATION
associationRepresentative object
Der benannte Vertreter einer Vereinigung — nur bei `partyType: ASSOCIATION` und dort freiwillig (seit XKfz 6.0 optional). In `POST /powerOfAttorneys` gibt es ihn nicht: Für eine Vereinigung lässt sich über uns keine Vollmacht unterschreiben (siehe `principal`).
firstName string
lastName string
companyName string
dateOfBirth string (date)
Streng als JJJJ-MM-TT. Nur bei natürlichen Personen. Zulässiger Bereich 1880–2099.
placeOfBirth string
Nur bei natürlichen Personen.
occupationKey string
Berufs- bzw. Wirtschaftszweigschlüssel, drei Stellen. Beim Halter einer Zulassung (UG, WG, WZ, NZ, TZ) Pflicht (KBA-Wissensartikel „Angabe des Berufsschlüssels bzw. Wirtschaftszweigs"). Firmen und juristische Personen nehmen den Schlüssel aus dem KBA-Verzeichnis SV 5, etwa `G01` für den Handel mit Kraftfahrzeugen; fehlt er, `400`. Privatpersonen ohne Angabe erhalten "888"; Freiberufler und Einzelunternehmer geben ihren Schlüssel an. Geprüft wird nur die Form. Bei der Halteränderung, beim Bevollmächtigten und beim Lieferungsempfänger optional.
sepaMandateBase64 string (byte)
SEPA-Mandat als PDF. Anders als bei der Vollmacht ist hier ein Scan zulässig. Entfällt, wenn sich der Antrag über `powerOfAttorney.processId` auf einen Vollmachtsvorgang mit `bankAccount` beruft: Dann hängen wir das dort signierte Mandat an — sofern `bankAccount` hier dieselbe IBAN und denselben Kontoinhaber nennt, sonst `400`. Mitgeschickt hat dieses Feld Vorrang.
bankAccount BankAccount
iban* string
accountHolder* string
usage enum
Steuer · Gebuehren
directDebitMandateGranted boolean
taxDetails TaxDetails
paymentInterval* enum
jaehrlich · halbjaehrlich · vierteljaehrlich
taxLargeCustomerId string
Großkunden-ID der Steuer. Liegt sie vor, entfällt das SEPA-Mandat. Zollform — drei Ziffern, ein Großbuchstabe, vier Ziffern —, seit XKfz 6.0 verbindlich; andere Formen weisen wir mit 400 ab.
taxExemptionRequested boolean
Befreiung von der Kfz-Steuer beantragen. Ohne diese Angabe lässt sich ein Fahrzeug mit Steuerbefreiung — etwa bei Schwerbehinderung — nicht anmelden.
taxExemptionReason string
Grund der Steuerbefreiung. Wird unverändert durchgereicht und nicht gegen eine Liste geprüft: Welche Gründe es gibt, sagen die vorliegenden KBA-Unterlagen nicht; im amtlichen Beispiel steht `18`.
inspections InspectionDetails[]
reportDate string (date)
nextInspection* string
Fälligkeit der nächsten Untersuchung als MMJJJJ.
inspectionType enum
Ohne Angabe wird HU gesendet (Codeliste artderuntersuchung, Klartext „Hauptuntersuchung“). Eine Sicherheitsprüfung muss ausdrücklich SP setzen.
HU · SP
institutionKey string
Schlüsselnummer der Überwachungsinstitution oder des ZDK. Wird ungeprüft durchgereicht und als schluesselnummerDerUeberwachungsinstitutionOderZDK gesendet.
inspectionDate string (date)
expressProcedure boolean
checkDigit string
deliveries DeliveryInstruction[]
deliveryService* enum
Zustellweg (Codeliste lieferdienst). AbholungBevollmaechtigter ist die Abholung durch den Bevollmächtigten — vom KBA am 14.05.2024 bestätigt, in keinem amtlichen Beispiel enthalten.
ZusendungHalter · ZusendungBevollmaechtigter · ZusendungDritter · Abholung · AbholungHalter · AbholungBevollmaechtigter
deliverTo enum
Wessen Anschrift gilt — hat Vorrang vor dem deliveryService. Ohne Angabe benennt der deliveryService den Empfänger (ZusendungHalter und AbholungHalter den Halter, ZusendungDritter den deliveryRecipient und so fort); benennt auch er niemanden (Abholung), gilt der deliveryRecipient, sonst der Bevollmächtigte, sonst der Halter. Verglichen wird gegen die Vollmacht, wer nach dieser Regel wirklich beliefert wird: ZusendungHalter mit deliverTo RECIPIENT gilt als Lieferung an den Dritten und ergibt gegen eine Vollmacht „an den Halter" 400.
HOLDER · REPRESENTATIVE · RECIPIENT
orderedAt string (date)
items* DeliveryItem[]
documentType* string
Codeliste artderunterlage — 2 ZB I, 3 ZB II, 27 HU-Plakette, 37 Siegelplakette, 39 HU-Plakettenträger, 42 Beiblatt zur ZB I, 40 Stempelplakettenträger (44 in älteren Beispielen, wird weiter angenommen).
quantity* integer
email* string (email)
externalOrderId string
Ihre eigene Auftragsreferenz. Wird in Webhook-Events zurückgegeben — und ist zugleich der Schutz gegen den doppelt gestellten Antrag: Derselbe Mandant, dieselbe `externalOrderId`, dieselbe FIN UND derselbe Geschäftsvorfall (Endpunkt) innerhalb von 15 Minuten gelten als Wiederholungsversuch. Es geht dann NICHTS erneut an das KBA, und die Antwort nennt den bestehenden Vorgang (HTTP 200, dieselbe `order.id`). So führt eine Zeitüberschreitung samt automatischer Wiederholung Ihres Clients nicht zu zwei Anträgen und zwei Gebühren. Ohne Referenz greift der Schutz nicht — dann fehlt die Aussage „das ist derselbe Auftrag". **Weichen die Daten ab, ist es kein Wiederholungsversuch:** Dieselbe Referenz und FIN mit geändertem Inhalt beantwortet der Dienst mit **409** und ändert nichts. Weder darf er die Korrektur still verwerfen noch ungefragt einen zweiten Antrag samt Gebühr auslösen. Für einen weiteren Antrag eine eigene Referenz vergeben; für eine Berichtigung den bestehenden Vorgang korrigieren. **Dieselbe Referenz an einem anderen Endpunkt** — etwa NZ statt TZ oder WG statt WZ — ist kein Wiederholungsversuch, sondern ein neuer Antrag samt Gebühr. Ein falsch gewählter Endpunkt lässt sich nicht durch erneutes Senden unter derselben Referenz berichtigen.
correctionOf integer (int64)
Vorgangsnummer eines abgewiesenen oder fehlgeschlagenen Auftrags, der mit diesem Rumpf korrigiert werden soll. Es entsteht ein neuer KBA-Versuch am selben Auftrag; die Antwort nennt `attemptOf` und `attempt`. Laufende oder beschiedene Aufträge sowie ein anderer Geschäftsvorfall ergeben 409.
gksConfigurationId string (uuid)
{
  "externalOrderId": "saisonstart-4711",
  "email": "kunde@example.de",
  "customization": {
    "vehicleIdentificationNumber": "WVWZZZ7HZ8H333333",
    "licensePlateNumberComponents": {
      "usageType": "EURO",
      "city": "SL",
      "middle": "OA",
      "end": "1418"
    },
    "vehicleRegistrationCertificatePartII": {
      "number": "ZZ112980",
      "securityCode": "BgDwroY6tly4"
    },
    "insuranceConfirmationNumber": "R245654"
  },
  "vehicleHolder": {
    "address": {
      "companyName": "Chaos-Klempnerei Wassermarsch OHG",
      "streetName": "Am Bahnhof",
      "houseNumber": "15",
      "zipCode": "24983",
      "cityName": "Handewitt",
      "countryCode": "D"
    },
    "occupationKey": "F00"
  },
  "taxDetails": {
    "paymentInterval": "jaehrlich",
    "taxLargeCustomerId": "123A4567"
  }
}

Antworten

200 Der Antrag wurde angenommen.
order* object
id* integer (int64)
attemptOf integer (int64)
Nur bei einer Korrektur — die Auftragsnummer der Versuchskette.
attempt integer
Nur bei einer Korrektur — die laufende Nummer des neuen Versuchs.
{
  "order": {
    "id": 1
  }
}
400
401
403
404
409
413
415
500
503
default
POST/vehicleRegistrations/registrationsNeuzulassung beauftragen

Neuzulassung eines fabrikneuen Fahrzeugs. Pflicht über die gemeinsamen Angaben hinaus (siehe `VehicleRegistrationRequest`): der Sicherheitscode der **ZB II** (`customization.vehicleRegistrationCertificatePartII.securityCode`) und die Kennzeichenzuteilung (`customization.licensePlateAssignment` — entweder eine Reservierung samt PIN oder die Kennzeichenart für das nächste freie Kennzeichen). Weder ein bisheriges Kennzeichen noch eine ZB I sind vorhanden; `licensePlateNumberComponents` neben einer Zuteilung wird abgewiesen. Nur typgenehmigte Fahrzeuge mit abrufbaren CoC-Daten sind über die GKS zulassbar. Ereignistyp: `VEHICLE_REGISTRATION_XKFZ_EVENT`.

Request application/json

requestRegistrationData boolean
Fordert die strukturierten Zulassungsdaten an (ZB I und ZB II, ueber sechzig Angaben). Ohne sie kommt nur der Bescheid als PDF zurueck. Die Daten erscheinen als `registrationData` in der Vorgangsauskunft und im Webhook-Ereignis. Bei einem Antrag mit Vollmacht muss sie das Kreuz „erweiterte Datenbereitstellung" tragen (`extendedDataProvision` im Vollmachtsvorgang), sonst antwortet der Antrag mit 400 — geprüft, sofern sich die Vollmacht als Formular lesen lässt.
orderEmissionSticker boolean
Feinstaubplakette mitbestellen; erweitert die Lieferung um eine Position (Festlegungen zum elektronischen Antrag, Blatt „GK NZ").
customization* VehicleRegistrationCustomization
vehicleIdentificationNumber* string
licensePlateNumberComponents object
Bisheriges Kennzeichen — bei Umschreibung Pflicht.
usageType enum
Kennzeichenmerkmal — für alle Anträge mit bisherigem Kennzeichen (AB, HA, UG, WG, WZ): EURO (Normalfall), ELECTRIC (Elektrokennzeichen) und HISTORIC (Oldtimerkennzeichen); andere Werte werden mit HTTP 400 abgewiesen.
EURO · ELECTRIC · HISTORIC
city* string
Unterscheidungszeichen, 1–3 Buchstaben (Umlaute zulässig). Kleinbuchstaben werden großgeschrieben; das Muster lässt sie deshalb zu.
middle* string
Erkennungsbuchstaben, 1–2 Buchstaben ohne Umlaute. Kleinbuchstaben werden großgeschrieben.
end* string
Erkennungsnummer, 1–4 Ziffern.
licensePlateSeals LicensePlateSeal[]
Codes der Stempelplaketten des bisherigen Kennzeichens — nur zusammen mit licensePlateNumberComponents wirksam. Ohne bisheriges Kennzeichen (immer bei NZ und TZ) werden die Einträge geprüft, aber nicht übermittelt.
position* enum
vorn · hinten · beide
securityCode string
Dreistelliger Code unter der Stempelplakette.
licensePlateAssignment object
Neues Kennzeichen zuteilen. Ein Wunschkennzeichen lässt sich über die GKS NICHT reservieren — entweder eine vorab bei der Zulassungsbehörde erwirkte Reservierung samt PIN, oder das nächste freie Kennzeichen.
reservation object
licensePlate* string
pin* string
plateType enum
Kennzeichenart nach dem amtlichen Schema (typ-MerkmalKennzeichenart-ZFZR). Z ist der Regelfall, B das Behördenkennzeichen. Pflicht, sobald das nächste freie Kennzeichen angefordert wird (keine `reservation`); fehlt sie, antworten wir mit 400. Saisonkennzeichen (ZS, BS) sind vorerst nicht beantragbar und werden mit 400 abgewiesen: Der Betriebszeitraum lässt sich im Antrag nicht angeben, und die Frage dazu ist beim KBA offen. Die übrigen Arten des Schemas — Ausfuhrkennzeichen (A), rotes Kennzeichen (R), Kurzzeitkennzeichen (RK) und Versicherungskennzeichen (V, VR) — lassen sich über die GKS nicht beantragen. Bescheide des KBA können dennoch jede Art melden.
B · Z
electric boolean
historic boolean
vehicleRegistrationCertificateSecurityCode string
vehicleRegistrationCertificateNumber string
Nummer der ZB I, 18–20 Zeichen, Buchstabe am Anfang. Kleinbuchstaben werden großgeschrieben.
vehicleRegistrationCertificateImprintNumber string
Druckstücknummer der ZB I. Acht Zeichen: Großbuchstabe, sechs Ziffern oder Großbuchstaben, zuletzt Ziffer oder X (Schema XKfz 6.0, Type.Druckstuecknummer).
vehicleRegistrationCertificatePartII object
number string
Nummer der ZB II. Kleinbuchstaben werden großgeschrieben. OHNEZBII und ohne-ZF- sind die amtlichen Platzhalter für Fahrzeuge ohne Teil II.
securityCode string
Zwölfstellig, Modulo-11-geprüft. Wird bereits hier vorgeprüft, verbindlich prüft das KBA.
insuranceConfirmationNumber* string
eVB-Nummer. Ohne sie ist keine Zulassung möglich.
vehicleUsage enum
Fahrzeugverwendung nach dem amtlichen Schema (typ-VerwendungFahrzeug). Muss zur eVB passen.
B · C · D · E · F · G · K · L · M · S · T · X
customerNumber string
contractPartner ContractPartner
vehicleHolder object
Der künftige Halter. Pflicht — AUSSER der Antrag beruft sich über `powerOfAttorney.processId` auf einen Vollmachtsvorgang, zu dem der Vertrauensdienst die Person bereits festgestellt hat. Dann setzen wir den Halter aus dessen Daten ein, und mitgeschickte Angaben werden überschrieben. Grund ist das BMDV-Schreiben vom 25.04.2024 (Az. 7362.8/1): Die Halterdaten stammen ausschliesslich vom Vertrauensdiensteanbieter, nicht aus der Kundeneingabe. § 38 Abs. 4 FZV sagt dasselbe — die Halterangaben sind der das Vollmachtsformular verarbeitenden Nachricht zu entnehmen. Bei Zulassungen (UG, WG, WZ, NZ, TZ) ersetzen wir mitgeschickte Halterangaben deshalb durch die des Vertrauensdienstes — es gibt dafür kein 400; Vorgangsauskunft und Dashboard zeigen den gesendeten Halter. Ergänzt wird nur, was kein Vertrauensdienst feststellt (`occupationKey`, `address.gender`; bei einer Firma nur `occupationKey`). Ohne `occupationKey` gilt der in der Vollmacht unterschriebene Wirtschaftszweig; `vehicleHolder: { occupationKey }` allein genügt. 400 kommt nur, wenn die Daten des Vertrauensdienstes nicht zur unterschriebenen Vollmacht passen, der mitgeschickte `occupationKey` vom in der Vollmacht unterschriebenen Wirtschaftszweig abweicht oder eine Firma an beiden Stellen keinen `occupationKey` führt. Anders die Halteränderung: Dort ist die neue Anschrift der Antrag selbst und muss der festgestellten entsprechen, sonst 400 (siehe `VehicleHolderChangeRequest`).
address* HolderAddress
firstName string
lastName string
companyName string
gender enum
Nur bei natürlichen Personen zulässig.
FEMALE · MALE · DIVERSE · UNSPECIFIED
streetName string
houseNumber string
Laut XKfz-Schema NUR Ziffern, höchstens vier. Ein Zusatz wie "7a" ist dort nicht vorgesehen und gehört in addressSuffix.
zipCode string
cityName string
countryCode string
KBA-Staatsschlüssel. Ohne Angabe D.
addressSuffix string
partyType enum
Die Art des Beteiligten. **Freiwillig und zusätzlich** — ohne Angabe gilt wie bisher der Name: `companyName` heisst juristische Person, sonst natürliche Person. - `NATURAL_PERSON`, `LEGAL_PERSON` — die beiden bisherigen Arten, ausdrücklich benannt. - `AUTHORITY` — eine Behörde. Geht im XML als juristische Person hinaus; das Schema kennt keine eigene Art. - `SOLE_TRADER` — Einzelunternehmer. MIT `companyName` juristische Person, OHNE natürliche Person (amtliche Dokumentation zur Vollmacht: „Status als juristische Person wird nur dann zuerkannt, wenn ‚Name des Unternehmens' ausgefüllt ist"). Der Berufs-/Wirtschaftszweigschlüssel ist in beiden Fällen anzugeben — `888` gilt nur für Privatpersonen. - `ASSOCIATION` — eine nicht rechtsfähige Vereinigung, etwa eine GbR ohne Registereintrag oder eine Erbengemeinschaft. Geht als eigene Struktur (`NameVereinigung`) ans KBA, mit optionalem Vertreter. Ein eingetragener Verein ist dagegen eine juristische Person. Erweiterung gegenüber kennzeichen.dev.
NATURAL_PERSON · LEGAL_PERSON · AUTHORITY · SOLE_TRADER · ASSOCIATION
associationRepresentative object
Der benannte Vertreter einer Vereinigung — nur bei `partyType: ASSOCIATION` und dort freiwillig (seit XKfz 6.0 optional). In `POST /powerOfAttorneys` gibt es ihn nicht: Für eine Vereinigung lässt sich über uns keine Vollmacht unterschreiben (siehe `principal`).
firstName string
lastName string
companyName string
dateOfBirth string (date)
Streng als JJJJ-MM-TT. Nur bei natürlichen Personen. Zulässiger Bereich 1880–2099.
placeOfBirth string
Nur bei natürlichen Personen.
occupationKey string
Berufs- bzw. Wirtschaftszweigschlüssel, drei Stellen. Beim Halter einer Zulassung (UG, WG, WZ, NZ, TZ) Pflicht (KBA-Wissensartikel „Angabe des Berufsschlüssels bzw. Wirtschaftszweigs"). Firmen und juristische Personen nehmen den Schlüssel aus dem KBA-Verzeichnis SV 5, etwa `G01` für den Handel mit Kraftfahrzeugen; fehlt er, `400`. Privatpersonen ohne Angabe erhalten "888"; Freiberufler und Einzelunternehmer geben ihren Schlüssel an. Geprüft wird nur die Form. Bei der Halteränderung, beim Bevollmächtigten und beim Lieferungsempfänger optional.
powerOfAttorney PowerOfAttorney
representative HolderParty
address* HolderAddress
firstName string
lastName string
companyName string
gender enum
Nur bei natürlichen Personen zulässig.
FEMALE · MALE · DIVERSE · UNSPECIFIED
streetName string
houseNumber string
Laut XKfz-Schema NUR Ziffern, höchstens vier. Ein Zusatz wie "7a" ist dort nicht vorgesehen und gehört in addressSuffix.
zipCode string
cityName string
countryCode string
KBA-Staatsschlüssel. Ohne Angabe D.
addressSuffix string
partyType enum
Die Art des Beteiligten. **Freiwillig und zusätzlich** — ohne Angabe gilt wie bisher der Name: `companyName` heisst juristische Person, sonst natürliche Person. - `NATURAL_PERSON`, `LEGAL_PERSON` — die beiden bisherigen Arten, ausdrücklich benannt. - `AUTHORITY` — eine Behörde. Geht im XML als juristische Person hinaus; das Schema kennt keine eigene Art. - `SOLE_TRADER` — Einzelunternehmer. MIT `companyName` juristische Person, OHNE natürliche Person (amtliche Dokumentation zur Vollmacht: „Status als juristische Person wird nur dann zuerkannt, wenn ‚Name des Unternehmens' ausgefüllt ist"). Der Berufs-/Wirtschaftszweigschlüssel ist in beiden Fällen anzugeben — `888` gilt nur für Privatpersonen. - `ASSOCIATION` — eine nicht rechtsfähige Vereinigung, etwa eine GbR ohne Registereintrag oder eine Erbengemeinschaft. Geht als eigene Struktur (`NameVereinigung`) ans KBA, mit optionalem Vertreter. Ein eingetragener Verein ist dagegen eine juristische Person. Erweiterung gegenüber kennzeichen.dev.
NATURAL_PERSON · LEGAL_PERSON · AUTHORITY · SOLE_TRADER · ASSOCIATION
associationRepresentative object
Der benannte Vertreter einer Vereinigung — nur bei `partyType: ASSOCIATION` und dort freiwillig (seit XKfz 6.0 optional). In `POST /powerOfAttorneys` gibt es ihn nicht: Für eine Vereinigung lässt sich über uns keine Vollmacht unterschreiben (siehe `principal`).
firstName string
lastName string
companyName string
dateOfBirth string (date)
Streng als JJJJ-MM-TT. Nur bei natürlichen Personen. Zulässiger Bereich 1880–2099.
placeOfBirth string
Nur bei natürlichen Personen.
occupationKey string
Berufs- bzw. Wirtschaftszweigschlüssel, drei Stellen. Beim Halter einer Zulassung (UG, WG, WZ, NZ, TZ) Pflicht (KBA-Wissensartikel „Angabe des Berufsschlüssels bzw. Wirtschaftszweigs"). Firmen und juristische Personen nehmen den Schlüssel aus dem KBA-Verzeichnis SV 5, etwa `G01` für den Handel mit Kraftfahrzeugen; fehlt er, `400`. Privatpersonen ohne Angabe erhalten "888"; Freiberufler und Einzelunternehmer geben ihren Schlüssel an. Geprüft wird nur die Form. Bei der Halteränderung, beim Bevollmächtigten und beim Lieferungsempfänger optional.
documentBase64 string (byte)
Das unterschriebene Vollmacht-PDF, Base64-kodiert — selbst mitgebracht.
processId integer
Nummer eines Vollmachtsvorgangs, der über diesen Dienst unterschrieben wurde (siehe Self-Service-Bereich, „Vollmachtsvorgänge"). Wir hängen das signierte Dokument dann selbst an und gleichen die Vollmacht vorab gegen die Antragsdaten ab. Ist der Vorgang unbekannt oder gehört er einem anderen Mandanten: 404. Ist er noch nicht unterschrieben: 409, mit seinem Stand in der Meldung — und zwar vor jeder Feldprüfung: Feldfehler und der Abgleich mit der Vollmacht melden sich erst nach der Unterschrift. Ein 400 danach verbraucht den Vorgang nicht; der korrigierte Antrag darf dieselbe processId nennen.
deliveryRecipient object
Abweichender Empfänger der Zulassungsunterlagen.
address* HolderAddress
firstName string
lastName string
companyName string
gender enum
Nur bei natürlichen Personen zulässig.
FEMALE · MALE · DIVERSE · UNSPECIFIED
streetName string
houseNumber string
Laut XKfz-Schema NUR Ziffern, höchstens vier. Ein Zusatz wie "7a" ist dort nicht vorgesehen und gehört in addressSuffix.
zipCode string
cityName string
countryCode string
KBA-Staatsschlüssel. Ohne Angabe D.
addressSuffix string
partyType enum
Die Art des Beteiligten. **Freiwillig und zusätzlich** — ohne Angabe gilt wie bisher der Name: `companyName` heisst juristische Person, sonst natürliche Person. - `NATURAL_PERSON`, `LEGAL_PERSON` — die beiden bisherigen Arten, ausdrücklich benannt. - `AUTHORITY` — eine Behörde. Geht im XML als juristische Person hinaus; das Schema kennt keine eigene Art. - `SOLE_TRADER` — Einzelunternehmer. MIT `companyName` juristische Person, OHNE natürliche Person (amtliche Dokumentation zur Vollmacht: „Status als juristische Person wird nur dann zuerkannt, wenn ‚Name des Unternehmens' ausgefüllt ist"). Der Berufs-/Wirtschaftszweigschlüssel ist in beiden Fällen anzugeben — `888` gilt nur für Privatpersonen. - `ASSOCIATION` — eine nicht rechtsfähige Vereinigung, etwa eine GbR ohne Registereintrag oder eine Erbengemeinschaft. Geht als eigene Struktur (`NameVereinigung`) ans KBA, mit optionalem Vertreter. Ein eingetragener Verein ist dagegen eine juristische Person. Erweiterung gegenüber kennzeichen.dev.
NATURAL_PERSON · LEGAL_PERSON · AUTHORITY · SOLE_TRADER · ASSOCIATION
associationRepresentative object
Der benannte Vertreter einer Vereinigung — nur bei `partyType: ASSOCIATION` und dort freiwillig (seit XKfz 6.0 optional). In `POST /powerOfAttorneys` gibt es ihn nicht: Für eine Vereinigung lässt sich über uns keine Vollmacht unterschreiben (siehe `principal`).
firstName string
lastName string
companyName string
dateOfBirth string (date)
Streng als JJJJ-MM-TT. Nur bei natürlichen Personen. Zulässiger Bereich 1880–2099.
placeOfBirth string
Nur bei natürlichen Personen.
occupationKey string
Berufs- bzw. Wirtschaftszweigschlüssel, drei Stellen. Beim Halter einer Zulassung (UG, WG, WZ, NZ, TZ) Pflicht (KBA-Wissensartikel „Angabe des Berufsschlüssels bzw. Wirtschaftszweigs"). Firmen und juristische Personen nehmen den Schlüssel aus dem KBA-Verzeichnis SV 5, etwa `G01` für den Handel mit Kraftfahrzeugen; fehlt er, `400`. Privatpersonen ohne Angabe erhalten "888"; Freiberufler und Einzelunternehmer geben ihren Schlüssel an. Geprüft wird nur die Form. Bei der Halteränderung, beim Bevollmächtigten und beim Lieferungsempfänger optional.
sepaMandateBase64 string (byte)
SEPA-Mandat als PDF. Anders als bei der Vollmacht ist hier ein Scan zulässig. Entfällt, wenn sich der Antrag über `powerOfAttorney.processId` auf einen Vollmachtsvorgang mit `bankAccount` beruft: Dann hängen wir das dort signierte Mandat an — sofern `bankAccount` hier dieselbe IBAN und denselben Kontoinhaber nennt, sonst `400`. Mitgeschickt hat dieses Feld Vorrang.
bankAccount BankAccount
iban* string
accountHolder* string
usage enum
Steuer · Gebuehren
directDebitMandateGranted boolean
taxDetails TaxDetails
paymentInterval* enum
jaehrlich · halbjaehrlich · vierteljaehrlich
taxLargeCustomerId string
Großkunden-ID der Steuer. Liegt sie vor, entfällt das SEPA-Mandat. Zollform — drei Ziffern, ein Großbuchstabe, vier Ziffern —, seit XKfz 6.0 verbindlich; andere Formen weisen wir mit 400 ab.
taxExemptionRequested boolean
Befreiung von der Kfz-Steuer beantragen. Ohne diese Angabe lässt sich ein Fahrzeug mit Steuerbefreiung — etwa bei Schwerbehinderung — nicht anmelden.
taxExemptionReason string
Grund der Steuerbefreiung. Wird unverändert durchgereicht und nicht gegen eine Liste geprüft: Welche Gründe es gibt, sagen die vorliegenden KBA-Unterlagen nicht; im amtlichen Beispiel steht `18`.
inspections InspectionDetails[]
reportDate string (date)
nextInspection* string
Fälligkeit der nächsten Untersuchung als MMJJJJ.
inspectionType enum
Ohne Angabe wird HU gesendet (Codeliste artderuntersuchung, Klartext „Hauptuntersuchung“). Eine Sicherheitsprüfung muss ausdrücklich SP setzen.
HU · SP
institutionKey string
Schlüsselnummer der Überwachungsinstitution oder des ZDK. Wird ungeprüft durchgereicht und als schluesselnummerDerUeberwachungsinstitutionOderZDK gesendet.
inspectionDate string (date)
expressProcedure boolean
checkDigit string
deliveries DeliveryInstruction[]
deliveryService* enum
Zustellweg (Codeliste lieferdienst). AbholungBevollmaechtigter ist die Abholung durch den Bevollmächtigten — vom KBA am 14.05.2024 bestätigt, in keinem amtlichen Beispiel enthalten.
ZusendungHalter · ZusendungBevollmaechtigter · ZusendungDritter · Abholung · AbholungHalter · AbholungBevollmaechtigter
deliverTo enum
Wessen Anschrift gilt — hat Vorrang vor dem deliveryService. Ohne Angabe benennt der deliveryService den Empfänger (ZusendungHalter und AbholungHalter den Halter, ZusendungDritter den deliveryRecipient und so fort); benennt auch er niemanden (Abholung), gilt der deliveryRecipient, sonst der Bevollmächtigte, sonst der Halter. Verglichen wird gegen die Vollmacht, wer nach dieser Regel wirklich beliefert wird: ZusendungHalter mit deliverTo RECIPIENT gilt als Lieferung an den Dritten und ergibt gegen eine Vollmacht „an den Halter" 400.
HOLDER · REPRESENTATIVE · RECIPIENT
orderedAt string (date)
items* DeliveryItem[]
documentType* string
Codeliste artderunterlage — 2 ZB I, 3 ZB II, 27 HU-Plakette, 37 Siegelplakette, 39 HU-Plakettenträger, 42 Beiblatt zur ZB I, 40 Stempelplakettenträger (44 in älteren Beispielen, wird weiter angenommen).
quantity* integer
email* string (email)
externalOrderId string
Ihre eigene Auftragsreferenz. Wird in Webhook-Events zurückgegeben — und ist zugleich der Schutz gegen den doppelt gestellten Antrag: Derselbe Mandant, dieselbe `externalOrderId`, dieselbe FIN UND derselbe Geschäftsvorfall (Endpunkt) innerhalb von 15 Minuten gelten als Wiederholungsversuch. Es geht dann NICHTS erneut an das KBA, und die Antwort nennt den bestehenden Vorgang (HTTP 200, dieselbe `order.id`). So führt eine Zeitüberschreitung samt automatischer Wiederholung Ihres Clients nicht zu zwei Anträgen und zwei Gebühren. Ohne Referenz greift der Schutz nicht — dann fehlt die Aussage „das ist derselbe Auftrag". **Weichen die Daten ab, ist es kein Wiederholungsversuch:** Dieselbe Referenz und FIN mit geändertem Inhalt beantwortet der Dienst mit **409** und ändert nichts. Weder darf er die Korrektur still verwerfen noch ungefragt einen zweiten Antrag samt Gebühr auslösen. Für einen weiteren Antrag eine eigene Referenz vergeben; für eine Berichtigung den bestehenden Vorgang korrigieren. **Dieselbe Referenz an einem anderen Endpunkt** — etwa NZ statt TZ oder WG statt WZ — ist kein Wiederholungsversuch, sondern ein neuer Antrag samt Gebühr. Ein falsch gewählter Endpunkt lässt sich nicht durch erneutes Senden unter derselben Referenz berichtigen.
correctionOf integer (int64)
Vorgangsnummer eines abgewiesenen oder fehlgeschlagenen Auftrags, der mit diesem Rumpf korrigiert werden soll. Es entsteht ein neuer KBA-Versuch am selben Auftrag; die Antwort nennt `attemptOf` und `attempt`. Laufende oder beschiedene Aufträge sowie ein anderer Geschäftsvorfall ergeben 409.
gksConfigurationId string (uuid)
{
  "externalOrderId": "neuzulassung-4711",
  "email": "kunde@example.de",
  "customization": {
    "vehicleIdentificationNumber": "WVWZZZ7HZ8H654321",
    "licensePlateAssignment": {
      "plateType": "Z"
    },
    "vehicleRegistrationCertificatePartII": {
      "number": "ZZ112977",
      "securityCode": "BgDwroY6tly4"
    },
    "insuranceConfirmationNumber": "R245654"
  },
  "vehicleHolder": {
    "address": {
      "companyName": "Chaos-Klempnerei Wassermarsch OHG",
      "streetName": "Am Bahnhof",
      "houseNumber": "15",
      "zipCode": "24983",
      "cityName": "Handewitt",
      "countryCode": "D"
    },
    "occupationKey": "F00"
  },
  "taxDetails": {
    "paymentInterval": "jaehrlich",
    "taxLargeCustomerId": "123A4567"
  }
}

Antworten

200 Der Antrag wurde angenommen.
order* object
id* integer (int64)
attemptOf integer (int64)
Nur bei einer Korrektur — die Auftragsnummer der Versuchskette.
attempt integer
Nur bei einer Korrektur — die laufende Nummer des neuen Versuchs.
{
  "order": {
    "id": 1
  }
}
400
401
403
404
409
413
415
500
503
default
POST/vehicleRegistrations/dayRegistrationsTageszulassung beauftragen

Tageszulassung — technisch wie die Neuzulassung, mit eigenem Geschäftsvorfallschlüssel. Pflicht über die gemeinsamen Angaben hinaus (siehe `VehicleRegistrationRequest`): wie bei der Neuzulassung der Sicherheitscode der **ZB II** (`customization.vehicleRegistrationCertificatePartII.securityCode`) und die Kennzeichenzuteilung (`customization.licensePlateAssignment` — entweder eine Reservierung samt PIN oder die Kennzeichenart für das nächste freie Kennzeichen). Ereignistyp: `VEHICLE_REGISTRATION_XKFZ_EVENT`.

Request application/json

requestRegistrationData boolean
Fordert die strukturierten Zulassungsdaten an (ZB I und ZB II, ueber sechzig Angaben). Ohne sie kommt nur der Bescheid als PDF zurueck. Die Daten erscheinen als `registrationData` in der Vorgangsauskunft und im Webhook-Ereignis. Bei einem Antrag mit Vollmacht muss sie das Kreuz „erweiterte Datenbereitstellung" tragen (`extendedDataProvision` im Vollmachtsvorgang), sonst antwortet der Antrag mit 400 — geprüft, sofern sich die Vollmacht als Formular lesen lässt.
orderEmissionSticker boolean
Feinstaubplakette mitbestellen; erweitert die Lieferung um eine Position (Festlegungen zum elektronischen Antrag, Blatt „GK NZ").
customization* VehicleRegistrationCustomization
vehicleIdentificationNumber* string
licensePlateNumberComponents object
Bisheriges Kennzeichen — bei Umschreibung Pflicht.
usageType enum
Kennzeichenmerkmal — für alle Anträge mit bisherigem Kennzeichen (AB, HA, UG, WG, WZ): EURO (Normalfall), ELECTRIC (Elektrokennzeichen) und HISTORIC (Oldtimerkennzeichen); andere Werte werden mit HTTP 400 abgewiesen.
EURO · ELECTRIC · HISTORIC
city* string
Unterscheidungszeichen, 1–3 Buchstaben (Umlaute zulässig). Kleinbuchstaben werden großgeschrieben; das Muster lässt sie deshalb zu.
middle* string
Erkennungsbuchstaben, 1–2 Buchstaben ohne Umlaute. Kleinbuchstaben werden großgeschrieben.
end* string
Erkennungsnummer, 1–4 Ziffern.
licensePlateSeals LicensePlateSeal[]
Codes der Stempelplaketten des bisherigen Kennzeichens — nur zusammen mit licensePlateNumberComponents wirksam. Ohne bisheriges Kennzeichen (immer bei NZ und TZ) werden die Einträge geprüft, aber nicht übermittelt.
position* enum
vorn · hinten · beide
securityCode string
Dreistelliger Code unter der Stempelplakette.
licensePlateAssignment object
Neues Kennzeichen zuteilen. Ein Wunschkennzeichen lässt sich über die GKS NICHT reservieren — entweder eine vorab bei der Zulassungsbehörde erwirkte Reservierung samt PIN, oder das nächste freie Kennzeichen.
reservation object
licensePlate* string
pin* string
plateType enum
Kennzeichenart nach dem amtlichen Schema (typ-MerkmalKennzeichenart-ZFZR). Z ist der Regelfall, B das Behördenkennzeichen. Pflicht, sobald das nächste freie Kennzeichen angefordert wird (keine `reservation`); fehlt sie, antworten wir mit 400. Saisonkennzeichen (ZS, BS) sind vorerst nicht beantragbar und werden mit 400 abgewiesen: Der Betriebszeitraum lässt sich im Antrag nicht angeben, und die Frage dazu ist beim KBA offen. Die übrigen Arten des Schemas — Ausfuhrkennzeichen (A), rotes Kennzeichen (R), Kurzzeitkennzeichen (RK) und Versicherungskennzeichen (V, VR) — lassen sich über die GKS nicht beantragen. Bescheide des KBA können dennoch jede Art melden.
B · Z
electric boolean
historic boolean
vehicleRegistrationCertificateSecurityCode string
vehicleRegistrationCertificateNumber string
Nummer der ZB I, 18–20 Zeichen, Buchstabe am Anfang. Kleinbuchstaben werden großgeschrieben.
vehicleRegistrationCertificateImprintNumber string
Druckstücknummer der ZB I. Acht Zeichen: Großbuchstabe, sechs Ziffern oder Großbuchstaben, zuletzt Ziffer oder X (Schema XKfz 6.0, Type.Druckstuecknummer).
vehicleRegistrationCertificatePartII object
number string
Nummer der ZB II. Kleinbuchstaben werden großgeschrieben. OHNEZBII und ohne-ZF- sind die amtlichen Platzhalter für Fahrzeuge ohne Teil II.
securityCode string
Zwölfstellig, Modulo-11-geprüft. Wird bereits hier vorgeprüft, verbindlich prüft das KBA.
insuranceConfirmationNumber* string
eVB-Nummer. Ohne sie ist keine Zulassung möglich.
vehicleUsage enum
Fahrzeugverwendung nach dem amtlichen Schema (typ-VerwendungFahrzeug). Muss zur eVB passen.
B · C · D · E · F · G · K · L · M · S · T · X
customerNumber string
contractPartner ContractPartner
vehicleHolder object
Der künftige Halter. Pflicht — AUSSER der Antrag beruft sich über `powerOfAttorney.processId` auf einen Vollmachtsvorgang, zu dem der Vertrauensdienst die Person bereits festgestellt hat. Dann setzen wir den Halter aus dessen Daten ein, und mitgeschickte Angaben werden überschrieben. Grund ist das BMDV-Schreiben vom 25.04.2024 (Az. 7362.8/1): Die Halterdaten stammen ausschliesslich vom Vertrauensdiensteanbieter, nicht aus der Kundeneingabe. § 38 Abs. 4 FZV sagt dasselbe — die Halterangaben sind der das Vollmachtsformular verarbeitenden Nachricht zu entnehmen. Bei Zulassungen (UG, WG, WZ, NZ, TZ) ersetzen wir mitgeschickte Halterangaben deshalb durch die des Vertrauensdienstes — es gibt dafür kein 400; Vorgangsauskunft und Dashboard zeigen den gesendeten Halter. Ergänzt wird nur, was kein Vertrauensdienst feststellt (`occupationKey`, `address.gender`; bei einer Firma nur `occupationKey`). Ohne `occupationKey` gilt der in der Vollmacht unterschriebene Wirtschaftszweig; `vehicleHolder: { occupationKey }` allein genügt. 400 kommt nur, wenn die Daten des Vertrauensdienstes nicht zur unterschriebenen Vollmacht passen, der mitgeschickte `occupationKey` vom in der Vollmacht unterschriebenen Wirtschaftszweig abweicht oder eine Firma an beiden Stellen keinen `occupationKey` führt. Anders die Halteränderung: Dort ist die neue Anschrift der Antrag selbst und muss der festgestellten entsprechen, sonst 400 (siehe `VehicleHolderChangeRequest`).
address* HolderAddress
firstName string
lastName string
companyName string
gender enum
Nur bei natürlichen Personen zulässig.
FEMALE · MALE · DIVERSE · UNSPECIFIED
streetName string
houseNumber string
Laut XKfz-Schema NUR Ziffern, höchstens vier. Ein Zusatz wie "7a" ist dort nicht vorgesehen und gehört in addressSuffix.
zipCode string
cityName string
countryCode string
KBA-Staatsschlüssel. Ohne Angabe D.
addressSuffix string
partyType enum
Die Art des Beteiligten. **Freiwillig und zusätzlich** — ohne Angabe gilt wie bisher der Name: `companyName` heisst juristische Person, sonst natürliche Person. - `NATURAL_PERSON`, `LEGAL_PERSON` — die beiden bisherigen Arten, ausdrücklich benannt. - `AUTHORITY` — eine Behörde. Geht im XML als juristische Person hinaus; das Schema kennt keine eigene Art. - `SOLE_TRADER` — Einzelunternehmer. MIT `companyName` juristische Person, OHNE natürliche Person (amtliche Dokumentation zur Vollmacht: „Status als juristische Person wird nur dann zuerkannt, wenn ‚Name des Unternehmens' ausgefüllt ist"). Der Berufs-/Wirtschaftszweigschlüssel ist in beiden Fällen anzugeben — `888` gilt nur für Privatpersonen. - `ASSOCIATION` — eine nicht rechtsfähige Vereinigung, etwa eine GbR ohne Registereintrag oder eine Erbengemeinschaft. Geht als eigene Struktur (`NameVereinigung`) ans KBA, mit optionalem Vertreter. Ein eingetragener Verein ist dagegen eine juristische Person. Erweiterung gegenüber kennzeichen.dev.
NATURAL_PERSON · LEGAL_PERSON · AUTHORITY · SOLE_TRADER · ASSOCIATION
associationRepresentative object
Der benannte Vertreter einer Vereinigung — nur bei `partyType: ASSOCIATION` und dort freiwillig (seit XKfz 6.0 optional). In `POST /powerOfAttorneys` gibt es ihn nicht: Für eine Vereinigung lässt sich über uns keine Vollmacht unterschreiben (siehe `principal`).
firstName string
lastName string
companyName string
dateOfBirth string (date)
Streng als JJJJ-MM-TT. Nur bei natürlichen Personen. Zulässiger Bereich 1880–2099.
placeOfBirth string
Nur bei natürlichen Personen.
occupationKey string
Berufs- bzw. Wirtschaftszweigschlüssel, drei Stellen. Beim Halter einer Zulassung (UG, WG, WZ, NZ, TZ) Pflicht (KBA-Wissensartikel „Angabe des Berufsschlüssels bzw. Wirtschaftszweigs"). Firmen und juristische Personen nehmen den Schlüssel aus dem KBA-Verzeichnis SV 5, etwa `G01` für den Handel mit Kraftfahrzeugen; fehlt er, `400`. Privatpersonen ohne Angabe erhalten "888"; Freiberufler und Einzelunternehmer geben ihren Schlüssel an. Geprüft wird nur die Form. Bei der Halteränderung, beim Bevollmächtigten und beim Lieferungsempfänger optional.
powerOfAttorney PowerOfAttorney
representative HolderParty
address* HolderAddress
firstName string
lastName string
companyName string
gender enum
Nur bei natürlichen Personen zulässig.
FEMALE · MALE · DIVERSE · UNSPECIFIED
streetName string
houseNumber string
Laut XKfz-Schema NUR Ziffern, höchstens vier. Ein Zusatz wie "7a" ist dort nicht vorgesehen und gehört in addressSuffix.
zipCode string
cityName string
countryCode string
KBA-Staatsschlüssel. Ohne Angabe D.
addressSuffix string
partyType enum
Die Art des Beteiligten. **Freiwillig und zusätzlich** — ohne Angabe gilt wie bisher der Name: `companyName` heisst juristische Person, sonst natürliche Person. - `NATURAL_PERSON`, `LEGAL_PERSON` — die beiden bisherigen Arten, ausdrücklich benannt. - `AUTHORITY` — eine Behörde. Geht im XML als juristische Person hinaus; das Schema kennt keine eigene Art. - `SOLE_TRADER` — Einzelunternehmer. MIT `companyName` juristische Person, OHNE natürliche Person (amtliche Dokumentation zur Vollmacht: „Status als juristische Person wird nur dann zuerkannt, wenn ‚Name des Unternehmens' ausgefüllt ist"). Der Berufs-/Wirtschaftszweigschlüssel ist in beiden Fällen anzugeben — `888` gilt nur für Privatpersonen. - `ASSOCIATION` — eine nicht rechtsfähige Vereinigung, etwa eine GbR ohne Registereintrag oder eine Erbengemeinschaft. Geht als eigene Struktur (`NameVereinigung`) ans KBA, mit optionalem Vertreter. Ein eingetragener Verein ist dagegen eine juristische Person. Erweiterung gegenüber kennzeichen.dev.
NATURAL_PERSON · LEGAL_PERSON · AUTHORITY · SOLE_TRADER · ASSOCIATION
associationRepresentative object
Der benannte Vertreter einer Vereinigung — nur bei `partyType: ASSOCIATION` und dort freiwillig (seit XKfz 6.0 optional). In `POST /powerOfAttorneys` gibt es ihn nicht: Für eine Vereinigung lässt sich über uns keine Vollmacht unterschreiben (siehe `principal`).
firstName string
lastName string
companyName string
dateOfBirth string (date)
Streng als JJJJ-MM-TT. Nur bei natürlichen Personen. Zulässiger Bereich 1880–2099.
placeOfBirth string
Nur bei natürlichen Personen.
occupationKey string
Berufs- bzw. Wirtschaftszweigschlüssel, drei Stellen. Beim Halter einer Zulassung (UG, WG, WZ, NZ, TZ) Pflicht (KBA-Wissensartikel „Angabe des Berufsschlüssels bzw. Wirtschaftszweigs"). Firmen und juristische Personen nehmen den Schlüssel aus dem KBA-Verzeichnis SV 5, etwa `G01` für den Handel mit Kraftfahrzeugen; fehlt er, `400`. Privatpersonen ohne Angabe erhalten "888"; Freiberufler und Einzelunternehmer geben ihren Schlüssel an. Geprüft wird nur die Form. Bei der Halteränderung, beim Bevollmächtigten und beim Lieferungsempfänger optional.
documentBase64 string (byte)
Das unterschriebene Vollmacht-PDF, Base64-kodiert — selbst mitgebracht.
processId integer
Nummer eines Vollmachtsvorgangs, der über diesen Dienst unterschrieben wurde (siehe Self-Service-Bereich, „Vollmachtsvorgänge"). Wir hängen das signierte Dokument dann selbst an und gleichen die Vollmacht vorab gegen die Antragsdaten ab. Ist der Vorgang unbekannt oder gehört er einem anderen Mandanten: 404. Ist er noch nicht unterschrieben: 409, mit seinem Stand in der Meldung — und zwar vor jeder Feldprüfung: Feldfehler und der Abgleich mit der Vollmacht melden sich erst nach der Unterschrift. Ein 400 danach verbraucht den Vorgang nicht; der korrigierte Antrag darf dieselbe processId nennen.
deliveryRecipient object
Abweichender Empfänger der Zulassungsunterlagen.
address* HolderAddress
firstName string
lastName string
companyName string
gender enum
Nur bei natürlichen Personen zulässig.
FEMALE · MALE · DIVERSE · UNSPECIFIED
streetName string
houseNumber string
Laut XKfz-Schema NUR Ziffern, höchstens vier. Ein Zusatz wie "7a" ist dort nicht vorgesehen und gehört in addressSuffix.
zipCode string
cityName string
countryCode string
KBA-Staatsschlüssel. Ohne Angabe D.
addressSuffix string
partyType enum
Die Art des Beteiligten. **Freiwillig und zusätzlich** — ohne Angabe gilt wie bisher der Name: `companyName` heisst juristische Person, sonst natürliche Person. - `NATURAL_PERSON`, `LEGAL_PERSON` — die beiden bisherigen Arten, ausdrücklich benannt. - `AUTHORITY` — eine Behörde. Geht im XML als juristische Person hinaus; das Schema kennt keine eigene Art. - `SOLE_TRADER` — Einzelunternehmer. MIT `companyName` juristische Person, OHNE natürliche Person (amtliche Dokumentation zur Vollmacht: „Status als juristische Person wird nur dann zuerkannt, wenn ‚Name des Unternehmens' ausgefüllt ist"). Der Berufs-/Wirtschaftszweigschlüssel ist in beiden Fällen anzugeben — `888` gilt nur für Privatpersonen. - `ASSOCIATION` — eine nicht rechtsfähige Vereinigung, etwa eine GbR ohne Registereintrag oder eine Erbengemeinschaft. Geht als eigene Struktur (`NameVereinigung`) ans KBA, mit optionalem Vertreter. Ein eingetragener Verein ist dagegen eine juristische Person. Erweiterung gegenüber kennzeichen.dev.
NATURAL_PERSON · LEGAL_PERSON · AUTHORITY · SOLE_TRADER · ASSOCIATION
associationRepresentative object
Der benannte Vertreter einer Vereinigung — nur bei `partyType: ASSOCIATION` und dort freiwillig (seit XKfz 6.0 optional). In `POST /powerOfAttorneys` gibt es ihn nicht: Für eine Vereinigung lässt sich über uns keine Vollmacht unterschreiben (siehe `principal`).
firstName string
lastName string
companyName string
dateOfBirth string (date)
Streng als JJJJ-MM-TT. Nur bei natürlichen Personen. Zulässiger Bereich 1880–2099.
placeOfBirth string
Nur bei natürlichen Personen.
occupationKey string
Berufs- bzw. Wirtschaftszweigschlüssel, drei Stellen. Beim Halter einer Zulassung (UG, WG, WZ, NZ, TZ) Pflicht (KBA-Wissensartikel „Angabe des Berufsschlüssels bzw. Wirtschaftszweigs"). Firmen und juristische Personen nehmen den Schlüssel aus dem KBA-Verzeichnis SV 5, etwa `G01` für den Handel mit Kraftfahrzeugen; fehlt er, `400`. Privatpersonen ohne Angabe erhalten "888"; Freiberufler und Einzelunternehmer geben ihren Schlüssel an. Geprüft wird nur die Form. Bei der Halteränderung, beim Bevollmächtigten und beim Lieferungsempfänger optional.
sepaMandateBase64 string (byte)
SEPA-Mandat als PDF. Anders als bei der Vollmacht ist hier ein Scan zulässig. Entfällt, wenn sich der Antrag über `powerOfAttorney.processId` auf einen Vollmachtsvorgang mit `bankAccount` beruft: Dann hängen wir das dort signierte Mandat an — sofern `bankAccount` hier dieselbe IBAN und denselben Kontoinhaber nennt, sonst `400`. Mitgeschickt hat dieses Feld Vorrang.
bankAccount BankAccount
iban* string
accountHolder* string
usage enum
Steuer · Gebuehren
directDebitMandateGranted boolean
taxDetails TaxDetails
paymentInterval* enum
jaehrlich · halbjaehrlich · vierteljaehrlich
taxLargeCustomerId string
Großkunden-ID der Steuer. Liegt sie vor, entfällt das SEPA-Mandat. Zollform — drei Ziffern, ein Großbuchstabe, vier Ziffern —, seit XKfz 6.0 verbindlich; andere Formen weisen wir mit 400 ab.
taxExemptionRequested boolean
Befreiung von der Kfz-Steuer beantragen. Ohne diese Angabe lässt sich ein Fahrzeug mit Steuerbefreiung — etwa bei Schwerbehinderung — nicht anmelden.
taxExemptionReason string
Grund der Steuerbefreiung. Wird unverändert durchgereicht und nicht gegen eine Liste geprüft: Welche Gründe es gibt, sagen die vorliegenden KBA-Unterlagen nicht; im amtlichen Beispiel steht `18`.
inspections InspectionDetails[]
reportDate string (date)
nextInspection* string
Fälligkeit der nächsten Untersuchung als MMJJJJ.
inspectionType enum
Ohne Angabe wird HU gesendet (Codeliste artderuntersuchung, Klartext „Hauptuntersuchung“). Eine Sicherheitsprüfung muss ausdrücklich SP setzen.
HU · SP
institutionKey string
Schlüsselnummer der Überwachungsinstitution oder des ZDK. Wird ungeprüft durchgereicht und als schluesselnummerDerUeberwachungsinstitutionOderZDK gesendet.
inspectionDate string (date)
expressProcedure boolean
checkDigit string
deliveries DeliveryInstruction[]
deliveryService* enum
Zustellweg (Codeliste lieferdienst). AbholungBevollmaechtigter ist die Abholung durch den Bevollmächtigten — vom KBA am 14.05.2024 bestätigt, in keinem amtlichen Beispiel enthalten.
ZusendungHalter · ZusendungBevollmaechtigter · ZusendungDritter · Abholung · AbholungHalter · AbholungBevollmaechtigter
deliverTo enum
Wessen Anschrift gilt — hat Vorrang vor dem deliveryService. Ohne Angabe benennt der deliveryService den Empfänger (ZusendungHalter und AbholungHalter den Halter, ZusendungDritter den deliveryRecipient und so fort); benennt auch er niemanden (Abholung), gilt der deliveryRecipient, sonst der Bevollmächtigte, sonst der Halter. Verglichen wird gegen die Vollmacht, wer nach dieser Regel wirklich beliefert wird: ZusendungHalter mit deliverTo RECIPIENT gilt als Lieferung an den Dritten und ergibt gegen eine Vollmacht „an den Halter" 400.
HOLDER · REPRESENTATIVE · RECIPIENT
orderedAt string (date)
items* DeliveryItem[]
documentType* string
Codeliste artderunterlage — 2 ZB I, 3 ZB II, 27 HU-Plakette, 37 Siegelplakette, 39 HU-Plakettenträger, 42 Beiblatt zur ZB I, 40 Stempelplakettenträger (44 in älteren Beispielen, wird weiter angenommen).
quantity* integer
email* string (email)
externalOrderId string
Ihre eigene Auftragsreferenz. Wird in Webhook-Events zurückgegeben — und ist zugleich der Schutz gegen den doppelt gestellten Antrag: Derselbe Mandant, dieselbe `externalOrderId`, dieselbe FIN UND derselbe Geschäftsvorfall (Endpunkt) innerhalb von 15 Minuten gelten als Wiederholungsversuch. Es geht dann NICHTS erneut an das KBA, und die Antwort nennt den bestehenden Vorgang (HTTP 200, dieselbe `order.id`). So führt eine Zeitüberschreitung samt automatischer Wiederholung Ihres Clients nicht zu zwei Anträgen und zwei Gebühren. Ohne Referenz greift der Schutz nicht — dann fehlt die Aussage „das ist derselbe Auftrag". **Weichen die Daten ab, ist es kein Wiederholungsversuch:** Dieselbe Referenz und FIN mit geändertem Inhalt beantwortet der Dienst mit **409** und ändert nichts. Weder darf er die Korrektur still verwerfen noch ungefragt einen zweiten Antrag samt Gebühr auslösen. Für einen weiteren Antrag eine eigene Referenz vergeben; für eine Berichtigung den bestehenden Vorgang korrigieren. **Dieselbe Referenz an einem anderen Endpunkt** — etwa NZ statt TZ oder WG statt WZ — ist kein Wiederholungsversuch, sondern ein neuer Antrag samt Gebühr. Ein falsch gewählter Endpunkt lässt sich nicht durch erneutes Senden unter derselben Referenz berichtigen.
correctionOf integer (int64)
Vorgangsnummer eines abgewiesenen oder fehlgeschlagenen Auftrags, der mit diesem Rumpf korrigiert werden soll. Es entsteht ein neuer KBA-Versuch am selben Auftrag; die Antwort nennt `attemptOf` und `attempt`. Laufende oder beschiedene Aufträge sowie ein anderer Geschäftsvorfall ergeben 409.
gksConfigurationId string (uuid)
{
  "externalOrderId": "tageszulassung-4711",
  "email": "kunde@example.de",
  "customization": {
    "vehicleIdentificationNumber": "WVWZZZ7HZ8H222222",
    "licensePlateAssignment": {
      "plateType": "Z"
    },
    "vehicleRegistrationCertificatePartII": {
      "number": "ZZ112979",
      "securityCode": "BgDwroY6tly4"
    },
    "insuranceConfirmationNumber": "R245654"
  },
  "vehicleHolder": {
    "address": {
      "companyName": "Chaos-Klempnerei Wassermarsch OHG",
      "streetName": "Am Bahnhof",
      "houseNumber": "15",
      "zipCode": "24983",
      "cityName": "Handewitt",
      "countryCode": "D"
    },
    "occupationKey": "F00"
  },
  "taxDetails": {
    "paymentInterval": "jaehrlich",
    "taxLargeCustomerId": "123A4567"
  }
}

Antworten

200 Der Antrag wurde angenommen.
order* object
id* integer (int64)
attemptOf integer (int64)
Nur bei einer Korrektur — die Auftragsnummer der Versuchskette.
attempt integer
Nur bei einer Korrektur — die laufende Nummer des neuen Versuchs.
{
  "order": {
    "id": 1
  }
}
400
401
403
404
409
413
415
500
503
default
GET/registrationOffices/{districtKey}/availabilityErreichbarkeit einer Zulassungsbehörde prüfen

Ist das i-Kfz-Portal einer Zulassungsbehörde gerade erreichbar? Vor der Antragstellung zu prüfen, ob eine automatisierte Zulassung zu diesem Zeitpunkt überhaupt möglich ist. Ohne die Abfrage gehen Anträge auch an Behörden, deren Portal gerade nicht bereitsteht; sie laufen dann in die manuelle Bearbeitung (00775). Der Aufruf ist **lesend**: Es entsteht kein Vorgang und keine Gebühr.

Parameter

districtKey*pathKreisschlüssel der Zulassungsbehörde, z. B. 06411.
officeSuffixqueryZusatzziffer, wenn ein Kreis mehrere Zulassungsstellen führt.

Antworten

200 Die Erreichbarkeit wurde ermittelt.
districtKey* string
Der abgefragte Kreisschlüssel, unverändert zurückgegeben.
available* boolean
True, wenn das Portal der Behörde zum Abfragezeitpunkt bereitsteht. Eine Zusage für den späteren Antrag ist das nicht — zwischen Abfrage und Antrag kann das Portal ausfallen.
messages* object[]
Die Quittungseinträge des KBA zur Abfrage.
code* string
Quittungscode
text string
additional string
400
401
403
500
502 Die Erreichbarkeit ließ sich nicht ermitteln.
error* string
Fehlerbeschreibung einschließlich TraceId.
traceId string
Auch im Header X-Trace-Id enthalten. Bei Rückfragen an den Support anzugeben.
default
GET/serviceStatusBetriebslage abrufen

Störungen, Wartungen und Hinweise — damit Sie den Zustand in Ihrer eigenen Oberfläche zeigen können, statt Ihre Endkunden erst durch einen scheiternden Antrag davon erfahren zu lassen. **`operational` ist eine redaktionelle Auskunft, kein Selbsttest.** Es sagt: „Uns ist zurzeit keine Störung und keine Wartung bekannt." Gespeist wird es aus den gemeldeten Betriebsmeldungen — ein bloßer **Hinweis** (eine neue Gebührenordnung etwa) färbt die Ampel bewusst NICHT rot; nur `stoerung` und `wartung` tun das. **Was es NICHT misst: den Durchsatz.** Ein Rückkanal, der langsamer wird oder stockt, lässt `operational` auf `true` — Ihre Aufträge sehen dabei gesund aus (`state: inBearbeitung`, `derivedStatus: PENDING`), es kommen keine Webhooks und keine Fehler. Eine frühere Fassung dieser Beschreibung sagte „beantwortet die eine Frage, die zählt: Läuft alles?", und das liest sich als technische Zusage, die dieses Feld nicht einlösen kann. **Wenn Sie Stockungen bemerken wollen, messen Sie sie selbst.** Der verlässliche Weg steht Ihnen offen: `GET …/orders?state=inBearbeitung` liefert die offenen Aufträge mit ihrem `createdAt` — alarmieren Sie, wenn der älteste davon zu lange offen ist. Eine Schwelle können wir Ihnen nicht vorgeben; sie hängt an Ihrer Menge und daran, wie schnell das KBA an diesem Tag antwortet.

Antworten

200 Die aktuelle Betriebslage.
operational* boolean
False, sobald eine Störung oder Wartung aktiv ist. Ein reiner Hinweis lässt die Ampel grün. **Kein Schalter für die Einlieferung.** Das Feld beschreibt die Betriebslage, wie sie hier bekannt ist — es sagt nicht, dass Anträge abgewiesen werden. POWRdrive nimmt sie auch bei `false` an und reicht sie weiter; ob das KBA im Wartungsfenster antwortet, entscheidet das KBA. Wer seine Einlieferung an dieses Feld koppelt, hält sie unnötig an: Über 400 Aufträge sind fehlerfrei abgesetzt worden, während es dauerhaft auf `false` stand. Als Anzeige in Ihrer Oberfläche ist es richtig, als Ampel für den Versand nicht.
announcements* ServiceAnnouncement[]
Aktuell geltende Meldungen.
id* integer
type* enum
Nur `stoerung` und `wartung` setzen `operational` auf false.
stoerung · wartung · hinweis
title* string
summary string
Eine Zeile für die Liste.
text string
Der Fließtext für die Einzelansicht.
slug string
affects string
Was betroffen ist, z. B. eine einzelne Zulassungsbehörde.
startsAt string
endsAt string
resolvedAt string
scheduled* ServiceAnnouncement[]
Angekündigte, noch nicht begonnene Meldungen. **Die festen Wartungsfenster des KBA stehen hier nicht.** Sie gelten jede Woche gleich und sind unter „Wartungsfenster des KBA" in der Doku (/docs/fehler) beschrieben. Hier erscheinen nur Meldungen, die der Betrieb einträgt — etwa eine angekündigte Sonderwartung. Mitten in einem regulären Fenster kann die Antwort also `operational: true` mit leeren Listen sein.
id* integer
type* enum
Nur `stoerung` und `wartung` setzen `operational` auf false.
stoerung · wartung · hinweis
title* string
summary string
Eine Zeile für die Liste.
text string
Der Fließtext für die Einzelansicht.
slug string
affects string
Was betroffen ist, z. B. eine einzelne Zulassungsbehörde.
startsAt string
endsAt string
resolvedAt string
401
403
500
default
GET/invoicesRechnungen abrufen

Die Rechnungen des Mandanten samt offenem Gesamtbetrag.

Antworten

200 Die Rechnungen des Mandanten.
invoices* Invoice[]
id* integer
number* string
periodFrom* string (date)
periodTo* string (date)
netAmountCents* integer
grossAmountCents* integer
dueDate string (date)
paidDate string (date)
status* InvoiceStatus
overdue* boolean
Errechnet aus Fälligkeit und Zahlungsstand — nicht identisch mit `status: ueberfaellig`, der gemeldet werden muss.
pdfUrl string
openAmountCents* integer
Summe der offenen Beträge in Cent.
401
403
500
default
POST/invoicesRechnung melden

Nimmt eine Rechnung aus dem Abrechnungssystem entgegen. **Dieses System erzeugt keine Rechnungen.** Sie entstehen im Abrechnungssystem und werden hierher gemeldet, damit sie im Dashboard und über `GET /invoices` sichtbar werden. Die `invoiceNumber` ist deshalb **gegeben, nicht vergeben**, und dient als Schlüssel: Ein wiederholter Aufruf erzeugt keine zweite Rechnung, aber ein späterer Stand („bezahlt" nach „offen") kommt an. **Diese Route gehört dem Abrechnungssystem.** Es weist sich zusätzlich zur gewöhnlichen Anmeldung mit der Kopfzeile `X-Abrechnung-Token` aus; ohne sie antwortet die Route mit `403`. Ist auf der Instanz kein Geheimnis eingerichtet, nimmt sie gar nichts entgegen (`503`) — sonst könnte jeder API-Benutzer die Rechnungen seines eigenen Mandanten schreiben und auf „bezahlt" setzen.

Request application/json

invoiceNumber* string
Die Rechnungsnummer aus dem Abrechnungssystem. Dient als Schlüssel — ein zweiter Aufruf mit derselben Nummer aktualisiert die Rechnung, statt eine weitere anzulegen.
periodFrom* string (date)
Abrechnungszeitraum
periodTo* string (date)
Abrechnungszeitraum
netAmountCents* integer
Nettobetrag in Cent. Ganze Zahl — Gleitkomma auf Geldbeträgen erzeugt Rundungsfehler, die erst in der Rechnung auffallen.
grossAmountCents* integer
Bruttobetrag in Cent, ganzzahlig.
dueDate string (date)
paidDate string (date)
status InvoiceStatus
pdfUrl string
Adresse des Rechnungs-PDF. Nur `http`/`https`; andere Schemata werden mit 400 abgewiesen.

Antworten

200 Die Rechnung wurde übernommen.
invoice* object
id* integer
number* string
{
  "invoice": {
    "id": 1,
    "number": "RE-2026-0001"
  }
}
400
401
403
413
415
500
default
POST/gksConfigurationsGKS-Zugang anlegen

Hinterlegt eine eigene KBA-Identität für diesen Mandanten: Kennung, Passwort, KoPa-Schlüssel und Schlüsselmaterial. Die zurückgegebene `id` ist der Wert, den Sie anschließend als `gksConfigurationId` in jedem Antrag mitgeben. Ohne `gksConfigurationId` geht ein Antrag unter der Grundkonfiguration des Servers hinaus. **Schlüsselmaterial:** Senden Sie `publicKeyCertificate` und `privateKey` als PEM-Text. Schlüsselmaterial ist Pflicht: Fehlen beide Felder, antwortet der Dienst mit 400. Beide gehören zusammen — wird nur eines geschickt, antwortet der Dienst mit 400, statt die fehlende Hälfte zu erzeugen: Ein Schlüssel, der nicht zum Zertifikat passt, erzeugt Signaturen, die das KBA ablehnt, und drei abgewiesene Anmeldungen sperren die Kennung. **Form des Zertifikats:** X.509 v3, Laufzeit höchstens ein Jahr. Über 366 Tage wird das Zertifikat mit 400 abgewiesen; genau 366 Tage und X.509 v1 werden angenommen und nur angemerkt. Angenommen hat die KBA-Registrierungsanwendung 364 Tage; v1 hat sie am 07.09.2026 abgewiesen. Die Anmerkungen stehen NICHT in dieser Antwort — der Zustand der hinterlegten Zertifikate steht unter `GET /health` als `gksCertificates.needAttention` (das die X.509-Version nicht erfasst) und im Klartext im Self-Service-Bereich unter „GKS-Zugänge". **Pfade nimmt diese Schnittstelle nicht an.** `certificatePath` und `privateKeyPath` werden mit 400 abgewiesen — sie sagten sonst jedem API-Benutzer, welche Dateien auf dem Server liegen, und liessen ein Gerät wie `/dev/zero` als Zertifikat eintragen. Dateien, die schon auf dem Server liegen, trägt allein der Betreiber im Self-Service-Bereich ein. In die Datenbank kommt nur der Pfad der abgelegten Datei; der private Schlüssel steht nie darin und wird nie zurückgegeben. **Längen:** `name` höchstens 100 Zeichen, `username` (GKS-Kennung) 20, `password` 200, `kopaKey` und `largeCustomerId` 20, `company` 255, PEM-Text je 65 536. Darüber 400. Das Passwort wird verschlüsselt abgelegt (AES-256-GCM) und **niemals zurückgegeben**.

Request application/json

name* string
Sprechender Name des Zugangs.
kopaKey* string
KoPa-Schlüssel des Großkunden, z. B. U195303.
largeCustomerId string
Siebenstellige Großkunden-ID aus der KBA-Registrierung.
username* string
GKS-Kennung für die Anmeldung. Höchstens 20 Zeichen.
password* string (password)
GKS-Passwort. Wird verschlüsselt abgelegt und nie zurückgegeben. Läuft laut KBA alle 90 Tage ab.
publicKeyCertificate string
Das X.509-Zertifikat als PEM-Text, von der Zeile `-----BEGIN CERTIFICATE-----` bis `-----END CERTIFICATE-----`. Gehört mit `privateKey` zusammen gesendet. X.509 **v3**; ein v1-Zertifikat wird angenommen und nur angemerkt, von der KBA-Registrierungsanwendung aber seit dem 07.09.2026 nicht mehr. Laufzeit höchstens ein Jahr: über 366 Tage 400, genau 366 Tage nur eine Anmerkung, angenommen wurden 364 Tage. Beim KBA wird dasselbe Zertifikat als Base64-`.cer` hochgeladen.
privateKey string (password)
Der private Schlüssel als PEM-Text. Wird als Datei abgelegt; in der Datenbank steht nur der Pfad, und zurückgegeben wird er nie.
environment enum
Bestimmt die KBA-Endpunkte. Ein Testzugang gerät damit niemals auf die Produktionsstrecke.
test · produktion
company —
Firma des Großkunden. Zeichenkette oder Objekt mit `name` — aus einem Objekt wird nur der Name übernommen, die Anschrift wird nicht gebraucht.

Antworten

201 Der Zugang wurde angelegt.
id string (uuid)
Als `gksConfigurationId` in jedem Antrag verwendbar.
name string
kopaKey string
largeCustomerId string
username string
environment enum
test · produktion
company string
createdAt string (date-time)
certificatePresent boolean
Liegt die Zertifikatsdatei tatsächlich auf dem Server?
privateKeyPresent boolean
400
401
403
413
415
500
503 Es ist kein GKS_SECRET_KEY eingerichtet — ohne ihn werden keine Zugangsdaten gespeichert.
default
PUT/gksConfigurations/{id}GKS-Zugang ändern

Ändert einen Zugang. Ein weggelassenes `password` bleibt unverändert — so lässt sich etwa der Name korrigieren, ohne das Passwort erneut einzugeben.

Parameter

id*path

Request application/json

name* string
Sprechender Name des Zugangs.
kopaKey* string
KoPa-Schlüssel des Großkunden, z. B. U195303.
largeCustomerId string
Siebenstellige Großkunden-ID aus der KBA-Registrierung.
username* string
GKS-Kennung für die Anmeldung. Höchstens 20 Zeichen.
password* string (password)
GKS-Passwort. Wird verschlüsselt abgelegt und nie zurückgegeben. Läuft laut KBA alle 90 Tage ab.
publicKeyCertificate string
Das X.509-Zertifikat als PEM-Text, von der Zeile `-----BEGIN CERTIFICATE-----` bis `-----END CERTIFICATE-----`. Gehört mit `privateKey` zusammen gesendet. X.509 **v3**; ein v1-Zertifikat wird angenommen und nur angemerkt, von der KBA-Registrierungsanwendung aber seit dem 07.09.2026 nicht mehr. Laufzeit höchstens ein Jahr: über 366 Tage 400, genau 366 Tage nur eine Anmerkung, angenommen wurden 364 Tage. Beim KBA wird dasselbe Zertifikat als Base64-`.cer` hochgeladen.
privateKey string (password)
Der private Schlüssel als PEM-Text. Wird als Datei abgelegt; in der Datenbank steht nur der Pfad, und zurückgegeben wird er nie.
environment enum
Bestimmt die KBA-Endpunkte. Ein Testzugang gerät damit niemals auf die Produktionsstrecke.
test · produktion
company —
Firma des Großkunden. Zeichenkette oder Objekt mit `name` — aus einem Objekt wird nur der Name übernommen, die Anschrift wird nicht gebraucht.

Antworten

200 Der Zugang wurde geändert.
id string (uuid)
Als `gksConfigurationId` in jedem Antrag verwendbar.
name string
kopaKey string
largeCustomerId string
username string
environment enum
test · produktion
company string
createdAt string (date-time)
certificatePresent boolean
Liegt die Zertifikatsdatei tatsächlich auf dem Server?
privateKeyPresent boolean
400
401
403
404 Zugang unbekannt.
error* string
Fehlerbeschreibung einschließlich TraceId.
traceId string
Auch im Header X-Trace-Id enthalten. Bei Rückfragen an den Support anzugeben.
413
415
500
503 Es ist kein GKS_SECRET_KEY eingerichtet — ohne ihn lässt sich ein mitgeschicktes `password` nicht ablegen. Ein Aufruf ohne `password` ist davon nicht betroffen.
error* string
Fehlerbeschreibung einschließlich TraceId.
traceId string
Auch im Header X-Trace-Id enthalten. Bei Rückfragen an den Support anzugeben.
default
DELETE/gksConfigurations/{id}GKS-Zugang löschen

Löscht einen Zugang. Solange **Vorgänge** darauf verweisen, schlägt das mit 409 fehl: Die Zuordnung, unter welcher Identität ein Antrag gestellt wurde, gehört zur Protokollierung und ist zwei Jahre aufzubewahren.

Parameter

id*path

Antworten

204 Gelöscht.
401
403
404 Zugang unbekannt.
error* string
Fehlerbeschreibung einschließlich TraceId.
traceId string
Auch im Header X-Trace-Id enthalten. Bei Rückfragen an den Support anzugeben.
409 Es hängen noch Vorgänge daran.
500
default
GET/gksConfigurations/overviewsEigene GKS-Zugänge auflisten

Nur die Zugänge des anfragenden Mandanten.

Antworten

200 Die Zugänge dieses Mandanten.
overviewGksConfigurations* GksConfigurationOverview[]
id string (uuid)
Als `gksConfigurationId` in jedem Antrag verwendbar.
name string
kopaKey string
largeCustomerId string
username string
environment enum
test · produktion
company string
createdAt string (date-time)
certificatePresent boolean
Liegt die Zertifikatsdatei tatsächlich auf dem Server?
privateKeyPresent boolean
401
403
500
default
GET/gksConfigurations/overviews/{id}Einen GKS-Zugang abrufen

Parameter

id*path

Antworten

200 Der Zugang.
id string (uuid)
Als `gksConfigurationId` in jedem Antrag verwendbar.
name string
kopaKey string
largeCustomerId string
username string
environment enum
test · produktion
company string
createdAt string (date-time)
certificatePresent boolean
Liegt die Zertifikatsdatei tatsächlich auf dem Server?
privateKeyPresent boolean
401
403
404 Zugang unbekannt.
error* string
Fehlerbeschreibung einschließlich TraceId.
traceId string
Auch im Header X-Trace-Id enthalten. Bei Rückfragen an den Support anzugeben.
500
default
POST/licensePlateReservations/availabilityChecksVerfügbarkeit eines Wunschkennzeichens prüfen

**POWRdrive: 501.** Reservierungen gehören zum Schilderversand.

Request application/json

registrationOfficeServiceId* string
Kennung des Reservierungsdienstes der Behoerde.
licensePlateNumberPatternComponents* EuroLicensePlateNumberComponents
usageType enum
Kennzeichenmerkmal — für alle Anträge mit bisherigem Kennzeichen (AB, HA, UG, WG, WZ): EURO (Normalfall), ELECTRIC (Elektrokennzeichen) und HISTORIC (Oldtimerkennzeichen); andere Werte werden mit HTTP 400 abgewiesen.
EURO · ELECTRIC · HISTORIC
city* string
Unterscheidungszeichen, 1–3 Buchstaben (Umlaute zulässig). Kleinbuchstaben werden großgeschrieben; das Muster lässt sie deshalb zu.
middle* string
Erkennungsbuchstaben, 1–2 Buchstaben ohne Umlaute. Kleinbuchstaben werden großgeschrieben.
end* string
Erkennungsnummer, 1–4 Ziffern.

Antworten

200 Verfügbare Kennzeichennummern.
available boolean
Ist das Kennzeichen frei?
reservationCode string
Vom Portal vergebener Code, falls einer entsteht.
400
401
413
415
500
501
default
POST/licensePlateReservations/reservationsWunschkennzeichen reservieren

**POWRdrive: 501.** Ergebnis käme sonst per Webhook (LICENSE_PLATE_RESERVATION_*).

Request application/json

externalOrderId* string
email* string (email)
customization* object
licensePlateNumberComponents EuroLicensePlateNumberComponents
usageType enum
Kennzeichenmerkmal — für alle Anträge mit bisherigem Kennzeichen (AB, HA, UG, WG, WZ): EURO (Normalfall), ELECTRIC (Elektrokennzeichen) und HISTORIC (Oldtimerkennzeichen); andere Werte werden mit HTTP 400 abgewiesen.
EURO · ELECTRIC · HISTORIC
city* string
Unterscheidungszeichen, 1–3 Buchstaben (Umlaute zulässig). Kleinbuchstaben werden großgeschrieben; das Muster lässt sie deshalb zu.
middle* string
Erkennungsbuchstaben, 1–2 Buchstaben ohne Umlaute. Kleinbuchstaben werden großgeschrieben.
end* string
Erkennungsnummer, 1–4 Ziffern.
vehicleHolder* VehicleDeregistrationRequestVehicleHolder
address Address
firstName string
lastName string
companyName string
streetName string
houseNumber string
zipCode string
cityName string
countryCode string
KBA-Staatsschlüssel

Antworten

200 Zur Bearbeitung angelegte Objekte.
reservationCode string
validUntil string (date-time)
Bis wann die Reservierung gilt.
400
401
413
415
500
501
default
POST/ordersBestellung anlegen (physische Schilder)

**Wird an den Schilderdienst durchgereicht**, sofern einer konfiguriert ist: Rumpf und Content-Type gehen unverändert hinaus, Status und Rumpf kommen unverändert zurück. Die Pflichtfelder prüft dann der Zieldienst, nicht dieser hier. Ohne konfigurierten Schilderdienst antwortet POWRdrive mit **501** — Schilderdruck und -versand sind kein GKS. Versandereignisse (`DELIVERY_*`) meldet der Schilderdienst weiterhin unmittelbar an den dort hinterlegten Webhook. Kommt er nicht zustande, antwortet dieser Endpunkt mit **502**.

Request application/json

externalId* string
Ihre eigene Auftragsnummer.
email* string (email)
deliveryAddress* Address
firstName string
lastName string
companyName string
streetName string
houseNumber string
zipCode string
cityName string
countryCode string
KBA-Staatsschlüssel
invoiceAddress* Address
firstName string
lastName string
companyName string
streetName string
houseNumber string
zipCode string
cityName string
countryCode string
KBA-Staatsschlüssel
items* object[]
productVariantId integer
name string
sku string
quantity* integer
customization object
Z. B. `productType: LICENSE_PLATE` und `licensePlateNumberComponents`.

Antworten

201 Angelegte Bestellung.
id integer
Kennung der Bestellung beim Schilderdienst.
400
401
413
415
500
501
502 Der Schilderdienst kam nicht zustande.
error* string
Fehlerbeschreibung einschließlich TraceId.
traceId string
Auch im Header X-Trace-Id enthalten. Bei Rückfragen an den Support anzugeben.
default
POST/orders/emissionStickerOrdersFeinstaubplakette bestellen

**Wird an den Schilderdienst durchgereicht**, sofern einer konfiguriert ist: Rumpf und Content-Type gehen unverändert hinaus, Status und Rumpf kommen unverändert zurück. Die Pflichtfelder prüft dann der Zieldienst, nicht dieser hier. Ohne konfigurierten Schilderdienst antwortet POWRdrive mit **501** — Schilderdruck und -versand sind kein GKS. Versandereignisse (`DELIVERY_*`) meldet der Schilderdienst weiterhin unmittelbar an den dort hinterlegten Webhook. Kommt er nicht zustande, antwortet dieser Endpunkt mit **502**. Multipart (Antrag + ZB-I-Dateien).

Request multipart/form-data

order object
files string[]

Antworten

201 Angelegte Bestellung.
id integer
401
413
415
500
501
502 Der Schilderdienst kam nicht zustande.
error* string
Fehlerbeschreibung einschließlich TraceId.
traceId string
Auch im Header X-Trace-Id enthalten. Bei Rückfragen an den Support anzugeben.
default
POST/orders/reshippedOrdersErsatzlieferung für eine Rücksendung anlegen

**Wird an den Schilderdienst durchgereicht**, sofern einer konfiguriert ist: Rumpf und Content-Type gehen unverändert hinaus, Status und Rumpf kommen unverändert zurück. Die Pflichtfelder prüft dann der Zieldienst, nicht dieser hier. Ohne konfigurierten Schilderdienst antwortet POWRdrive mit **501** — Schilderdruck und -versand sind kein GKS. Versandereignisse (`DELIVERY_*`) meldet der Schilderdienst weiterhin unmittelbar an den dort hinterlegten Webhook. Kommt er nicht zustande, antwortet dieser Endpunkt mit **502**.

Request application/json

returnedDeliveryId* integer
Kennung der Ruecksendung beim Schilderdienst.
externalId* string
deliveryAddress* Address
firstName string
lastName string
companyName string
streetName string
houseNumber string
zipCode string
cityName string
countryCode string
KBA-Staatsschlüssel
invoiceAddress* Address
firstName string
lastName string
companyName string
streetName string
houseNumber string
zipCode string
cityName string
countryCode string
KBA-Staatsschlüssel

Antworten

201 Angelegte Bestellung.
id integer
Kennung der Bestellung beim Schilderdienst.
400
401
413
415
500
501
502 Der Schilderdienst kam nicht zustande.
error* string
Fehlerbeschreibung einschließlich TraceId.
traceId string
Auch im Header X-Trace-Id enthalten. Bei Rückfragen an den Support anzugeben.
default

Datentypen

TYPRegistrationOfficeAvailability
districtKey* string
Der abgefragte Kreisschlüssel, unverändert zurückgegeben.
available* boolean
True, wenn das Portal der Behörde zum Abfragezeitpunkt bereitsteht. Eine Zusage für den späteren Antrag ist das nicht — zwischen Abfrage und Antrag kann das Portal ausfallen.
messages* object[]
Die Quittungseinträge des KBA zur Abfrage.
code* string
Quittungscode
text string
additional string
{
  "districtKey": "06411",
  "available": true,
  "messages": []
}
TYPServiceAnnouncement
id* integer
type* enum
Nur `stoerung` und `wartung` setzen `operational` auf false.
stoerung · wartung · hinweis
title* string
summary string
Eine Zeile für die Liste.
text string
Der Fließtext für die Einzelansicht.
slug string
affects string
Was betroffen ist, z. B. eine einzelne Zulassungsbehörde.
startsAt string
endsAt string
resolvedAt string
TYPServiceStatus
operational* boolean
False, sobald eine Störung oder Wartung aktiv ist. Ein reiner Hinweis lässt die Ampel grün. **Kein Schalter für die Einlieferung.** Das Feld beschreibt die Betriebslage, wie sie hier bekannt ist — es sagt nicht, dass Anträge abgewiesen werden. POWRdrive nimmt sie auch bei `false` an und reicht sie weiter; ob das KBA im Wartungsfenster antwortet, entscheidet das KBA. Wer seine Einlieferung an dieses Feld koppelt, hält sie unnötig an: Über 400 Aufträge sind fehlerfrei abgesetzt worden, während es dauerhaft auf `false` stand. Als Anzeige in Ihrer Oberfläche ist es richtig, als Ampel für den Versand nicht.
announcements* ServiceAnnouncement[]
Aktuell geltende Meldungen.
id* integer
type* enum
Nur `stoerung` und `wartung` setzen `operational` auf false.
stoerung · wartung · hinweis
title* string
summary string
Eine Zeile für die Liste.
text string
Der Fließtext für die Einzelansicht.
slug string
affects string
Was betroffen ist, z. B. eine einzelne Zulassungsbehörde.
startsAt string
endsAt string
resolvedAt string
scheduled* ServiceAnnouncement[]
Angekündigte, noch nicht begonnene Meldungen. **Die festen Wartungsfenster des KBA stehen hier nicht.** Sie gelten jede Woche gleich und sind unter „Wartungsfenster des KBA" in der Doku (/docs/fehler) beschrieben. Hier erscheinen nur Meldungen, die der Betrieb einträgt — etwa eine angekündigte Sonderwartung. Mitten in einem regulären Fenster kann die Antwort also `operational: true` mit leeren Listen sein.
id* integer
type* enum
Nur `stoerung` und `wartung` setzen `operational` auf false.
stoerung · wartung · hinweis
title* string
summary string
Eine Zeile für die Liste.
text string
Der Fließtext für die Einzelansicht.
slug string
affects string
Was betroffen ist, z. B. eine einzelne Zulassungsbehörde.
startsAt string
endsAt string
resolvedAt string
{
  "operational": true,
  "announcements": [],
  "scheduled": [
    {
      "id": 7,
      "type": "wartung",
      "title": "Angekündigte Sonderwartung des KBA",
      "summary": "Das KBA hat eine zusätzliche Wartung außerhalb der festen Fenster angekündigt.",
      "startsAt": "2026-08-20T22:00:00",
      "endsAt": "2026-08-21T04:00:00"
    }
  ]
}
TYPInvoiceStatus

Werte: offen, bezahlt, storniert, ueberfaellig

TYPInvoiceRequest
invoiceNumber* string
Die Rechnungsnummer aus dem Abrechnungssystem. Dient als Schlüssel — ein zweiter Aufruf mit derselben Nummer aktualisiert die Rechnung, statt eine weitere anzulegen.
periodFrom* string (date)
Abrechnungszeitraum
periodTo* string (date)
Abrechnungszeitraum
netAmountCents* integer
Nettobetrag in Cent. Ganze Zahl — Gleitkomma auf Geldbeträgen erzeugt Rundungsfehler, die erst in der Rechnung auffallen.
grossAmountCents* integer
Bruttobetrag in Cent, ganzzahlig.
dueDate string (date)
paidDate string (date)
status InvoiceStatus
pdfUrl string
Adresse des Rechnungs-PDF. Nur `http`/`https`; andere Schemata werden mit 400 abgewiesen. 
{
  "invoiceNumber": "RE-2026-0001",
  "periodFrom": "2026-07-01",
  "periodTo": "2026-07-31",
  "netAmountCents": 100000,
  "grossAmountCents": 119000,
  "dueDate": "2026-08-14",
  "status": "offen"
}
TYPInvoiceResponse
invoice* object
id* integer
number* string
TYPInvoice
id* integer
number* string
periodFrom* string (date)
periodTo* string (date)
netAmountCents* integer
grossAmountCents* integer
dueDate string (date)
paidDate string (date)
status* InvoiceStatus
overdue* boolean
Errechnet aus Fälligkeit und Zahlungsstand — nicht identisch mit `status: ueberfaellig`, der gemeldet werden muss.
pdfUrl string
TYPInvoiceList
invoices* Invoice[]
id* integer
number* string
periodFrom* string (date)
periodTo* string (date)
netAmountCents* integer
grossAmountCents* integer
dueDate string (date)
paidDate string (date)
status* InvoiceStatus
overdue* boolean
Errechnet aus Fälligkeit und Zahlungsstand — nicht identisch mit `status: ueberfaellig`, der gemeldet werden muss.
pdfUrl string
openAmountCents* integer
Summe der offenen Beträge in Cent.
TYPError
error* string
Fehlerbeschreibung einschließlich TraceId.
traceId string
Auch im Header X-Trace-Id enthalten. Bei Rückfragen an den Support anzugeben.
TYPPowerOfAttorneyError
error* string
Fehlerbeschreibung einschließlich TraceId.
traceId string
Auch im Header X-Trace-Id enthalten. Bei Rückfragen an den Support anzugeben.
powerOfAttorneyId integer (int64)
Der Vollmachtsvorgang, um den es geht: der beim Anlegen gescheiterte (`status: fehlgeschlagen`) oder der schon offene unter derselben `externalOrderId`. Fehlt, wenn nichts angelegt wurde.
TYPEuroLicensePlateNumberComponents
usageType enum
Kennzeichenmerkmal — für alle Anträge mit bisherigem Kennzeichen (AB, HA, UG, WG, WZ): EURO (Normalfall), ELECTRIC (Elektrokennzeichen) und HISTORIC (Oldtimerkennzeichen); andere Werte werden mit HTTP 400 abgewiesen.
EURO · ELECTRIC · HISTORIC
city* string
Unterscheidungszeichen, 1–3 Buchstaben (Umlaute zulässig). Kleinbuchstaben werden großgeschrieben; das Muster lässt sie deshalb zu.
middle* string
Erkennungsbuchstaben, 1–2 Buchstaben ohne Umlaute. Kleinbuchstaben werden großgeschrieben.
end* string
Erkennungsnummer, 1–4 Ziffern.
TYPRecycling
type* enum
SCRAPPED_IN_GERMANY — Verwertungsnachweis lag vor (§ 15 Abs. 1/2 FZV). NOT_DISPOSED — außer Betrieb gesetzt, nicht als Abfall entsorgt (§ 15 Abs. 5 FZV). EXPORTED_FOR_DISPOSAL — zur Entsorgung außerhalb EU/EWR verbracht (§ 15 Abs. 4 FZV).
SCRAPPED_IN_GERMANY · NOT_DISPOSED · EXPORTED_FOR_DISPOSAL
dismantlingCompanyNumber string
Betriebsnummer des Demontagebetriebs, höchstens 20 Zeichen (`BetriebsnummerDemontagebetrieb`). Pflicht bei SCRAPPED_IN_GERMANY.
certificateDate string (date)
Ausstellungsdatum des Nachweises. Pflicht bei SCRAPPED_IN_GERMANY.
countryCode string
Zielstaat nach KBA-Staatsschlüssel, ein bis drei Großbuchstaben (`StaatVerwertung`, z. B. D, NL). Pflicht bei EXPORTED_FOR_DISPOSAL.
TYPVehicleRegistrationCertificatePartII
number string
Nummer der ZB II. Kleinbuchstaben werden großgeschrieben.
securityCode* string
Zwölfstellig, **beginnend mit `B`**; danach zehn Stellen (Ziffern und Buchstaben, Kleinbuchstaben zulässig). Die letzte Stelle ist eine Ziffer oder `X` und trägt die Modulo-11-Prüfziffer über den gesamten Code. Format und Prüfziffer sind zwei Prüfungen: Die Form lässt sich gegen `pattern` vorab feststellen, die Prüfziffer rechnet der Dienst vor dem Versand nach und weist sie mit 400 ab.
TYPVehicleDeregistrationCustomization
productType enum
VEHICLE_DEREGISTRATION
licensePlateNumberComponents* EuroLicensePlateNumberComponents
usageType enum
Kennzeichenmerkmal — für alle Anträge mit bisherigem Kennzeichen (AB, HA, UG, WG, WZ): EURO (Normalfall), ELECTRIC (Elektrokennzeichen) und HISTORIC (Oldtimerkennzeichen); andere Werte werden mit HTTP 400 abgewiesen.
EURO · ELECTRIC · HISTORIC
city* string
Unterscheidungszeichen, 1–3 Buchstaben (Umlaute zulässig). Kleinbuchstaben werden großgeschrieben; das Muster lässt sie deshalb zu.
middle* string
Erkennungsbuchstaben, 1–2 Buchstaben ohne Umlaute. Kleinbuchstaben werden großgeschrieben.
end* string
Erkennungsnummer, 1–4 Ziffern.
licensePlateReservationIncluded* boolean
Kennzeichen fahrzeugbezogen reservieren, längstens zwölf Monate. Bei Entsorgung (SCRAPPED_IN_GERMANY, EXPORTED_FOR_DISPOSAL) ausgeschlossen.
vehicleIdentificationNumber* string
Fahrzeugidentifizierungsnummer. Geprüft wird die Regel des KBA: Ziffern und Großbuchstaben, höchstens 25 Stellen (sonst Fehlercode 00306); Kleinbuchstaben werden großgeschrieben. **Auf Länge und Zeichenwahl wird bewusst NICHT strenger geprüft** — seit 1981 hat eine FIN zwar genau 17 Stellen und üblicherweise kein I, O oder Q, aber Oldtimer führen kürzere Nummern, und die amtlichen Beispiele des KBA enthalten vereinzelt doch ein O. Eine falsche FIN fällt deshalb erst beim KBA auf und kostet die Übermittlungsgebühr: bitte gegen den Fahrzeugschein prüfen.
vehicleRegistrationCertificateSecurityCode* string
Sicherheitscode der Zulassungsbescheinigung Teil I, genau sieben Ziffern oder Buchstaben (`SicherheitscodeZB1`). Klein- und Großschreibung gehören hier zum Wert und werden nicht vereinheitlicht.
frontLicensePlateSecurityCode string
Sicherheitscode der vorderen Stempelplakette, genau drei Ziffern oder Buchstaben. Erforderlich bei Fahrzeugen mit zwei Kennzeichenschildern; bei nur einem Schild unzulässig.
rearLicensePlateSecurityCode* string
Sicherheitscode der hinteren Stempelplakette, genau drei Ziffern oder Buchstaben.
vehicleRegistrationCertificateNumber string
Erweiterung — Nummer der ZB I, 18–20 Zeichen, Buchstabe am Anfang. Kleinbuchstaben werden großgeschrieben; das Muster lässt sie deshalb zu.
recycling Recycling
type* enum
SCRAPPED_IN_GERMANY — Verwertungsnachweis lag vor (§ 15 Abs. 1/2 FZV). NOT_DISPOSED — außer Betrieb gesetzt, nicht als Abfall entsorgt (§ 15 Abs. 5 FZV). EXPORTED_FOR_DISPOSAL — zur Entsorgung außerhalb EU/EWR verbracht (§ 15 Abs. 4 FZV).
SCRAPPED_IN_GERMANY · NOT_DISPOSED · EXPORTED_FOR_DISPOSAL
dismantlingCompanyNumber string
Betriebsnummer des Demontagebetriebs, höchstens 20 Zeichen (`BetriebsnummerDemontagebetrieb`). Pflicht bei SCRAPPED_IN_GERMANY.
certificateDate string (date)
Ausstellungsdatum des Nachweises. Pflicht bei SCRAPPED_IN_GERMANY.
countryCode string
Zielstaat nach KBA-Staatsschlüssel, ein bis drei Großbuchstaben (`StaatVerwertung`, z. B. D, NL). Pflicht bei EXPORTED_FOR_DISPOSAL.
vehicleRegistrationCertificatePartII VehicleRegistrationCertificatePartII
number string
Nummer der ZB II. Kleinbuchstaben werden großgeschrieben.
securityCode* string
Zwölfstellig, **beginnend mit `B`**; danach zehn Stellen (Ziffern und Buchstaben, Kleinbuchstaben zulässig). Die letzte Stelle ist eine Ziffer oder `X` und trägt die Modulo-11-Prüfziffer über den gesamten Code. Format und Prüfziffer sind zwei Prüfungen: Die Form lässt sich gegen `pattern` vorab feststellen, die Prüfziffer rechnet der Dienst vor dem Versand nach und weist sie mit 400 ab.
contractPartner ContractPartner
TYPContractPartner
"U871450"
TYPHolderAddress
firstName string
lastName string
companyName string
gender enum
Nur bei natürlichen Personen zulässig.
FEMALE · MALE · DIVERSE · UNSPECIFIED
streetName string
houseNumber string
Laut XKfz-Schema NUR Ziffern, höchstens vier. Ein Zusatz wie "7a" ist dort nicht vorgesehen und gehört in addressSuffix.
zipCode string
cityName string
countryCode string
KBA-Staatsschlüssel. Ohne Angabe D.
addressSuffix string
TYPHolderParty
address* HolderAddress
firstName string
lastName string
companyName string
gender enum
Nur bei natürlichen Personen zulässig.
FEMALE · MALE · DIVERSE · UNSPECIFIED
streetName string
houseNumber string
Laut XKfz-Schema NUR Ziffern, höchstens vier. Ein Zusatz wie "7a" ist dort nicht vorgesehen und gehört in addressSuffix.
zipCode string
cityName string
countryCode string
KBA-Staatsschlüssel. Ohne Angabe D.
addressSuffix string
partyType enum
Die Art des Beteiligten. **Freiwillig und zusätzlich** — ohne Angabe gilt wie bisher der Name: `companyName` heisst juristische Person, sonst natürliche Person. - `NATURAL_PERSON`, `LEGAL_PERSON` — die beiden bisherigen Arten, ausdrücklich benannt. - `AUTHORITY` — eine Behörde. Geht im XML als juristische Person hinaus; das Schema kennt keine eigene Art. - `SOLE_TRADER` — Einzelunternehmer. MIT `companyName` juristische Person, OHNE natürliche Person (amtliche Dokumentation zur Vollmacht: „Status als juristische Person wird nur dann zuerkannt, wenn ‚Name des Unternehmens' ausgefüllt ist"). Der Berufs-/Wirtschaftszweigschlüssel ist in beiden Fällen anzugeben — `888` gilt nur für Privatpersonen. - `ASSOCIATION` — eine nicht rechtsfähige Vereinigung, etwa eine GbR ohne Registereintrag oder eine Erbengemeinschaft. Geht als eigene Struktur (`NameVereinigung`) ans KBA, mit optionalem Vertreter. Ein eingetragener Verein ist dagegen eine juristische Person. Erweiterung gegenüber kennzeichen.dev.
NATURAL_PERSON · LEGAL_PERSON · AUTHORITY · SOLE_TRADER · ASSOCIATION
associationRepresentative object
Der benannte Vertreter einer Vereinigung — nur bei `partyType: ASSOCIATION` und dort freiwillig (seit XKfz 6.0 optional). In `POST /powerOfAttorneys` gibt es ihn nicht: Für eine Vereinigung lässt sich über uns keine Vollmacht unterschreiben (siehe `principal`).
firstName string
lastName string
companyName string
dateOfBirth string (date)
Streng als JJJJ-MM-TT. Nur bei natürlichen Personen. Zulässiger Bereich 1880–2099.
placeOfBirth string
Nur bei natürlichen Personen.
occupationKey string
Berufs- bzw. Wirtschaftszweigschlüssel, drei Stellen. Beim Halter einer Zulassung (UG, WG, WZ, NZ, TZ) Pflicht (KBA-Wissensartikel „Angabe des Berufsschlüssels bzw. Wirtschaftszweigs"). Firmen und juristische Personen nehmen den Schlüssel aus dem KBA-Verzeichnis SV 5, etwa `G01` für den Handel mit Kraftfahrzeugen; fehlt er, `400`. Privatpersonen ohne Angabe erhalten "888"; Freiberufler und Einzelunternehmer geben ihren Schlüssel an. Geprüft wird nur die Form. Bei der Halteränderung, beim Bevollmächtigten und beim Lieferungsempfänger optional.
TYPAssociationRepresentative
firstName string
lastName string
companyName string
TYPPowerOfAttorneyRequest
principal* object
Der Vollmachtgeber — der künftige Halter. Ein `companyName` ohne `lastName` bedeutet eine juristische Person; das amtliche Formular hat dafür eine eigene Vorlage. `partyType: ASSOCIATION` ergibt hier `400`: Der Vertrauensdienst stellt keine Vereinigung fest, der Antrag über `processId` führte deshalb zwangsläufig einen anderen Halter als die unterschriebene Vollmacht. Eine Vereinigung bringt ihre gesiegelte Vollmacht als `powerOfAttorney.documentBase64` mit. Mit `partyType` wird daraus die passende Variante des Formulars: `LEGAL_PERSON`, `AUTHORITY`, `SOLE_TRADER` (mit Unternehmensnamen) oder `ASSOCIATION`. Ein Einzelunternehmer ohne Unternehmensnamen bekommt die Vorlage für natürliche Personen.
address* HolderAddress
firstName string
lastName string
companyName string
gender enum
Nur bei natürlichen Personen zulässig.
FEMALE · MALE · DIVERSE · UNSPECIFIED
streetName string
houseNumber string
Laut XKfz-Schema NUR Ziffern, höchstens vier. Ein Zusatz wie "7a" ist dort nicht vorgesehen und gehört in addressSuffix.
zipCode string
cityName string
countryCode string
KBA-Staatsschlüssel. Ohne Angabe D.
addressSuffix string
partyType enum
Die Art des Beteiligten. **Freiwillig und zusätzlich** — ohne Angabe gilt wie bisher der Name: `companyName` heisst juristische Person, sonst natürliche Person. - `NATURAL_PERSON`, `LEGAL_PERSON` — die beiden bisherigen Arten, ausdrücklich benannt. - `AUTHORITY` — eine Behörde. Geht im XML als juristische Person hinaus; das Schema kennt keine eigene Art. - `SOLE_TRADER` — Einzelunternehmer. MIT `companyName` juristische Person, OHNE natürliche Person (amtliche Dokumentation zur Vollmacht: „Status als juristische Person wird nur dann zuerkannt, wenn ‚Name des Unternehmens' ausgefüllt ist"). Der Berufs-/Wirtschaftszweigschlüssel ist in beiden Fällen anzugeben — `888` gilt nur für Privatpersonen. - `ASSOCIATION` — eine nicht rechtsfähige Vereinigung, etwa eine GbR ohne Registereintrag oder eine Erbengemeinschaft. Geht als eigene Struktur (`NameVereinigung`) ans KBA, mit optionalem Vertreter. Ein eingetragener Verein ist dagegen eine juristische Person. Erweiterung gegenüber kennzeichen.dev.
NATURAL_PERSON · LEGAL_PERSON · AUTHORITY · SOLE_TRADER · ASSOCIATION
associationRepresentative object
Der benannte Vertreter einer Vereinigung — nur bei `partyType: ASSOCIATION` und dort freiwillig (seit XKfz 6.0 optional). In `POST /powerOfAttorneys` gibt es ihn nicht: Für eine Vereinigung lässt sich über uns keine Vollmacht unterschreiben (siehe `principal`).
firstName string
lastName string
companyName string
dateOfBirth string (date)
Streng als JJJJ-MM-TT. Nur bei natürlichen Personen. Zulässiger Bereich 1880–2099.
placeOfBirth string
Nur bei natürlichen Personen.
occupationKey string
Berufs- bzw. Wirtschaftszweigschlüssel, drei Stellen. Beim Halter einer Zulassung (UG, WG, WZ, NZ, TZ) Pflicht (KBA-Wissensartikel „Angabe des Berufsschlüssels bzw. Wirtschaftszweigs"). Firmen und juristische Personen nehmen den Schlüssel aus dem KBA-Verzeichnis SV 5, etwa `G01` für den Handel mit Kraftfahrzeugen; fehlt er, `400`. Privatpersonen ohne Angabe erhalten "888"; Freiberufler und Einzelunternehmer geben ihren Schlüssel an. Geprüft wird nur die Form. Bei der Halteränderung, beim Bevollmächtigten und beim Lieferungsempfänger optional.
representative* object
Der Bevollmächtigte — Sie.
address* HolderAddress
firstName string
lastName string
companyName string
gender enum
Nur bei natürlichen Personen zulässig.
FEMALE · MALE · DIVERSE · UNSPECIFIED
streetName string
houseNumber string
Laut XKfz-Schema NUR Ziffern, höchstens vier. Ein Zusatz wie "7a" ist dort nicht vorgesehen und gehört in addressSuffix.
zipCode string
cityName string
countryCode string
KBA-Staatsschlüssel. Ohne Angabe D.
addressSuffix string
partyType enum
Die Art des Beteiligten. **Freiwillig und zusätzlich** — ohne Angabe gilt wie bisher der Name: `companyName` heisst juristische Person, sonst natürliche Person. - `NATURAL_PERSON`, `LEGAL_PERSON` — die beiden bisherigen Arten, ausdrücklich benannt. - `AUTHORITY` — eine Behörde. Geht im XML als juristische Person hinaus; das Schema kennt keine eigene Art. - `SOLE_TRADER` — Einzelunternehmer. MIT `companyName` juristische Person, OHNE natürliche Person (amtliche Dokumentation zur Vollmacht: „Status als juristische Person wird nur dann zuerkannt, wenn ‚Name des Unternehmens' ausgefüllt ist"). Der Berufs-/Wirtschaftszweigschlüssel ist in beiden Fällen anzugeben — `888` gilt nur für Privatpersonen. - `ASSOCIATION` — eine nicht rechtsfähige Vereinigung, etwa eine GbR ohne Registereintrag oder eine Erbengemeinschaft. Geht als eigene Struktur (`NameVereinigung`) ans KBA, mit optionalem Vertreter. Ein eingetragener Verein ist dagegen eine juristische Person. Erweiterung gegenüber kennzeichen.dev.
NATURAL_PERSON · LEGAL_PERSON · AUTHORITY · SOLE_TRADER · ASSOCIATION
associationRepresentative object
Der benannte Vertreter einer Vereinigung — nur bei `partyType: ASSOCIATION` und dort freiwillig (seit XKfz 6.0 optional). In `POST /powerOfAttorneys` gibt es ihn nicht: Für eine Vereinigung lässt sich über uns keine Vollmacht unterschreiben (siehe `principal`).
firstName string
lastName string
companyName string
dateOfBirth string (date)
Streng als JJJJ-MM-TT. Nur bei natürlichen Personen. Zulässiger Bereich 1880–2099.
placeOfBirth string
Nur bei natürlichen Personen.
occupationKey string
Berufs- bzw. Wirtschaftszweigschlüssel, drei Stellen. Beim Halter einer Zulassung (UG, WG, WZ, NZ, TZ) Pflicht (KBA-Wissensartikel „Angabe des Berufsschlüssels bzw. Wirtschaftszweigs"). Firmen und juristische Personen nehmen den Schlüssel aus dem KBA-Verzeichnis SV 5, etwa `G01` für den Handel mit Kraftfahrzeugen; fehlt er, `400`. Privatpersonen ohne Angabe erhalten "888"; Freiberufler und Einzelunternehmer geben ihren Schlüssel an. Geprüft wird nur die Form. Bei der Halteränderung, beim Bevollmächtigten und beim Lieferungsempfänger optional.
email* string (email)
Die Adresse des Vollmachtgebers. Dorthin geht die Einladung zur Unterschrift, wenn auf der Instanz ein Mailversand eingerichtet ist.
vehicles* object[]
Höchstens zehn — so viele fasst die Fahrzeugtabelle des amtlichen Formulars. Jede FIN des späteren Antrags muss hier stehen (Fehlercode 00301).
vehicleIdentificationNumber* string
Wie im Antrag: Ziffern und Buchstaben, höchstens 25 Stellen (`typ-Fahrzeugidentifizierungsnummer`). Sonderzeichen, Steuerzeichen oder Überlänge ⇒ **400** mit Feldnamen und Index.
certificatePartIINumber string
Angenommen, aber nicht ins Formular übernommen — es führt genau eine Identifikation, die FIN (sonst 00306).
manufacturerKey string
Wie certificatePartIINumber.
typeKey string
Wie certificatePartIINumber.
customerNumber string
Großkunden-ID der Zollverwaltung des Vollmachtgebers, sofern vorhanden (ersetzt das SEPA-Mandat); nur Vorlage für juristische Personen. Form drei Ziffern, Großbuchstabe, vier Ziffern — derselbe Wert wie taxDetails.taxLargeCustomerId im späteren Antrag. Nicht die KBA-Kennung und nicht customization.customerNumber (Referenz 27).
certificatePartIRecipient enum
Empfänger der ZB I samt Plaketten. Ohne Angabe HOLDER — so stellt das KBA ohne Lieferinformation zu. Die deliveries des späteren Antrags müssen dazu passen, sonst 400.
HOLDER · REPRESENTATIVE · THIRD_PARTY
certificatePartIIRecipient enum
Empfänger der ZB II; wie certificatePartIRecipient.
HOLDER · REPRESENTATIVE · THIRD_PARTY
pickup boolean
Unterlagen werden abgeholt statt versandt — vom Bevollmächtigten, mit deliveryRecipient von diesem Dritten. Abholung durch einen Dritten (pickup zusammen mit deliveryRecipient) geht nur bei GENAU EINEM Fahrzeug in vehicles: Die Fahrzeugtabelle des amtlichen Formulars trägt je Zeile nur den Buchstaben und führt keinen Abholer. Mit mehreren Fahrzeugen 400 — dann je Fahrzeug ein eigener Vorgang. Holt der Bevollmächtigte selbst ab, bleiben zehn Fahrzeuge möglich.
deliveryRecipient object
Der Dritte bei THIRD_PARTY (Pflicht) oder der abholende Dritte bei pickup. Name und Anschrift müssen zu deliveryRecipient im Antrag passen.
address* HolderAddress
firstName string
lastName string
companyName string
gender enum
Nur bei natürlichen Personen zulässig.
FEMALE · MALE · DIVERSE · UNSPECIFIED
streetName string
houseNumber string
Laut XKfz-Schema NUR Ziffern, höchstens vier. Ein Zusatz wie "7a" ist dort nicht vorgesehen und gehört in addressSuffix.
zipCode string
cityName string
countryCode string
KBA-Staatsschlüssel. Ohne Angabe D.
addressSuffix string
partyType enum
Die Art des Beteiligten. **Freiwillig und zusätzlich** — ohne Angabe gilt wie bisher der Name: `companyName` heisst juristische Person, sonst natürliche Person. - `NATURAL_PERSON`, `LEGAL_PERSON` — die beiden bisherigen Arten, ausdrücklich benannt. - `AUTHORITY` — eine Behörde. Geht im XML als juristische Person hinaus; das Schema kennt keine eigene Art. - `SOLE_TRADER` — Einzelunternehmer. MIT `companyName` juristische Person, OHNE natürliche Person (amtliche Dokumentation zur Vollmacht: „Status als juristische Person wird nur dann zuerkannt, wenn ‚Name des Unternehmens' ausgefüllt ist"). Der Berufs-/Wirtschaftszweigschlüssel ist in beiden Fällen anzugeben — `888` gilt nur für Privatpersonen. - `ASSOCIATION` — eine nicht rechtsfähige Vereinigung, etwa eine GbR ohne Registereintrag oder eine Erbengemeinschaft. Geht als eigene Struktur (`NameVereinigung`) ans KBA, mit optionalem Vertreter. Ein eingetragener Verein ist dagegen eine juristische Person. Erweiterung gegenüber kennzeichen.dev.
NATURAL_PERSON · LEGAL_PERSON · AUTHORITY · SOLE_TRADER · ASSOCIATION
associationRepresentative object
Der benannte Vertreter einer Vereinigung — nur bei `partyType: ASSOCIATION` und dort freiwillig (seit XKfz 6.0 optional). In `POST /powerOfAttorneys` gibt es ihn nicht: Für eine Vereinigung lässt sich über uns keine Vollmacht unterschreiben (siehe `principal`).
firstName string
lastName string
companyName string
dateOfBirth string (date)
Streng als JJJJ-MM-TT. Nur bei natürlichen Personen. Zulässiger Bereich 1880–2099.
placeOfBirth string
Nur bei natürlichen Personen.
occupationKey string
Berufs- bzw. Wirtschaftszweigschlüssel, drei Stellen. Beim Halter einer Zulassung (UG, WG, WZ, NZ, TZ) Pflicht (KBA-Wissensartikel „Angabe des Berufsschlüssels bzw. Wirtschaftszweigs"). Firmen und juristische Personen nehmen den Schlüssel aus dem KBA-Verzeichnis SV 5, etwa `G01` für den Handel mit Kraftfahrzeugen; fehlt er, `400`. Privatpersonen ohne Angabe erhalten "888"; Freiberufler und Einzelunternehmer geben ihren Schlüssel an. Geprüft wird nur die Form. Bei der Halteränderung, beim Bevollmächtigten und beim Lieferungsempfänger optional.
extendedDataProvision boolean
Erlaubt den Empfang der vollständigen ZB-Daten über den Rückkanal. Ohne dieses Kreuz gibt es keinen ZB-Datenrückkanal: Ein späterer Antrag mit requestRegistrationData: true wird dann mit 400 abgewiesen, bevor etwas an das KBA geht (§ 39 Abs. 3 Satz 2 FZV — die Übermittlung braucht die Einwilligung des Halters).
externalOrderId string
bankAccount object
Konto für die Kfz-Steuer — dieselbe Form wie `bankAccount` im Zulassungsantrag, dazu `bic`. Wir befüllen daraus das SEPA-Lastschriftmandat (Vorlage der Generalzolldirektion) und lassen es im selben Nect-Vorgang wie die Vollmacht unterschreiben. Der Antrag mit `processId` hängt es als Dokumentart 44 an, wenn er `bankAccount` mit derselben IBAN und demselben Kontoinhaber führt; eine abweichende Angabe ergibt dort `400`, ein mitgeschicktes `sepaMandateBase64` hat Vorrang. `400`: bei einer juristischen Person (Business Sign — dort `sepaMandateBase64` oder `taxDetails.taxLargeCustomerId` im Antrag), wenn der Kontoinhaber nicht zum Vollmachtgeber passt (jeder Nachname, mindestens ein Vorname, kein weiteres Wort; Groß-/Kleinschreibung und Komma egal), bei ungültiger IBAN oder BIC, `usage` außer `Steuer` und `directDebitMandateGranted: false`. `503`, solange die Vorlage fehlt.
iban* string
Leerzeichen werden entfernt.
bic string
accountHolder* string
usage enum
Steuer
directDebitMandateGranted enum
true
TYPPowerOfAttorneyProcess
id integer (int64)
Diese Nummer gehört in `powerOfAttorney.processId`.
status enum
offen · signiert · abgelehnt · verfallen · fehlgeschlagen
provider string
signatureUrl string
Der Link, unter dem der Vollmachtgeber unterschreibt. Geben Sie ihn selbst weiter: Per Mail verschickt ihn die Schnittstelle nur, wenn auf der Instanz ein Mailversand eingerichtet ist, und Nect lädt nicht selbst ein.
validUntil string
Frist, bis zu der über `signatureUrl` unterschrieben werden kann; verstreicht sie ohne Unterschrift, wird der Vorgang `verfallen`. `null`, wenn die Instanz keine Frist gesetzt hat — bei Business Sign immer. Nicht die Laufzeit der Vollmacht.
externalOrderId string
vehicleIdentificationNumber string
Die FIN des ersten Eintrags in `vehicles`. Die Vollmacht gilt trotzdem für alle angegebenen Fahrzeuge.
createdAt string
updatedAt string
readyForApplication boolean
Ob der Vorgang für einen Zulassungsantrag taugt. `status: signiert` allein genügt NICHT. Ein Vorgang kann unterschrieben und trotzdem unbrauchbar sein: Bei Identifizierung per Reisepass liefert der Vertrauensdienst keine Anschrift, weil ein Pass keine führt. Seltener, aber möglich: das signierte Dokument oder die Feldbelegung fehlt — dann steht der Grund in `blockingIssues`. Nach dem BMDV-Schreiben vom 25.04.2024 darf sie dann nicht aus Ihren Angaben ergänzt werden — dort ist zusätzlich eine Meldebescheinigung zu prüfen. Prüfen Sie dieses Feld, bevor Sie sich im Zulassungsantrag auf `processId` berufen. Andernfalls antwortet der Antrag mit 409, und der Kunde hat die Identifizierung bereits durchlaufen. **Was es NICHT abdeckt:** den inhaltlichen Abgleich der unterschriebenen Vollmacht gegen die festgestellte Identität. Weicht etwas ab — der Kunde hat sich unter einem anderen Namen ausgewiesen, oder das Formular führt einen Geburtsort, den der Ausweis nicht hergibt —, meldet das erst der Antrag, und zwar mit **400** samt Angabe des betroffenen Feldes. `readyForApplication` sagt aus, dass der Vorgang **vollständig** ist, nicht dass er **stimmig** ist.
missingHolderFields string[]
Welche Pflichtfelder der Anschrift der Vertrauensdienst nicht festgestellt hat. Nur vorhanden, wenn etwas fehlt. Aussagekräftig erst bei `status: signiert` — bei einem offenen Vorgang hat der Dienst noch nichts festgestellt, und die Liste kann alle Felder nennen, bei einer Firma auch Vorname und Nachname. Genannt werden ausschliesslich FELDNAMEN, keine Werte: Die festgestellten Personendaten geben wir nicht heraus. Der Zulassungsantrag zieht den Halter selbst aus dem Vorgang.
blockingIssues string[]
Was dem unterschriebenen Vorgang zum Antrag sonst noch fehlt — im Unterschied zu `missingHolderFields` keine Feldnamen, sondern Zustände des Vorgangs selbst: ein fehlendes signiertes Dokument, eine fehlende oder unlesbare Feldbelegung. Nur vorhanden, wenn `status: signiert` ist und etwas fehlt. Beides sind Fälle für den Support — ein erneutes Abrufen des Standes hilft beim ersten, beim zweiten muss der Vorgang neu angestossen werden.
note string
Ein Hinweis zum Vorgang — etwa dass die Einladung nicht versendet werden konnte, oder womit der Vertrauensdienst eine Ablehnung begründet hat. Der Vorgang steht trotzdem.
holderDataProvenance object
Der Herkunftsnachweis der Halterdaten: welcher Vertrauensdienst sie wann geliefert hat, und der Fingerabdruck über die gelieferten Felder. Nur bei `status: signiert` und nur, wenn der Anbieter sich zu erkennen gegeben hat — Vorgänge von vor dem 12.09.2026 führen keinen. `unchanged` und `deviatingFields` gibt es erst am Zulassungsantrag, der sich auf den Vorgang beruft.
provider enum
Der Dienst, der die Halterdaten geliefert hat.
nect-sign · nect-business-sign · yousign
providerProcessId string
Kennung des Vorgangs beim Anbieter — darüber kann er ihn im Prüfverfahren bestätigen.
verifiedAt string (date-time)
Zeitpunkt laut Anbieter (die Unterschrift); nennt er keinen, der Eingang des Ergebnisses bei uns.
identitySource string
Was der Anbieter zur Quelle meldet — bei Business Sign `Handelsregister`. Nur vorhanden, wenn er etwas nennt; Nect Sign nennt keine Ausweisart.
fingerprint string
powerOfAttorneyProcessId integer (int64)
Nur an der Vorgangsauskunft — der Vollmachtsvorgang, auf den sich der Antrag beruft.
unchanged boolean
Nur an der Vorgangsauskunft. Ob die Halterdaten des Antrags den gelieferten entsprechen. Verglichen wird, was in die XKfz-Nachricht geht; zulässig sind allein das Entfernen führender und nachgestellter Leerzeichen, die Umwandlung des Datumsformats und die Umschlüsselung des Staats von ISO „DE" auf KBA „D".
deviatingFields string[]
Nur an der Vorgangsauskunft. Leer, wenn `unchanged` — siehe oben.
checkedAt string (date-time)
Nur an der Vorgangsauskunft — Zeitpunkt des Abgleichs.
TYPHolderDataProvenance
provider enum
Der Dienst, der die Halterdaten geliefert hat.
nect-sign · nect-business-sign · yousign
providerProcessId string
Kennung des Vorgangs beim Anbieter — darüber kann er ihn im Prüfverfahren bestätigen.
verifiedAt string (date-time)
Zeitpunkt laut Anbieter (die Unterschrift); nennt er keinen, der Eingang des Ergebnisses bei uns.
identitySource string
Was der Anbieter zur Quelle meldet — bei Business Sign `Handelsregister`. Nur vorhanden, wenn er etwas nennt; Nect Sign nennt keine Ausweisart.
fingerprint string
powerOfAttorneyProcessId integer (int64)
Nur an der Vorgangsauskunft — der Vollmachtsvorgang, auf den sich der Antrag beruft.
unchanged boolean
Nur an der Vorgangsauskunft. Ob die Halterdaten des Antrags den gelieferten entsprechen. Verglichen wird, was in die XKfz-Nachricht geht; zulässig sind allein das Entfernen führender und nachgestellter Leerzeichen, die Umwandlung des Datumsformats und die Umschlüsselung des Staats von ISO „DE" auf KBA „D".
deviatingFields string[]
Nur an der Vorgangsauskunft. Leer, wenn `unchanged` — siehe oben.
checkedAt string (date-time)
Nur an der Vorgangsauskunft — Zeitpunkt des Abgleichs.
TYPPowerOfAttorney
representative HolderParty
address* HolderAddress
firstName string
lastName string
companyName string
gender enum
Nur bei natürlichen Personen zulässig.
FEMALE · MALE · DIVERSE · UNSPECIFIED
streetName string
houseNumber string
Laut XKfz-Schema NUR Ziffern, höchstens vier. Ein Zusatz wie "7a" ist dort nicht vorgesehen und gehört in addressSuffix.
zipCode string
cityName string
countryCode string
KBA-Staatsschlüssel. Ohne Angabe D.
addressSuffix string
partyType enum
Die Art des Beteiligten. **Freiwillig und zusätzlich** — ohne Angabe gilt wie bisher der Name: `companyName` heisst juristische Person, sonst natürliche Person. - `NATURAL_PERSON`, `LEGAL_PERSON` — die beiden bisherigen Arten, ausdrücklich benannt. - `AUTHORITY` — eine Behörde. Geht im XML als juristische Person hinaus; das Schema kennt keine eigene Art. - `SOLE_TRADER` — Einzelunternehmer. MIT `companyName` juristische Person, OHNE natürliche Person (amtliche Dokumentation zur Vollmacht: „Status als juristische Person wird nur dann zuerkannt, wenn ‚Name des Unternehmens' ausgefüllt ist"). Der Berufs-/Wirtschaftszweigschlüssel ist in beiden Fällen anzugeben — `888` gilt nur für Privatpersonen. - `ASSOCIATION` — eine nicht rechtsfähige Vereinigung, etwa eine GbR ohne Registereintrag oder eine Erbengemeinschaft. Geht als eigene Struktur (`NameVereinigung`) ans KBA, mit optionalem Vertreter. Ein eingetragener Verein ist dagegen eine juristische Person. Erweiterung gegenüber kennzeichen.dev.
NATURAL_PERSON · LEGAL_PERSON · AUTHORITY · SOLE_TRADER · ASSOCIATION
associationRepresentative object
Der benannte Vertreter einer Vereinigung — nur bei `partyType: ASSOCIATION` und dort freiwillig (seit XKfz 6.0 optional). In `POST /powerOfAttorneys` gibt es ihn nicht: Für eine Vereinigung lässt sich über uns keine Vollmacht unterschreiben (siehe `principal`).
firstName string
lastName string
companyName string
dateOfBirth string (date)
Streng als JJJJ-MM-TT. Nur bei natürlichen Personen. Zulässiger Bereich 1880–2099.
placeOfBirth string
Nur bei natürlichen Personen.
occupationKey string
Berufs- bzw. Wirtschaftszweigschlüssel, drei Stellen. Beim Halter einer Zulassung (UG, WG, WZ, NZ, TZ) Pflicht (KBA-Wissensartikel „Angabe des Berufsschlüssels bzw. Wirtschaftszweigs"). Firmen und juristische Personen nehmen den Schlüssel aus dem KBA-Verzeichnis SV 5, etwa `G01` für den Handel mit Kraftfahrzeugen; fehlt er, `400`. Privatpersonen ohne Angabe erhalten "888"; Freiberufler und Einzelunternehmer geben ihren Schlüssel an. Geprüft wird nur die Form. Bei der Halteränderung, beim Bevollmächtigten und beim Lieferungsempfänger optional.
documentBase64 string (byte)
Das unterschriebene Vollmacht-PDF, Base64-kodiert — selbst mitgebracht.
processId integer
Nummer eines Vollmachtsvorgangs, der über diesen Dienst unterschrieben wurde (siehe Self-Service-Bereich, „Vollmachtsvorgänge"). Wir hängen das signierte Dokument dann selbst an und gleichen die Vollmacht vorab gegen die Antragsdaten ab. Ist der Vorgang unbekannt oder gehört er einem anderen Mandanten: 404. Ist er noch nicht unterschrieben: 409, mit seinem Stand in der Meldung — und zwar vor jeder Feldprüfung: Feldfehler und der Abgleich mit der Vollmacht melden sich erst nach der Unterschrift. Ein 400 danach verbraucht den Vorgang nicht; der korrigierte Antrag darf dieselbe processId nennen.
TYPVehicleHolderChangeCustomization
vehicleIdentificationNumber* string
licensePlateNumberComponents* EuroLicensePlateNumberComponents
usageType enum
Kennzeichenmerkmal — für alle Anträge mit bisherigem Kennzeichen (AB, HA, UG, WG, WZ): EURO (Normalfall), ELECTRIC (Elektrokennzeichen) und HISTORIC (Oldtimerkennzeichen); andere Werte werden mit HTTP 400 abgewiesen.
EURO · ELECTRIC · HISTORIC
city* string
Unterscheidungszeichen, 1–3 Buchstaben (Umlaute zulässig). Kleinbuchstaben werden großgeschrieben; das Muster lässt sie deshalb zu.
middle* string
Erkennungsbuchstaben, 1–2 Buchstaben ohne Umlaute. Kleinbuchstaben werden großgeschrieben.
end* string
Erkennungsnummer, 1–4 Ziffern.
vehicleRegistrationCertificateSecurityCode* string
Siebenstelliger Sicherheitscode der ZB I — der Nachweis der Berechtigung. Die Codes der Stempelplaketten werden bei der Halteränderung NICHT geprüft.
vehicleRegistrationCertificateNumber string
Nummer der ZB I, 18–20 Zeichen, Buchstabe am Anfang. Kleinbuchstaben werden großgeschrieben — abgetippt wie gedruckt ist sie gültig.
vehicleRegistrationCertificateImprintNumber string
Druckstücknummer der ZB I, falls vorhanden. Acht Zeichen: Großbuchstabe, sechs Ziffern oder Großbuchstaben, zuletzt Ziffer oder X (Schema XKfz 6.0, Type.Druckstuecknummer).
vehicleRegistrationCertificatePartIINumber string
Wird nur auf ausdrückliche Angabe gesendet. Die Konventionstabelle des KBA führt die Vorgangskomponente bei der Halteränderung als unzulässig, die amtlichen Beispiele senden sie dennoch — beim KBA in Klärung. Kleinbuchstaben werden großgeschrieben.
deliveryToHolder boolean
Zustellung der neuen ZB I: true an den Halter, false an den Bevollmächtigten, sofern der Antrag einen nennt (sonst ebenfalls an den Halter). Ohne Angabe geht keine Lieferinformation an das KBA; es stellt dann dem Halter zu, und der Abgleich mit einer Vollmacht wertet das wie true. `deliveries` kennt die Halteränderung nicht; ein mitgeschicktes Feld wird ohne Meldung übergangen.
customerNumber string
contractPartner ContractPartner
TYPVehicleHolderChangeRequest
customization* VehicleHolderChangeCustomization
vehicleIdentificationNumber* string
licensePlateNumberComponents* EuroLicensePlateNumberComponents
usageType enum
Kennzeichenmerkmal — für alle Anträge mit bisherigem Kennzeichen (AB, HA, UG, WG, WZ): EURO (Normalfall), ELECTRIC (Elektrokennzeichen) und HISTORIC (Oldtimerkennzeichen); andere Werte werden mit HTTP 400 abgewiesen.
EURO · ELECTRIC · HISTORIC
city* string
Unterscheidungszeichen, 1–3 Buchstaben (Umlaute zulässig). Kleinbuchstaben werden großgeschrieben; das Muster lässt sie deshalb zu.
middle* string
Erkennungsbuchstaben, 1–2 Buchstaben ohne Umlaute. Kleinbuchstaben werden großgeschrieben.
end* string
Erkennungsnummer, 1–4 Ziffern.
vehicleRegistrationCertificateSecurityCode* string
Siebenstelliger Sicherheitscode der ZB I — der Nachweis der Berechtigung. Die Codes der Stempelplaketten werden bei der Halteränderung NICHT geprüft.
vehicleRegistrationCertificateNumber string
Nummer der ZB I, 18–20 Zeichen, Buchstabe am Anfang. Kleinbuchstaben werden großgeschrieben — abgetippt wie gedruckt ist sie gültig.
vehicleRegistrationCertificateImprintNumber string
Druckstücknummer der ZB I, falls vorhanden. Acht Zeichen: Großbuchstabe, sechs Ziffern oder Großbuchstaben, zuletzt Ziffer oder X (Schema XKfz 6.0, Type.Druckstuecknummer).
vehicleRegistrationCertificatePartIINumber string
Wird nur auf ausdrückliche Angabe gesendet. Die Konventionstabelle des KBA führt die Vorgangskomponente bei der Halteränderung als unzulässig, die amtlichen Beispiele senden sie dennoch — beim KBA in Klärung. Kleinbuchstaben werden großgeschrieben.
deliveryToHolder boolean
Zustellung der neuen ZB I: true an den Halter, false an den Bevollmächtigten, sofern der Antrag einen nennt (sonst ebenfalls an den Halter). Ohne Angabe geht keine Lieferinformation an das KBA; es stellt dann dem Halter zu, und der Abgleich mit einer Vollmacht wertet das wie true. `deliveries` kennt die Halteränderung nicht; ein mitgeschicktes Feld wird ohne Meldung übergangen.
customerNumber string
contractPartner ContractPartner
vehicleHolder object
Der Halter mit seiner NEUEN Anschrift. Pflicht, außer bei `powerOfAttorney.processId`: Dann stammen die Halterdaten vom Vertrauensdienst, und ohne Angabe gilt, was er festgestellt hat. Mit Angabe muss die Anschrift der vom Vertrauensdienst festgestellten entsprechen, sonst 400 — die neue Anschrift ist der Antrag. Ein mitgeschickter `occupationKey` muss zum in der Vollmacht unterschriebenen Wirtschaftszweig passen, sonst ebenfalls 400.
address* HolderAddress
firstName string
lastName string
companyName string
gender enum
Nur bei natürlichen Personen zulässig.
FEMALE · MALE · DIVERSE · UNSPECIFIED
streetName string
houseNumber string
Laut XKfz-Schema NUR Ziffern, höchstens vier. Ein Zusatz wie "7a" ist dort nicht vorgesehen und gehört in addressSuffix.
zipCode string
cityName string
countryCode string
KBA-Staatsschlüssel. Ohne Angabe D.
addressSuffix string
partyType enum
Die Art des Beteiligten. **Freiwillig und zusätzlich** — ohne Angabe gilt wie bisher der Name: `companyName` heisst juristische Person, sonst natürliche Person. - `NATURAL_PERSON`, `LEGAL_PERSON` — die beiden bisherigen Arten, ausdrücklich benannt. - `AUTHORITY` — eine Behörde. Geht im XML als juristische Person hinaus; das Schema kennt keine eigene Art. - `SOLE_TRADER` — Einzelunternehmer. MIT `companyName` juristische Person, OHNE natürliche Person (amtliche Dokumentation zur Vollmacht: „Status als juristische Person wird nur dann zuerkannt, wenn ‚Name des Unternehmens' ausgefüllt ist"). Der Berufs-/Wirtschaftszweigschlüssel ist in beiden Fällen anzugeben — `888` gilt nur für Privatpersonen. - `ASSOCIATION` — eine nicht rechtsfähige Vereinigung, etwa eine GbR ohne Registereintrag oder eine Erbengemeinschaft. Geht als eigene Struktur (`NameVereinigung`) ans KBA, mit optionalem Vertreter. Ein eingetragener Verein ist dagegen eine juristische Person. Erweiterung gegenüber kennzeichen.dev.
NATURAL_PERSON · LEGAL_PERSON · AUTHORITY · SOLE_TRADER · ASSOCIATION
associationRepresentative object
Der benannte Vertreter einer Vereinigung — nur bei `partyType: ASSOCIATION` und dort freiwillig (seit XKfz 6.0 optional). In `POST /powerOfAttorneys` gibt es ihn nicht: Für eine Vereinigung lässt sich über uns keine Vollmacht unterschreiben (siehe `principal`).
firstName string
lastName string
companyName string
dateOfBirth string (date)
Streng als JJJJ-MM-TT. Nur bei natürlichen Personen. Zulässiger Bereich 1880–2099.
placeOfBirth string
Nur bei natürlichen Personen.
occupationKey string
Berufs- bzw. Wirtschaftszweigschlüssel, drei Stellen. Beim Halter einer Zulassung (UG, WG, WZ, NZ, TZ) Pflicht (KBA-Wissensartikel „Angabe des Berufsschlüssels bzw. Wirtschaftszweigs"). Firmen und juristische Personen nehmen den Schlüssel aus dem KBA-Verzeichnis SV 5, etwa `G01` für den Handel mit Kraftfahrzeugen; fehlt er, `400`. Privatpersonen ohne Angabe erhalten "888"; Freiberufler und Einzelunternehmer geben ihren Schlüssel an. Geprüft wird nur die Form. Bei der Halteränderung, beim Bevollmächtigten und beim Lieferungsempfänger optional.
powerOfAttorney PowerOfAttorney
representative HolderParty
address* HolderAddress
firstName string
lastName string
companyName string
gender enum
Nur bei natürlichen Personen zulässig.
FEMALE · MALE · DIVERSE · UNSPECIFIED
streetName string
houseNumber string
Laut XKfz-Schema NUR Ziffern, höchstens vier. Ein Zusatz wie "7a" ist dort nicht vorgesehen und gehört in addressSuffix.
zipCode string
cityName string
countryCode string
KBA-Staatsschlüssel. Ohne Angabe D.
addressSuffix string
partyType enum
Die Art des Beteiligten. **Freiwillig und zusätzlich** — ohne Angabe gilt wie bisher der Name: `companyName` heisst juristische Person, sonst natürliche Person. - `NATURAL_PERSON`, `LEGAL_PERSON` — die beiden bisherigen Arten, ausdrücklich benannt. - `AUTHORITY` — eine Behörde. Geht im XML als juristische Person hinaus; das Schema kennt keine eigene Art. - `SOLE_TRADER` — Einzelunternehmer. MIT `companyName` juristische Person, OHNE natürliche Person (amtliche Dokumentation zur Vollmacht: „Status als juristische Person wird nur dann zuerkannt, wenn ‚Name des Unternehmens' ausgefüllt ist"). Der Berufs-/Wirtschaftszweigschlüssel ist in beiden Fällen anzugeben — `888` gilt nur für Privatpersonen. - `ASSOCIATION` — eine nicht rechtsfähige Vereinigung, etwa eine GbR ohne Registereintrag oder eine Erbengemeinschaft. Geht als eigene Struktur (`NameVereinigung`) ans KBA, mit optionalem Vertreter. Ein eingetragener Verein ist dagegen eine juristische Person. Erweiterung gegenüber kennzeichen.dev.
NATURAL_PERSON · LEGAL_PERSON · AUTHORITY · SOLE_TRADER · ASSOCIATION
associationRepresentative object
Der benannte Vertreter einer Vereinigung — nur bei `partyType: ASSOCIATION` und dort freiwillig (seit XKfz 6.0 optional). In `POST /powerOfAttorneys` gibt es ihn nicht: Für eine Vereinigung lässt sich über uns keine Vollmacht unterschreiben (siehe `principal`).
firstName string
lastName string
companyName string
dateOfBirth string (date)
Streng als JJJJ-MM-TT. Nur bei natürlichen Personen. Zulässiger Bereich 1880–2099.
placeOfBirth string
Nur bei natürlichen Personen.
occupationKey string
Berufs- bzw. Wirtschaftszweigschlüssel, drei Stellen. Beim Halter einer Zulassung (UG, WG, WZ, NZ, TZ) Pflicht (KBA-Wissensartikel „Angabe des Berufsschlüssels bzw. Wirtschaftszweigs"). Firmen und juristische Personen nehmen den Schlüssel aus dem KBA-Verzeichnis SV 5, etwa `G01` für den Handel mit Kraftfahrzeugen; fehlt er, `400`. Privatpersonen ohne Angabe erhalten "888"; Freiberufler und Einzelunternehmer geben ihren Schlüssel an. Geprüft wird nur die Form. Bei der Halteränderung, beim Bevollmächtigten und beim Lieferungsempfänger optional.
documentBase64 string (byte)
Das unterschriebene Vollmacht-PDF, Base64-kodiert — selbst mitgebracht.
processId integer
Nummer eines Vollmachtsvorgangs, der über diesen Dienst unterschrieben wurde (siehe Self-Service-Bereich, „Vollmachtsvorgänge"). Wir hängen das signierte Dokument dann selbst an und gleichen die Vollmacht vorab gegen die Antragsdaten ab. Ist der Vorgang unbekannt oder gehört er einem anderen Mandanten: 404. Ist er noch nicht unterschrieben: 409, mit seinem Stand in der Meldung — und zwar vor jeder Feldprüfung: Feldfehler und der Abgleich mit der Vollmacht melden sich erst nach der Unterschrift. Ein 400 danach verbraucht den Vorgang nicht; der korrigierte Antrag darf dieselbe processId nennen.
email* string (email)
externalOrderId string
Ihre eigene Auftragsreferenz. Wird in Webhook-Events zurückgegeben — und ist zugleich der Schutz gegen den doppelt gestellten Antrag: Derselbe Mandant, dieselbe `externalOrderId`, dieselbe FIN UND derselbe Geschäftsvorfall (Endpunkt) innerhalb von 15 Minuten gelten als Wiederholungsversuch. Es geht dann NICHTS erneut an das KBA, und die Antwort nennt den bestehenden Vorgang (HTTP 200, dieselbe `order.id`). So führt eine Zeitüberschreitung samt automatischer Wiederholung Ihres Clients nicht zu zwei Anträgen und zwei Gebühren. Ohne Referenz greift der Schutz nicht — dann fehlt die Aussage „das ist derselbe Auftrag". **Weichen die Daten ab, ist es kein Wiederholungsversuch:** Dieselbe Referenz und FIN mit geändertem Inhalt beantwortet der Dienst mit **409** und ändert nichts. Weder darf er die Korrektur still verwerfen noch ungefragt einen zweiten Antrag samt Gebühr auslösen. Für einen weiteren Antrag eine eigene Referenz vergeben; für eine Berichtigung den bestehenden Vorgang korrigieren. **Dieselbe Referenz an einem anderen Endpunkt** — etwa NZ statt TZ oder WG statt WZ — ist kein Wiederholungsversuch, sondern ein neuer Antrag samt Gebühr. Ein falsch gewählter Endpunkt lässt sich nicht durch erneutes Senden unter derselben Referenz berichtigen.
correctionOf integer (int64)
Vorgangsnummer eines abgewiesenen oder fehlgeschlagenen Auftrags, der mit diesem Rumpf korrigiert werden soll. Es entsteht ein neuer KBA-Versuch am selben Auftrag; die Antwort nennt `attemptOf` und `attempt`. Laufende oder beschiedene Aufträge sowie ein anderer Geschäftsvorfall ergeben 409.
gksConfigurationId string (uuid)
TYPDeliveryItem
documentType* string
Codeliste artderunterlage — 2 ZB I, 3 ZB II, 27 HU-Plakette, 37 Siegelplakette, 39 HU-Plakettenträger, 42 Beiblatt zur ZB I, 40 Stempelplakettenträger (44 in älteren Beispielen, wird weiter angenommen).
quantity* integer
TYPDeliveryInstruction
deliveryService* enum
Zustellweg (Codeliste lieferdienst). AbholungBevollmaechtigter ist die Abholung durch den Bevollmächtigten — vom KBA am 14.05.2024 bestätigt, in keinem amtlichen Beispiel enthalten.
ZusendungHalter · ZusendungBevollmaechtigter · ZusendungDritter · Abholung · AbholungHalter · AbholungBevollmaechtigter
deliverTo enum
Wessen Anschrift gilt — hat Vorrang vor dem deliveryService. Ohne Angabe benennt der deliveryService den Empfänger (ZusendungHalter und AbholungHalter den Halter, ZusendungDritter den deliveryRecipient und so fort); benennt auch er niemanden (Abholung), gilt der deliveryRecipient, sonst der Bevollmächtigte, sonst der Halter. Verglichen wird gegen die Vollmacht, wer nach dieser Regel wirklich beliefert wird: ZusendungHalter mit deliverTo RECIPIENT gilt als Lieferung an den Dritten und ergibt gegen eine Vollmacht „an den Halter" 400.
HOLDER · REPRESENTATIVE · RECIPIENT
orderedAt string (date)
items* DeliveryItem[]
documentType* string
Codeliste artderunterlage — 2 ZB I, 3 ZB II, 27 HU-Plakette, 37 Siegelplakette, 39 HU-Plakettenträger, 42 Beiblatt zur ZB I, 40 Stempelplakettenträger (44 in älteren Beispielen, wird weiter angenommen).
quantity* integer
TYPBankAccount
iban* string
accountHolder* string
usage enum
Steuer · Gebuehren
directDebitMandateGranted boolean
TYPTaxDetails
paymentInterval* enum
jaehrlich · halbjaehrlich · vierteljaehrlich
taxLargeCustomerId string
Großkunden-ID der Steuer. Liegt sie vor, entfällt das SEPA-Mandat. Zollform — drei Ziffern, ein Großbuchstabe, vier Ziffern —, seit XKfz 6.0 verbindlich; andere Formen weisen wir mit 400 ab.
taxExemptionRequested boolean
Befreiung von der Kfz-Steuer beantragen. Ohne diese Angabe lässt sich ein Fahrzeug mit Steuerbefreiung — etwa bei Schwerbehinderung — nicht anmelden.
taxExemptionReason string
Grund der Steuerbefreiung. Wird unverändert durchgereicht und nicht gegen eine Liste geprüft: Welche Gründe es gibt, sagen die vorliegenden KBA-Unterlagen nicht; im amtlichen Beispiel steht `18`.
TYPInspectionDetails
reportDate string (date)
nextInspection* string
Fälligkeit der nächsten Untersuchung als MMJJJJ.
inspectionType enum
Ohne Angabe wird HU gesendet (Codeliste artderuntersuchung, Klartext „Hauptuntersuchung“). Eine Sicherheitsprüfung muss ausdrücklich SP setzen.
HU · SP
institutionKey string
Schlüsselnummer der Überwachungsinstitution oder des ZDK. Wird ungeprüft durchgereicht und als schluesselnummerDerUeberwachungsinstitutionOderZDK gesendet.
inspectionDate string (date)
expressProcedure boolean
checkDigit string
TYPLicensePlateSeal
position* enum
vorn · hinten · beide
securityCode string
Dreistelliger Code unter der Stempelplakette.
TYPVehicleRegistrationCustomization
vehicleIdentificationNumber* string
licensePlateNumberComponents object
Bisheriges Kennzeichen — bei Umschreibung Pflicht.
usageType enum
Kennzeichenmerkmal — für alle Anträge mit bisherigem Kennzeichen (AB, HA, UG, WG, WZ): EURO (Normalfall), ELECTRIC (Elektrokennzeichen) und HISTORIC (Oldtimerkennzeichen); andere Werte werden mit HTTP 400 abgewiesen.
EURO · ELECTRIC · HISTORIC
city* string
Unterscheidungszeichen, 1–3 Buchstaben (Umlaute zulässig). Kleinbuchstaben werden großgeschrieben; das Muster lässt sie deshalb zu.
middle* string
Erkennungsbuchstaben, 1–2 Buchstaben ohne Umlaute. Kleinbuchstaben werden großgeschrieben.
end* string
Erkennungsnummer, 1–4 Ziffern.
licensePlateSeals LicensePlateSeal[]
Codes der Stempelplaketten des bisherigen Kennzeichens — nur zusammen mit licensePlateNumberComponents wirksam. Ohne bisheriges Kennzeichen (immer bei NZ und TZ) werden die Einträge geprüft, aber nicht übermittelt.
position* enum
vorn · hinten · beide
securityCode string
Dreistelliger Code unter der Stempelplakette.
licensePlateAssignment object
Neues Kennzeichen zuteilen. Ein Wunschkennzeichen lässt sich über die GKS NICHT reservieren — entweder eine vorab bei der Zulassungsbehörde erwirkte Reservierung samt PIN, oder das nächste freie Kennzeichen.
reservation object
licensePlate* string
pin* string
plateType enum
Kennzeichenart nach dem amtlichen Schema (typ-MerkmalKennzeichenart-ZFZR). Z ist der Regelfall, B das Behördenkennzeichen. Pflicht, sobald das nächste freie Kennzeichen angefordert wird (keine `reservation`); fehlt sie, antworten wir mit 400. Saisonkennzeichen (ZS, BS) sind vorerst nicht beantragbar und werden mit 400 abgewiesen: Der Betriebszeitraum lässt sich im Antrag nicht angeben, und die Frage dazu ist beim KBA offen. Die übrigen Arten des Schemas — Ausfuhrkennzeichen (A), rotes Kennzeichen (R), Kurzzeitkennzeichen (RK) und Versicherungskennzeichen (V, VR) — lassen sich über die GKS nicht beantragen. Bescheide des KBA können dennoch jede Art melden.
B · Z
electric boolean
historic boolean
vehicleRegistrationCertificateSecurityCode string
vehicleRegistrationCertificateNumber string
Nummer der ZB I, 18–20 Zeichen, Buchstabe am Anfang. Kleinbuchstaben werden großgeschrieben.
vehicleRegistrationCertificateImprintNumber string
Druckstücknummer der ZB I. Acht Zeichen: Großbuchstabe, sechs Ziffern oder Großbuchstaben, zuletzt Ziffer oder X (Schema XKfz 6.0, Type.Druckstuecknummer).
vehicleRegistrationCertificatePartII object
number string
Nummer der ZB II. Kleinbuchstaben werden großgeschrieben. OHNEZBII und ohne-ZF- sind die amtlichen Platzhalter für Fahrzeuge ohne Teil II.
securityCode string
Zwölfstellig, Modulo-11-geprüft. Wird bereits hier vorgeprüft, verbindlich prüft das KBA.
insuranceConfirmationNumber* string
eVB-Nummer. Ohne sie ist keine Zulassung möglich.
vehicleUsage enum
Fahrzeugverwendung nach dem amtlichen Schema (typ-VerwendungFahrzeug). Muss zur eVB passen.
B · C · D · E · F · G · K · L · M · S · T · X
customerNumber string
contractPartner ContractPartner
TYPVehicleRegistrationRequest
requestRegistrationData boolean
Fordert die strukturierten Zulassungsdaten an (ZB I und ZB II, ueber sechzig Angaben). Ohne sie kommt nur der Bescheid als PDF zurueck. Die Daten erscheinen als `registrationData` in der Vorgangsauskunft und im Webhook-Ereignis. Bei einem Antrag mit Vollmacht muss sie das Kreuz „erweiterte Datenbereitstellung" tragen (`extendedDataProvision` im Vollmachtsvorgang), sonst antwortet der Antrag mit 400 — geprüft, sofern sich die Vollmacht als Formular lesen lässt.
orderEmissionSticker boolean
Feinstaubplakette mitbestellen; erweitert die Lieferung um eine Position (Festlegungen zum elektronischen Antrag, Blatt „GK NZ").
customization* VehicleRegistrationCustomization
vehicleIdentificationNumber* string
licensePlateNumberComponents object
Bisheriges Kennzeichen — bei Umschreibung Pflicht.
usageType enum
Kennzeichenmerkmal — für alle Anträge mit bisherigem Kennzeichen (AB, HA, UG, WG, WZ): EURO (Normalfall), ELECTRIC (Elektrokennzeichen) und HISTORIC (Oldtimerkennzeichen); andere Werte werden mit HTTP 400 abgewiesen.
EURO · ELECTRIC · HISTORIC
city* string
Unterscheidungszeichen, 1–3 Buchstaben (Umlaute zulässig). Kleinbuchstaben werden großgeschrieben; das Muster lässt sie deshalb zu.
middle* string
Erkennungsbuchstaben, 1–2 Buchstaben ohne Umlaute. Kleinbuchstaben werden großgeschrieben.
end* string
Erkennungsnummer, 1–4 Ziffern.
licensePlateSeals LicensePlateSeal[]
Codes der Stempelplaketten des bisherigen Kennzeichens — nur zusammen mit licensePlateNumberComponents wirksam. Ohne bisheriges Kennzeichen (immer bei NZ und TZ) werden die Einträge geprüft, aber nicht übermittelt.
position* enum
vorn · hinten · beide
securityCode string
Dreistelliger Code unter der Stempelplakette.
licensePlateAssignment object
Neues Kennzeichen zuteilen. Ein Wunschkennzeichen lässt sich über die GKS NICHT reservieren — entweder eine vorab bei der Zulassungsbehörde erwirkte Reservierung samt PIN, oder das nächste freie Kennzeichen.
reservation object
licensePlate* string
pin* string
plateType enum
Kennzeichenart nach dem amtlichen Schema (typ-MerkmalKennzeichenart-ZFZR). Z ist der Regelfall, B das Behördenkennzeichen. Pflicht, sobald das nächste freie Kennzeichen angefordert wird (keine `reservation`); fehlt sie, antworten wir mit 400. Saisonkennzeichen (ZS, BS) sind vorerst nicht beantragbar und werden mit 400 abgewiesen: Der Betriebszeitraum lässt sich im Antrag nicht angeben, und die Frage dazu ist beim KBA offen. Die übrigen Arten des Schemas — Ausfuhrkennzeichen (A), rotes Kennzeichen (R), Kurzzeitkennzeichen (RK) und Versicherungskennzeichen (V, VR) — lassen sich über die GKS nicht beantragen. Bescheide des KBA können dennoch jede Art melden.
B · Z
electric boolean
historic boolean
vehicleRegistrationCertificateSecurityCode string
vehicleRegistrationCertificateNumber string
Nummer der ZB I, 18–20 Zeichen, Buchstabe am Anfang. Kleinbuchstaben werden großgeschrieben.
vehicleRegistrationCertificateImprintNumber string
Druckstücknummer der ZB I. Acht Zeichen: Großbuchstabe, sechs Ziffern oder Großbuchstaben, zuletzt Ziffer oder X (Schema XKfz 6.0, Type.Druckstuecknummer).
vehicleRegistrationCertificatePartII object
number string
Nummer der ZB II. Kleinbuchstaben werden großgeschrieben. OHNEZBII und ohne-ZF- sind die amtlichen Platzhalter für Fahrzeuge ohne Teil II.
securityCode string
Zwölfstellig, Modulo-11-geprüft. Wird bereits hier vorgeprüft, verbindlich prüft das KBA.
insuranceConfirmationNumber* string
eVB-Nummer. Ohne sie ist keine Zulassung möglich.
vehicleUsage enum
Fahrzeugverwendung nach dem amtlichen Schema (typ-VerwendungFahrzeug). Muss zur eVB passen.
B · C · D · E · F · G · K · L · M · S · T · X
customerNumber string
contractPartner ContractPartner
vehicleHolder object
Der künftige Halter. Pflicht — AUSSER der Antrag beruft sich über `powerOfAttorney.processId` auf einen Vollmachtsvorgang, zu dem der Vertrauensdienst die Person bereits festgestellt hat. Dann setzen wir den Halter aus dessen Daten ein, und mitgeschickte Angaben werden überschrieben. Grund ist das BMDV-Schreiben vom 25.04.2024 (Az. 7362.8/1): Die Halterdaten stammen ausschliesslich vom Vertrauensdiensteanbieter, nicht aus der Kundeneingabe. § 38 Abs. 4 FZV sagt dasselbe — die Halterangaben sind der das Vollmachtsformular verarbeitenden Nachricht zu entnehmen. Bei Zulassungen (UG, WG, WZ, NZ, TZ) ersetzen wir mitgeschickte Halterangaben deshalb durch die des Vertrauensdienstes — es gibt dafür kein 400; Vorgangsauskunft und Dashboard zeigen den gesendeten Halter. Ergänzt wird nur, was kein Vertrauensdienst feststellt (`occupationKey`, `address.gender`; bei einer Firma nur `occupationKey`). Ohne `occupationKey` gilt der in der Vollmacht unterschriebene Wirtschaftszweig; `vehicleHolder: { occupationKey }` allein genügt. 400 kommt nur, wenn die Daten des Vertrauensdienstes nicht zur unterschriebenen Vollmacht passen, der mitgeschickte `occupationKey` vom in der Vollmacht unterschriebenen Wirtschaftszweig abweicht oder eine Firma an beiden Stellen keinen `occupationKey` führt. Anders die Halteränderung: Dort ist die neue Anschrift der Antrag selbst und muss der festgestellten entsprechen, sonst 400 (siehe `VehicleHolderChangeRequest`).
address* HolderAddress
firstName string
lastName string
companyName string
gender enum
Nur bei natürlichen Personen zulässig.
FEMALE · MALE · DIVERSE · UNSPECIFIED
streetName string
houseNumber string
Laut XKfz-Schema NUR Ziffern, höchstens vier. Ein Zusatz wie "7a" ist dort nicht vorgesehen und gehört in addressSuffix.
zipCode string
cityName string
countryCode string
KBA-Staatsschlüssel. Ohne Angabe D.
addressSuffix string
partyType enum
Die Art des Beteiligten. **Freiwillig und zusätzlich** — ohne Angabe gilt wie bisher der Name: `companyName` heisst juristische Person, sonst natürliche Person. - `NATURAL_PERSON`, `LEGAL_PERSON` — die beiden bisherigen Arten, ausdrücklich benannt. - `AUTHORITY` — eine Behörde. Geht im XML als juristische Person hinaus; das Schema kennt keine eigene Art. - `SOLE_TRADER` — Einzelunternehmer. MIT `companyName` juristische Person, OHNE natürliche Person (amtliche Dokumentation zur Vollmacht: „Status als juristische Person wird nur dann zuerkannt, wenn ‚Name des Unternehmens' ausgefüllt ist"). Der Berufs-/Wirtschaftszweigschlüssel ist in beiden Fällen anzugeben — `888` gilt nur für Privatpersonen. - `ASSOCIATION` — eine nicht rechtsfähige Vereinigung, etwa eine GbR ohne Registereintrag oder eine Erbengemeinschaft. Geht als eigene Struktur (`NameVereinigung`) ans KBA, mit optionalem Vertreter. Ein eingetragener Verein ist dagegen eine juristische Person. Erweiterung gegenüber kennzeichen.dev.
NATURAL_PERSON · LEGAL_PERSON · AUTHORITY · SOLE_TRADER · ASSOCIATION
associationRepresentative object
Der benannte Vertreter einer Vereinigung — nur bei `partyType: ASSOCIATION` und dort freiwillig (seit XKfz 6.0 optional). In `POST /powerOfAttorneys` gibt es ihn nicht: Für eine Vereinigung lässt sich über uns keine Vollmacht unterschreiben (siehe `principal`).
firstName string
lastName string
companyName string
dateOfBirth string (date)
Streng als JJJJ-MM-TT. Nur bei natürlichen Personen. Zulässiger Bereich 1880–2099.
placeOfBirth string
Nur bei natürlichen Personen.
occupationKey string
Berufs- bzw. Wirtschaftszweigschlüssel, drei Stellen. Beim Halter einer Zulassung (UG, WG, WZ, NZ, TZ) Pflicht (KBA-Wissensartikel „Angabe des Berufsschlüssels bzw. Wirtschaftszweigs"). Firmen und juristische Personen nehmen den Schlüssel aus dem KBA-Verzeichnis SV 5, etwa `G01` für den Handel mit Kraftfahrzeugen; fehlt er, `400`. Privatpersonen ohne Angabe erhalten "888"; Freiberufler und Einzelunternehmer geben ihren Schlüssel an. Geprüft wird nur die Form. Bei der Halteränderung, beim Bevollmächtigten und beim Lieferungsempfänger optional.
powerOfAttorney PowerOfAttorney
representative HolderParty
address* HolderAddress
firstName string
lastName string
companyName string
gender enum
Nur bei natürlichen Personen zulässig.
FEMALE · MALE · DIVERSE · UNSPECIFIED
streetName string
houseNumber string
Laut XKfz-Schema NUR Ziffern, höchstens vier. Ein Zusatz wie "7a" ist dort nicht vorgesehen und gehört in addressSuffix.
zipCode string
cityName string
countryCode string
KBA-Staatsschlüssel. Ohne Angabe D.
addressSuffix string
partyType enum
Die Art des Beteiligten. **Freiwillig und zusätzlich** — ohne Angabe gilt wie bisher der Name: `companyName` heisst juristische Person, sonst natürliche Person. - `NATURAL_PERSON`, `LEGAL_PERSON` — die beiden bisherigen Arten, ausdrücklich benannt. - `AUTHORITY` — eine Behörde. Geht im XML als juristische Person hinaus; das Schema kennt keine eigene Art. - `SOLE_TRADER` — Einzelunternehmer. MIT `companyName` juristische Person, OHNE natürliche Person (amtliche Dokumentation zur Vollmacht: „Status als juristische Person wird nur dann zuerkannt, wenn ‚Name des Unternehmens' ausgefüllt ist"). Der Berufs-/Wirtschaftszweigschlüssel ist in beiden Fällen anzugeben — `888` gilt nur für Privatpersonen. - `ASSOCIATION` — eine nicht rechtsfähige Vereinigung, etwa eine GbR ohne Registereintrag oder eine Erbengemeinschaft. Geht als eigene Struktur (`NameVereinigung`) ans KBA, mit optionalem Vertreter. Ein eingetragener Verein ist dagegen eine juristische Person. Erweiterung gegenüber kennzeichen.dev.
NATURAL_PERSON · LEGAL_PERSON · AUTHORITY · SOLE_TRADER · ASSOCIATION
associationRepresentative object
Der benannte Vertreter einer Vereinigung — nur bei `partyType: ASSOCIATION` und dort freiwillig (seit XKfz 6.0 optional). In `POST /powerOfAttorneys` gibt es ihn nicht: Für eine Vereinigung lässt sich über uns keine Vollmacht unterschreiben (siehe `principal`).
firstName string
lastName string
companyName string
dateOfBirth string (date)
Streng als JJJJ-MM-TT. Nur bei natürlichen Personen. Zulässiger Bereich 1880–2099.
placeOfBirth string
Nur bei natürlichen Personen.
occupationKey string
Berufs- bzw. Wirtschaftszweigschlüssel, drei Stellen. Beim Halter einer Zulassung (UG, WG, WZ, NZ, TZ) Pflicht (KBA-Wissensartikel „Angabe des Berufsschlüssels bzw. Wirtschaftszweigs"). Firmen und juristische Personen nehmen den Schlüssel aus dem KBA-Verzeichnis SV 5, etwa `G01` für den Handel mit Kraftfahrzeugen; fehlt er, `400`. Privatpersonen ohne Angabe erhalten "888"; Freiberufler und Einzelunternehmer geben ihren Schlüssel an. Geprüft wird nur die Form. Bei der Halteränderung, beim Bevollmächtigten und beim Lieferungsempfänger optional.
documentBase64 string (byte)
Das unterschriebene Vollmacht-PDF, Base64-kodiert — selbst mitgebracht.
processId integer
Nummer eines Vollmachtsvorgangs, der über diesen Dienst unterschrieben wurde (siehe Self-Service-Bereich, „Vollmachtsvorgänge"). Wir hängen das signierte Dokument dann selbst an und gleichen die Vollmacht vorab gegen die Antragsdaten ab. Ist der Vorgang unbekannt oder gehört er einem anderen Mandanten: 404. Ist er noch nicht unterschrieben: 409, mit seinem Stand in der Meldung — und zwar vor jeder Feldprüfung: Feldfehler und der Abgleich mit der Vollmacht melden sich erst nach der Unterschrift. Ein 400 danach verbraucht den Vorgang nicht; der korrigierte Antrag darf dieselbe processId nennen.
deliveryRecipient object
Abweichender Empfänger der Zulassungsunterlagen.
address* HolderAddress
firstName string
lastName string
companyName string
gender enum
Nur bei natürlichen Personen zulässig.
FEMALE · MALE · DIVERSE · UNSPECIFIED
streetName string
houseNumber string
Laut XKfz-Schema NUR Ziffern, höchstens vier. Ein Zusatz wie "7a" ist dort nicht vorgesehen und gehört in addressSuffix.
zipCode string
cityName string
countryCode string
KBA-Staatsschlüssel. Ohne Angabe D.
addressSuffix string
partyType enum
Die Art des Beteiligten. **Freiwillig und zusätzlich** — ohne Angabe gilt wie bisher der Name: `companyName` heisst juristische Person, sonst natürliche Person. - `NATURAL_PERSON`, `LEGAL_PERSON` — die beiden bisherigen Arten, ausdrücklich benannt. - `AUTHORITY` — eine Behörde. Geht im XML als juristische Person hinaus; das Schema kennt keine eigene Art. - `SOLE_TRADER` — Einzelunternehmer. MIT `companyName` juristische Person, OHNE natürliche Person (amtliche Dokumentation zur Vollmacht: „Status als juristische Person wird nur dann zuerkannt, wenn ‚Name des Unternehmens' ausgefüllt ist"). Der Berufs-/Wirtschaftszweigschlüssel ist in beiden Fällen anzugeben — `888` gilt nur für Privatpersonen. - `ASSOCIATION` — eine nicht rechtsfähige Vereinigung, etwa eine GbR ohne Registereintrag oder eine Erbengemeinschaft. Geht als eigene Struktur (`NameVereinigung`) ans KBA, mit optionalem Vertreter. Ein eingetragener Verein ist dagegen eine juristische Person. Erweiterung gegenüber kennzeichen.dev.
NATURAL_PERSON · LEGAL_PERSON · AUTHORITY · SOLE_TRADER · ASSOCIATION
associationRepresentative object
Der benannte Vertreter einer Vereinigung — nur bei `partyType: ASSOCIATION` und dort freiwillig (seit XKfz 6.0 optional). In `POST /powerOfAttorneys` gibt es ihn nicht: Für eine Vereinigung lässt sich über uns keine Vollmacht unterschreiben (siehe `principal`).
firstName string
lastName string
companyName string
dateOfBirth string (date)
Streng als JJJJ-MM-TT. Nur bei natürlichen Personen. Zulässiger Bereich 1880–2099.
placeOfBirth string
Nur bei natürlichen Personen.
occupationKey string
Berufs- bzw. Wirtschaftszweigschlüssel, drei Stellen. Beim Halter einer Zulassung (UG, WG, WZ, NZ, TZ) Pflicht (KBA-Wissensartikel „Angabe des Berufsschlüssels bzw. Wirtschaftszweigs"). Firmen und juristische Personen nehmen den Schlüssel aus dem KBA-Verzeichnis SV 5, etwa `G01` für den Handel mit Kraftfahrzeugen; fehlt er, `400`. Privatpersonen ohne Angabe erhalten "888"; Freiberufler und Einzelunternehmer geben ihren Schlüssel an. Geprüft wird nur die Form. Bei der Halteränderung, beim Bevollmächtigten und beim Lieferungsempfänger optional.
sepaMandateBase64 string (byte)
SEPA-Mandat als PDF. Anders als bei der Vollmacht ist hier ein Scan zulässig. Entfällt, wenn sich der Antrag über `powerOfAttorney.processId` auf einen Vollmachtsvorgang mit `bankAccount` beruft: Dann hängen wir das dort signierte Mandat an — sofern `bankAccount` hier dieselbe IBAN und denselben Kontoinhaber nennt, sonst `400`. Mitgeschickt hat dieses Feld Vorrang.
bankAccount BankAccount
iban* string
accountHolder* string
usage enum
Steuer · Gebuehren
directDebitMandateGranted boolean
taxDetails TaxDetails
paymentInterval* enum
jaehrlich · halbjaehrlich · vierteljaehrlich
taxLargeCustomerId string
Großkunden-ID der Steuer. Liegt sie vor, entfällt das SEPA-Mandat. Zollform — drei Ziffern, ein Großbuchstabe, vier Ziffern —, seit XKfz 6.0 verbindlich; andere Formen weisen wir mit 400 ab.
taxExemptionRequested boolean
Befreiung von der Kfz-Steuer beantragen. Ohne diese Angabe lässt sich ein Fahrzeug mit Steuerbefreiung — etwa bei Schwerbehinderung — nicht anmelden.
taxExemptionReason string
Grund der Steuerbefreiung. Wird unverändert durchgereicht und nicht gegen eine Liste geprüft: Welche Gründe es gibt, sagen die vorliegenden KBA-Unterlagen nicht; im amtlichen Beispiel steht `18`.
inspections InspectionDetails[]
reportDate string (date)
nextInspection* string
Fälligkeit der nächsten Untersuchung als MMJJJJ.
inspectionType enum
Ohne Angabe wird HU gesendet (Codeliste artderuntersuchung, Klartext „Hauptuntersuchung“). Eine Sicherheitsprüfung muss ausdrücklich SP setzen.
HU · SP
institutionKey string
Schlüsselnummer der Überwachungsinstitution oder des ZDK. Wird ungeprüft durchgereicht und als schluesselnummerDerUeberwachungsinstitutionOderZDK gesendet.
inspectionDate string (date)
expressProcedure boolean
checkDigit string
deliveries DeliveryInstruction[]
deliveryService* enum
Zustellweg (Codeliste lieferdienst). AbholungBevollmaechtigter ist die Abholung durch den Bevollmächtigten — vom KBA am 14.05.2024 bestätigt, in keinem amtlichen Beispiel enthalten.
ZusendungHalter · ZusendungBevollmaechtigter · ZusendungDritter · Abholung · AbholungHalter · AbholungBevollmaechtigter
deliverTo enum
Wessen Anschrift gilt — hat Vorrang vor dem deliveryService. Ohne Angabe benennt der deliveryService den Empfänger (ZusendungHalter und AbholungHalter den Halter, ZusendungDritter den deliveryRecipient und so fort); benennt auch er niemanden (Abholung), gilt der deliveryRecipient, sonst der Bevollmächtigte, sonst der Halter. Verglichen wird gegen die Vollmacht, wer nach dieser Regel wirklich beliefert wird: ZusendungHalter mit deliverTo RECIPIENT gilt als Lieferung an den Dritten und ergibt gegen eine Vollmacht „an den Halter" 400.
HOLDER · REPRESENTATIVE · RECIPIENT
orderedAt string (date)
items* DeliveryItem[]
documentType* string
Codeliste artderunterlage — 2 ZB I, 3 ZB II, 27 HU-Plakette, 37 Siegelplakette, 39 HU-Plakettenträger, 42 Beiblatt zur ZB I, 40 Stempelplakettenträger (44 in älteren Beispielen, wird weiter angenommen).
quantity* integer
email* string (email)
externalOrderId string
Ihre eigene Auftragsreferenz. Wird in Webhook-Events zurückgegeben — und ist zugleich der Schutz gegen den doppelt gestellten Antrag: Derselbe Mandant, dieselbe `externalOrderId`, dieselbe FIN UND derselbe Geschäftsvorfall (Endpunkt) innerhalb von 15 Minuten gelten als Wiederholungsversuch. Es geht dann NICHTS erneut an das KBA, und die Antwort nennt den bestehenden Vorgang (HTTP 200, dieselbe `order.id`). So führt eine Zeitüberschreitung samt automatischer Wiederholung Ihres Clients nicht zu zwei Anträgen und zwei Gebühren. Ohne Referenz greift der Schutz nicht — dann fehlt die Aussage „das ist derselbe Auftrag". **Weichen die Daten ab, ist es kein Wiederholungsversuch:** Dieselbe Referenz und FIN mit geändertem Inhalt beantwortet der Dienst mit **409** und ändert nichts. Weder darf er die Korrektur still verwerfen noch ungefragt einen zweiten Antrag samt Gebühr auslösen. Für einen weiteren Antrag eine eigene Referenz vergeben; für eine Berichtigung den bestehenden Vorgang korrigieren. **Dieselbe Referenz an einem anderen Endpunkt** — etwa NZ statt TZ oder WG statt WZ — ist kein Wiederholungsversuch, sondern ein neuer Antrag samt Gebühr. Ein falsch gewählter Endpunkt lässt sich nicht durch erneutes Senden unter derselben Referenz berichtigen.
correctionOf integer (int64)
Vorgangsnummer eines abgewiesenen oder fehlgeschlagenen Auftrags, der mit diesem Rumpf korrigiert werden soll. Es entsteht ein neuer KBA-Versuch am selben Auftrag; die Antwort nennt `attemptOf` und `attempt`. Laufende oder beschiedene Aufträge sowie ein anderer Geschäftsvorfall ergeben 409.
gksConfigurationId string (uuid)
TYPGksConfigurationRequest
name* string
Sprechender Name des Zugangs.
kopaKey* string
KoPa-Schlüssel des Großkunden, z. B. U195303.
largeCustomerId string
Siebenstellige Großkunden-ID aus der KBA-Registrierung.
username* string
GKS-Kennung für die Anmeldung. Höchstens 20 Zeichen.
password* string (password)
GKS-Passwort. Wird verschlüsselt abgelegt und nie zurückgegeben. Läuft laut KBA alle 90 Tage ab.
publicKeyCertificate string
Das X.509-Zertifikat als PEM-Text, von der Zeile `-----BEGIN CERTIFICATE-----` bis `-----END CERTIFICATE-----`. Gehört mit `privateKey` zusammen gesendet. X.509 **v3**; ein v1-Zertifikat wird angenommen und nur angemerkt, von der KBA-Registrierungsanwendung aber seit dem 07.09.2026 nicht mehr. Laufzeit höchstens ein Jahr: über 366 Tage 400, genau 366 Tage nur eine Anmerkung, angenommen wurden 364 Tage. Beim KBA wird dasselbe Zertifikat als Base64-`.cer` hochgeladen.
privateKey string (password)
Der private Schlüssel als PEM-Text. Wird als Datei abgelegt; in der Datenbank steht nur der Pfad, und zurückgegeben wird er nie.
environment enum
Bestimmt die KBA-Endpunkte. Ein Testzugang gerät damit niemals auf die Produktionsstrecke.
test · produktion
company —
Firma des Großkunden. Zeichenkette oder Objekt mit `name` — aus einem Objekt wird nur der Name übernommen, die Anschrift wird nicht gebraucht.
TYPGksConfigurationOverview
id string (uuid)
Als `gksConfigurationId` in jedem Antrag verwendbar.
name string
kopaKey string
largeCustomerId string
username string
environment enum
test · produktion
company string
createdAt string (date-time)
certificatePresent boolean
Liegt die Zertifikatsdatei tatsächlich auf dem Server?
privateKeyPresent boolean
TYPAddress
firstName string
lastName string
companyName string
streetName string
houseNumber string
zipCode string
cityName string
countryCode string
KBA-Staatsschlüssel
TYPVehicleDeregistrationRequestVehicleHolder
address Address
firstName string
lastName string
companyName string
streetName string
houseNumber string
zipCode string
cityName string
countryCode string
KBA-Staatsschlüssel
TYPVehicleDeregistrationRequest
customization* VehicleDeregistrationCustomization
productType enum
VEHICLE_DEREGISTRATION
licensePlateNumberComponents* EuroLicensePlateNumberComponents
usageType enum
Kennzeichenmerkmal — für alle Anträge mit bisherigem Kennzeichen (AB, HA, UG, WG, WZ): EURO (Normalfall), ELECTRIC (Elektrokennzeichen) und HISTORIC (Oldtimerkennzeichen); andere Werte werden mit HTTP 400 abgewiesen.
EURO · ELECTRIC · HISTORIC
city* string
Unterscheidungszeichen, 1–3 Buchstaben (Umlaute zulässig). Kleinbuchstaben werden großgeschrieben; das Muster lässt sie deshalb zu.
middle* string
Erkennungsbuchstaben, 1–2 Buchstaben ohne Umlaute. Kleinbuchstaben werden großgeschrieben.
end* string
Erkennungsnummer, 1–4 Ziffern.
licensePlateReservationIncluded* boolean
Kennzeichen fahrzeugbezogen reservieren, längstens zwölf Monate. Bei Entsorgung (SCRAPPED_IN_GERMANY, EXPORTED_FOR_DISPOSAL) ausgeschlossen.
vehicleIdentificationNumber* string
Fahrzeugidentifizierungsnummer. Geprüft wird die Regel des KBA: Ziffern und Großbuchstaben, höchstens 25 Stellen (sonst Fehlercode 00306); Kleinbuchstaben werden großgeschrieben. **Auf Länge und Zeichenwahl wird bewusst NICHT strenger geprüft** — seit 1981 hat eine FIN zwar genau 17 Stellen und üblicherweise kein I, O oder Q, aber Oldtimer führen kürzere Nummern, und die amtlichen Beispiele des KBA enthalten vereinzelt doch ein O. Eine falsche FIN fällt deshalb erst beim KBA auf und kostet die Übermittlungsgebühr: bitte gegen den Fahrzeugschein prüfen.
vehicleRegistrationCertificateSecurityCode* string
Sicherheitscode der Zulassungsbescheinigung Teil I, genau sieben Ziffern oder Buchstaben (`SicherheitscodeZB1`). Klein- und Großschreibung gehören hier zum Wert und werden nicht vereinheitlicht.
frontLicensePlateSecurityCode string
Sicherheitscode der vorderen Stempelplakette, genau drei Ziffern oder Buchstaben. Erforderlich bei Fahrzeugen mit zwei Kennzeichenschildern; bei nur einem Schild unzulässig.
rearLicensePlateSecurityCode* string
Sicherheitscode der hinteren Stempelplakette, genau drei Ziffern oder Buchstaben.
vehicleRegistrationCertificateNumber string
Erweiterung — Nummer der ZB I, 18–20 Zeichen, Buchstabe am Anfang. Kleinbuchstaben werden großgeschrieben; das Muster lässt sie deshalb zu.
recycling Recycling
type* enum
SCRAPPED_IN_GERMANY — Verwertungsnachweis lag vor (§ 15 Abs. 1/2 FZV). NOT_DISPOSED — außer Betrieb gesetzt, nicht als Abfall entsorgt (§ 15 Abs. 5 FZV). EXPORTED_FOR_DISPOSAL — zur Entsorgung außerhalb EU/EWR verbracht (§ 15 Abs. 4 FZV).
SCRAPPED_IN_GERMANY · NOT_DISPOSED · EXPORTED_FOR_DISPOSAL
dismantlingCompanyNumber string
Betriebsnummer des Demontagebetriebs, höchstens 20 Zeichen (`BetriebsnummerDemontagebetrieb`). Pflicht bei SCRAPPED_IN_GERMANY.
certificateDate string (date)
Ausstellungsdatum des Nachweises. Pflicht bei SCRAPPED_IN_GERMANY.
countryCode string
Zielstaat nach KBA-Staatsschlüssel, ein bis drei Großbuchstaben (`StaatVerwertung`, z. B. D, NL). Pflicht bei EXPORTED_FOR_DISPOSAL.
vehicleRegistrationCertificatePartII VehicleRegistrationCertificatePartII
number string
Nummer der ZB II. Kleinbuchstaben werden großgeschrieben.
securityCode* string
Zwölfstellig, **beginnend mit `B`**; danach zehn Stellen (Ziffern und Buchstaben, Kleinbuchstaben zulässig). Die letzte Stelle ist eine Ziffer oder `X` und trägt die Modulo-11-Prüfziffer über den gesamten Code. Format und Prüfziffer sind zwei Prüfungen: Die Form lässt sich gegen `pattern` vorab feststellen, die Prüfziffer rechnet der Dienst vor dem Versand nach und weist sie mit 400 ab.
contractPartner ContractPartner
email* string (email)
externalOrderId string
Ihre eigene Referenz. Wird in Webhook-Events zurückgegeben — und ist zugleich der Schutz gegen den doppelt gestellten Antrag: Derselbe Mandant, dieselbe `externalOrderId`, dieselbe FIN und derselbe Geschäftsvorfall innerhalb von 15 Minuten gelten als Wiederholungsversuch. Es geht dann NICHTS erneut an das KBA, und die Antwort nennt den bestehenden Vorgang (HTTP 200, dieselbe `order.id`). Ohne Referenz greift der Schutz nicht — dann fehlt die Aussage „das ist derselbe Auftrag". **Weichen die Daten ab, ist es kein Wiederholungsversuch:** Dieselbe Referenz und FIN mit geändertem Inhalt beantwortet der Dienst mit **409** und ändert nichts. Weder darf er die Korrektur still verwerfen noch ungefragt einen zweiten Antrag samt Gebühr auslösen. Für einen weiteren Antrag eine eigene Referenz vergeben; für eine Berichtigung den bestehenden Vorgang korrigieren.
correctionOf integer (int64)
Vorgangsnummer eines abgewiesenen oder fehlgeschlagenen Auftrags, der mit diesem Rumpf korrigiert werden soll. Es entsteht ein neuer KBA-Versuch am selben Auftrag; die Antwort nennt `attemptOf` und `attempt`. Laufende oder beschiedene Aufträge ergeben 409.
gksConfigurationId string (uuid)
vehicleHolder VehicleDeregistrationRequestVehicleHolder
Wird entgegengenommen, aber nicht an das KBA übermittelt: Bei der Außerbetriebsetzung stammen die Halterdaten aus dem Fahrzeugregister.
address Address
firstName string
lastName string
companyName string
streetName string
houseNumber string
zipCode string
cityName string
countryCode string
KBA-Staatsschlüssel
TYPVehicleDeregistrationResponse
order* object
id* integer (int64)
attemptOf integer (int64)
Nur bei einer Korrektur — die Auftragsnummer der Versuchskette.
attempt integer
Nur bei einer Korrektur — die laufende Nummer des neuen Versuchs.
TYPVehicleDeregistrationOrderList
orders* VehicleDeregistrationOrderSummary[]
order object
id integer
externalId string
attemptOf integer
Id des Auftrags. In dieser Liste stehen nur Auftragsköpfe, also immer die eigene Id.
businessTransaction string
state enum
angelegt · eingereicht · inBearbeitung · weitergeleitet · beschieden · abgelehnt · fehlgeschlagen
derivedStatus enum
PENDING · SUCCESS · FAILURE · VEHICLE_UNKNOWN · VEHICLE_ALREADY_DEREGISTERED · LICENSE_PLATE_CODE_INVALID · REGISTRATION_CERTIFICATE_CODE_INVALID · LICENSE_PLATE_CODE_QTY_INVALID · INPUT_INVALID · RESERVATION_IMPOSSIBLE · ERROR_UNHANDLED
applicationId string
vehicleIdentificationNumber string
licensePlate string
createdAt string (date-time)
changedAt string (date-time)
Der Wert, gegen den `changedSince` filtert.
limit* integer
Das angewandte Limit. Höchstens 200, auch wenn Sie mehr anfragen.
offset* integer
total* integer
Wie viele Aufträge der Filter insgesamt trifft — nicht die Seitengröße.
hasMore* boolean
Ob nach dieser Seite noch etwas kommt. Steht ausdrücklich da, statt sie aus `total > offset + limit` ableiten zu lassen: Diese Rechnung stellt jeder Aufrufer selbst an, und einer stellt sie falsch.
TYPVehicleDeregistrationOrderSummary
order object
id integer
externalId string
attemptOf integer
Id des Auftrags. In dieser Liste stehen nur Auftragsköpfe, also immer die eigene Id.
businessTransaction string
state enum
angelegt · eingereicht · inBearbeitung · weitergeleitet · beschieden · abgelehnt · fehlgeschlagen
derivedStatus enum
PENDING · SUCCESS · FAILURE · VEHICLE_UNKNOWN · VEHICLE_ALREADY_DEREGISTERED · LICENSE_PLATE_CODE_INVALID · REGISTRATION_CERTIFICATE_CODE_INVALID · LICENSE_PLATE_CODE_QTY_INVALID · INPUT_INVALID · RESERVATION_IMPOSSIBLE · ERROR_UNHANDLED
applicationId string
vehicleIdentificationNumber string
licensePlate string
createdAt string (date-time)
changedAt string (date-time)
Der Wert, gegen den `changedSince` filtert.
TYPVehicleDeregistrationOrderCostBreakdownItem
number* integer
code string
Gebührennummer nach GebOSt, z. B. 224.2.
name string
amount* integer
Betrag in kleinster Währungseinheit (Cent).
note string
TYPVehicleDeregistrationOrderCostBreakdown
kbaCost integer
Nutzungsgebühr des KBA nach Nr. 129 GebOSt, in Cent. Steht da, wenn das KBA sie mit Quittungscode 07085 angekündigt hat oder der Antrag beschieden bzw. abgelehnt ist; sonst fehlt das Feld.
registrationOfficeCosts object
items* VehicleDeregistrationOrderCostBreakdownItem[]
number* integer
code string
Gebührennummer nach GebOSt, z. B. 224.2.
name string
amount* integer
Betrag in kleinster Währungseinheit (Cent).
note string
total* VehicleDeregistrationOrderCostBreakdownItem
number* integer
code string
Gebührennummer nach GebOSt, z. B. 224.2.
name string
amount* integer
Betrag in kleinster Währungseinheit (Cent).
note string
TYPVehicleDeregistrationOrder
order object
id integer
Vorgangsnummer in diesem System.
externalId string
Ihre eigene Referenz aus dem Antrag.
attempt integer
Laufende Nummer des Versuchs. Ein korrigierter Antrag entsteht als NEUER Vorgang mit derselben `externalId` — beim KBA ist jeder Versuch ein eigener Antrag mit eigener Antragsnummer.
attemptOf integer
Id des Auftrags, zu dem dieser Versuch gehört; beim ersten Versuch die eigene Id. **Wer über die Schnittstelle abrechnet, gruppiert danach** — sonst zählt derselbe Auftrag mehrfach. Abgerechnet wird er einmal (die Übermittlungsgebühr je abgewiesenem Versuch bleibt davon unberührt).
state enum
Der Stand des Vorgangs. **Endzustand heisst: Endzustand des VERSUCHS, nicht des Auftrags.** `beschieden`, `abgelehnt` und `fehlgeschlagen` beenden den einzelnen Antrag beim KBA. Der Auftrag darüber kann weitergehen: Wird ein abgewiesener Antrag korrigiert, entsteht ein zweiter Versuch, und der Auftragskopf folgt dem jüngsten — er wechselt dann von `fehlgeschlagen` zurück nach `inBearbeitung`. Wer auf „Endzustand" vertraut und den Auftrag in seinem System abschliesst, verpasst die Korrektur und meldet ein Fahrzeug als nicht abgemeldet, obwohl es abgemeldet wird. Der Rücksprung sieht dabei aus wie ein Fehler des Systems und ist keiner. Fragen Sie den Versuch ab, wenn Sie einen Endzustand brauchen — `attempt` und `attemptOf` sagen Ihnen, was Sie vor sich haben. Die Webhook-Ereignisse führen für denselben Sachverhalt eigene, englische Werte (`ACCEPTED`, `APPROVED_WITH_DOCUMENTS`, `REJECTED_WITH_DOCUMENTS`) samt `derivedStatus`.
angelegt · eingereicht · inBearbeitung · weitergeleitet · beschieden · abgelehnt · fehlgeschlagen
derivedStatus enum
Die grobe Einordnung: läuft noch, erledigt, gescheitert. `state` hat sieben Werte, und welche davon Endzustände sind, steht in dieser Spezifikation — ein Aufrufer müsste die Liste bei jeder Erweiterung nachziehen. Wenn Ihr System nur wissen will, ob es weiter warten muss, werten Sie dieses Feld aus. Es ist dieselbe Abbildung, die auch das Webhook-Ereignis führt.
PENDING · SUCCESS · FAILURE · VEHICLE_UNKNOWN · VEHICLE_ALREADY_DEREGISTERED · LICENSE_PLATE_CODE_INVALID · REGISTRATION_CERTIFICATE_CODE_INVALID · LICENSE_PLATE_CODE_QTY_INVALID · INPUT_INVALID · RESERVATION_IMPOSSIBLE · ERROR_UNHANDLED
applicationId string
Antragsnummer des KBA — der Schlüssel für jede Rückfrage dort. Erst gesetzt, nachdem die Quittung eingetroffen ist; bei einem Antrag, der das KBA nicht erreicht hat, bleibt sie leer.
vehicleIdentificationNumber string
Die FIN des Vorgangs, immer in Großschreibung. **Am Auftragskopf kann sie sich ändern.** Eine Korrektur darf eine falsch abgetippte FIN berichtigen; der Kopf folgt dem jüngsten Versuch und trägt danach die neue. Die `externalId` bleibt dabei dieselbe. Wer Fahrzeuge über die FIN führt, sollte das wissen — sonst liest es sich wie eine Verwechslung von Fahrzeugen.
licensePlate string
Kennzeichen in der Anzeigeform, z. B. `HN-LL 2418`.
files object[]
Belege aus dem Rückkanal. Der Gebührenbescheid erscheint nur, wenn Sie selbst beim KBA registriert sind. Am Auftragskopf stehen die Belege aller Versuche (Kopf und `attempts[].id`), ohne Dubletten und in der Reihenfolge ihres Eingangs; die Auskunft zu einer Versuchs-Id führt nur dessen eigene.
purposeType string
mediaType string
fileAccessKey string
Einzulösen über `/vehicleDeregistrations/files/content/{fileAccessKey}`.
expirationTime string (date-time)
Bis dahin ist der Schlüssel gültig — beim Ablegen eines Vorgangsbelegs 72 Stunden; danach im Self-Service erneut freigeben. **Format:** vollständiger ISO-8601-Zeitstempel MIT Zonenangabe und Millisekunden (`2026-09-19T14:38:22.558Z`). Das Webhook-Ereignis nennt denselben Zeitpunkt als `LocalDateTime` — in UTC, aber ohne Zone und sekundengenau (`2026-09-19T14:38:22`); dieses Format schreibt der Webhook-Vertrag vor (`spec/webhooks.yaml`, Vorbild kennzeichen.dev). Wer beide Quellen vergleicht, liest den Wert des Ereignisses als UTC.
filename string
Der Name, unter dem der Abruf die Datei ausliefert (`Content-Disposition`), z. B. `Vorgang-17_KBA-NZ-123_Zulassungsbescheid.pdf`. Zwei Belege mit `purposeType: CERTIFICATE` — Zulassungsbescheid und vorläufiger Zulassungsnachweis — sind daran zu unterscheiden.
costBreakdown object
Die Gebührenaufstellung aus der Entscheidung (0709) — derselbe Wert wie `costBreakdown` im Webhook-Ereignis, für den Abgleich nach einem verlorenen Ereignis. **Nur bei eigener KBA-Registrierung** (Selbstabrechner); ein Vertragspartner unter unserer Registrierung sieht die amtlichen Beträge weder hier noch im Ereignis noch im Dashboard. Fehlt, solange keine Entscheidung vorliegt.
kbaCost integer
Nutzungsgebühr des KBA nach Nr. 129 GebOSt, in Cent. Steht da, wenn das KBA sie mit Quittungscode 07085 angekündigt hat oder der Antrag beschieden bzw. abgelehnt ist; sonst fehlt das Feld.
registrationOfficeCosts object
items* VehicleDeregistrationOrderCostBreakdownItem[]
number* integer
code string
Gebührennummer nach GebOSt, z. B. 224.2.
name string
amount* integer
Betrag in kleinster Währungseinheit (Cent).
note string
total* VehicleDeregistrationOrderCostBreakdownItem
number* integer
code string
Gebührennummer nach GebOSt, z. B. 224.2.
name string
amount* integer
Betrag in kleinster Währungseinheit (Cent).
note string
registrationData object
Über sechzig Angaben aus den Zulassungsbescheinigungen, sofern die Rückmeldung sie führt.
registrationDocumentsReady boolean
Erweiterung gegenüber kennzeichen.dev. `true`, wenn die Zulassungsbehörde meldet, dass die Zulassungsunterlagen (ZB I, ZB II, Stempelplaketten, Feinstaubplakette) wie gewünscht versandt wurden oder zur Abholung bereitliegen — derselbe Wert wie `registrationDocumentsReady` im Webhook-Ereignis. Nur bei Zulassungsvorfällen und nur in der automatisierten Bearbeitung nach einer antragsgemäßen Entscheidung. **Fehlt das Feld, ist nichts gesagt** — nicht „nicht versandt": Die Behörde führt die Angabe nicht in jeder Nachricht. Löst die abschliessende Rückmeldung weder einen Zustandswechsel noch neue Belege aus, kommt kein weiteres Ereignis; dann steht die Angabe nur hier.
parties object[]
Beteiligte laut Rückmeldung, etwa der Halter — bei allen Geschäftsvorfällen. Dieselbe Struktur wie im Webhook-Ereignis (spec/webhooks.yaml, …Party): `role` (Codeliste `rolle`, `2` ist der Halter), `roleName` (Klartext der Rolle, fehlt wenn die Nachricht keinen führt), `kind` (natural, legal, association), `name` und bei einer Vereinigung `representative`.
messages object[]
Meldungen des KBA mit Klartext und Begründung. `code` ist nicht immer ein fünfstelliger Quittungscode: Eine Ablehnung führt dort ihren kurzen Ablehnungsgrund; trägt sie keinen — der Regelfall —, steht im `code` der Antragsstatus in Worten. **Bis zum 19.08.2026 stand hier `{code, text, zusatz}`.** Geliefert wurden schon immer fünf Felder, und `zusatz` heisst in Wahrheit `additional` — Codegenerierung gegen den Vertrag erzeugte damit ein Feld, das nie befüllt wird, und übersah drei, die kommen. Die Webhook-Spezifikation beschrieb dieselbe Struktur die ganze Zeit richtig; beide sagen jetzt dasselbe, weil beide Wege dieselbe Funktion benutzen.
type* string
Herkunft der Meldung — `QUITTUNG` für jede Meldung des KBA, aus der Quittung (0002) wie aus der Entscheidung (0709).
kind enum
Quittungsart in Worten (Codeliste quittungsart 0/1/2). Fehlt bei den Ablehnungsgründen der 0709 — sie tragen keine Quittungsart.
Hinweis · Warnung · Fehler
code string
**Nicht immer fünfstellig.** Drei Ausprägungen kommen vor: der fünfstellige Quittungscode des KBA (`07077`); der kurze, numerische Ablehnungsgrund der 0709 (Codeliste `grundablehnungzulassungsantrag`, etwa `1` für Steuerrückstände, `2` für Gebührenrückstände); und — bei einer Ablehnung ohne Ablehnungsgrund, dem Regelfall — der Antragsstatus in Worten (Codeliste `statuselektronischerantrag`: neu, geprueft, wartend, weitergeleitet, bearbeitet, abgeschlossen, abgelehnt, eskaliert). Prüfen Sie den Wert nicht auf fünf Stellen.
text string
additional string
Der Zusatztext des KBA. Bei einer abgelehnten Zulassung trägt er den GRUND — die 0709 führt ihn ausdrücklich nicht.
createdAt string (date-time)
updatedAt string (date-time)
businessTransaction enum
Geschaeftsvorfall des Vorgangs — einer der sieben Codes. Wird in jeder Auskunft geliefert; derselbe Wert steht als `businessTransaction` im Webhook-Ereignis.
AB · HA · UG · WG · WZ · NZ · TZ
paymentReference string
Kassenzeichen aus dem Sammelgebuehrenbescheid (0103) — die Zahlungsreferenz. Erst gesetzt, nachdem der Bescheid eingetroffen ist. **Unabhängig von `feeAmountCents`.** Beide stammen aus demselben Bescheid, werden aber einzeln gesetzt: Ein Betrag ohne Kassenzeichen kommt vor. Wer seine Abrechnung auf „wenn `paymentReference` da, dann `feeAmountCents` lesen" baut, verliert diese Beträge.
feeAmountCents integer
Abgerechneter Betrag in ganzen Cent, aus demselben Bescheid. Kann gesetzt sein, ohne dass `paymentReference` es ist — siehe dort.
attempts object[]
**Alle Versuche dieses Auftrags** — der Weg vom Auftrag zu seinen Versuchen. `attemptOf` führt vom Ereignis oder vom Versuch zum Auftrag; dies ist die Gegenrichtung. Sie wird gebraucht, weil die **Übermittlungsgebühr je Versuch anfällt** und der Auftragskopf die Versuche mischt: `state` und `vehicleIdentificationNumber` folgen dem jüngsten Versuch, `paymentReference` und `feeAmountCents` können von einem älteren stammen. Wer über den Kopf abrechnet, bucht die Gebühr des einen und übersieht die des anderen. Die Auftragsliste (`GET …/orders`) führt ausschliesslich Auftragsköpfe — ein Versuch ist dort nicht zu finden, und einen Filter darauf gibt es nicht. Ohne dieses Feld bliebe das Webhook-Ereignis der einzige Weg an eine Versuchs-Id; damit hinge die Abrechnung wieder an dem Kanal, für dessen Ausfall die Auftragsliste gebaut wurde, und ein verlorenes Ereignis wäre dauerhaft nicht heilbar. Ältester Versuch zuerst. Bei einem Auftrag ohne Korrektur enthält die Liste genau einen Eintrag — den Auftrag selbst. Die amtlichen Gebührenangaben stehen hier unter derselben Sichtbarkeitsregel wie am Auftrag: Wer sie dort nicht sieht, sieht sie auch hier nicht.
id* integer
Id dieses Versuchs. Über `GET …/orders/{id}` abrufbar, in `GET …/orders` NICHT enthalten.
attempt* integer
state* enum
angelegt · eingereicht · inBearbeitung · weitergeleitet · beschieden · abgelehnt · fehlgeschlagen
derivedStatus* enum
PENDING · SUCCESS · FAILURE · VEHICLE_UNKNOWN · VEHICLE_ALREADY_DEREGISTERED · LICENSE_PLATE_CODE_INVALID · REGISTRATION_CERTIFICATE_CODE_INVALID · LICENSE_PLATE_CODE_QTY_INVALID · INPUT_INVALID · RESERVATION_IMPOSSIBLE · ERROR_UNHANDLED
applicationId string
Die eigene Antragsnummer dieses Versuchs. Jeder Versuch bekommt beim KBA eine neue — darüber läuft die Rückfrage.
vehicleIdentificationNumber* string
paymentReference string
feeAmountCents integer
retryable boolean
Gesetzt, wenn der Vorgang nur voruebergehend gescheitert ist (Portalausfall, Registerauskunft derzeit nicht moeglich). Derselbe Antrag hat spaeter Aussicht auf Erfolg.
holderDataProvenance object
Der Herkunftsnachweis der Halterdaten — nur bei Anträgen, die sich über `powerOfAttorney.processId` auf einen Vollmachtsvorgang mit Nachweis berufen. Der Fingerabdruck ist derselbe wie am Vollmachtsvorgang; `unchanged` ist hier immer `true`, denn eine Abweichung führt zur Ablehnung, bevor ein Vorgang entsteht.
provider enum
Der Dienst, der die Halterdaten geliefert hat.
nect-sign · nect-business-sign · yousign
providerProcessId string
Kennung des Vorgangs beim Anbieter — darüber kann er ihn im Prüfverfahren bestätigen.
verifiedAt string (date-time)
Zeitpunkt laut Anbieter (die Unterschrift); nennt er keinen, der Eingang des Ergebnisses bei uns.
identitySource string
Was der Anbieter zur Quelle meldet — bei Business Sign `Handelsregister`. Nur vorhanden, wenn er etwas nennt; Nect Sign nennt keine Ausweisart.
fingerprint string
powerOfAttorneyProcessId integer (int64)
Nur an der Vorgangsauskunft — der Vollmachtsvorgang, auf den sich der Antrag beruft.
unchanged boolean
Nur an der Vorgangsauskunft. Ob die Halterdaten des Antrags den gelieferten entsprechen. Verglichen wird, was in die XKfz-Nachricht geht; zulässig sind allein das Entfernen führender und nachgestellter Leerzeichen, die Umwandlung des Datumsformats und die Umschlüsselung des Staats von ISO „DE" auf KBA „D".
deviatingFields string[]
Nur an der Vorgangsauskunft. Leer, wenn `unchanged` — siehe oben.
checkedAt string (date-time)
Nur an der Vorgangsauskunft — Zeitpunkt des Abgleichs.
TYPOrderCreationRequest
externalId* string
Ihre eigene Auftragsnummer.
email* string (email)
deliveryAddress* Address
firstName string
lastName string
companyName string
streetName string
houseNumber string
zipCode string
cityName string
countryCode string
KBA-Staatsschlüssel
invoiceAddress* Address
firstName string
lastName string
companyName string
streetName string
houseNumber string
zipCode string
cityName string
countryCode string
KBA-Staatsschlüssel
items* object[]
productVariantId integer
name string
sku string
quantity* integer
customization object
Z. B. `productType: LICENSE_PLATE` und `licensePlateNumberComponents`.
TYPOrderCreationResponse
id integer
Kennung der Bestellung beim Schilderdienst.
TYPReshippedOrderCreationRequest
returnedDeliveryId* integer
Kennung der Ruecksendung beim Schilderdienst.
externalId* string
deliveryAddress* Address
firstName string
lastName string
companyName string
streetName string
houseNumber string
zipCode string
cityName string
countryCode string
KBA-Staatsschlüssel
invoiceAddress* Address
firstName string
lastName string
companyName string
streetName string
houseNumber string
zipCode string
cityName string
countryCode string
KBA-Staatsschlüssel
TYPEmissionStickerOrderCreationResponse
id integer
TYPLicensePlateReservationAvailabilityCheckRequest
registrationOfficeServiceId* string
Kennung des Reservierungsdienstes der Behoerde.
licensePlateNumberPatternComponents* EuroLicensePlateNumberComponents
usageType enum
Kennzeichenmerkmal — für alle Anträge mit bisherigem Kennzeichen (AB, HA, UG, WG, WZ): EURO (Normalfall), ELECTRIC (Elektrokennzeichen) und HISTORIC (Oldtimerkennzeichen); andere Werte werden mit HTTP 400 abgewiesen.
EURO · ELECTRIC · HISTORIC
city* string
Unterscheidungszeichen, 1–3 Buchstaben (Umlaute zulässig). Kleinbuchstaben werden großgeschrieben; das Muster lässt sie deshalb zu.
middle* string
Erkennungsbuchstaben, 1–2 Buchstaben ohne Umlaute. Kleinbuchstaben werden großgeschrieben.
end* string
Erkennungsnummer, 1–4 Ziffern.
TYPLicensePlateReservationAvailabilityCheckResponse
available boolean
Ist das Kennzeichen frei?
reservationCode string
Vom Portal vergebener Code, falls einer entsteht.
TYPLicensePlateReservationRequest
externalOrderId* string
email* string (email)
customization* object
licensePlateNumberComponents EuroLicensePlateNumberComponents
usageType enum
Kennzeichenmerkmal — für alle Anträge mit bisherigem Kennzeichen (AB, HA, UG, WG, WZ): EURO (Normalfall), ELECTRIC (Elektrokennzeichen) und HISTORIC (Oldtimerkennzeichen); andere Werte werden mit HTTP 400 abgewiesen.
EURO · ELECTRIC · HISTORIC
city* string
Unterscheidungszeichen, 1–3 Buchstaben (Umlaute zulässig). Kleinbuchstaben werden großgeschrieben; das Muster lässt sie deshalb zu.
middle* string
Erkennungsbuchstaben, 1–2 Buchstaben ohne Umlaute. Kleinbuchstaben werden großgeschrieben.
end* string
Erkennungsnummer, 1–4 Ziffern.
vehicleHolder* VehicleDeregistrationRequestVehicleHolder
address Address
firstName string
lastName string
companyName string
streetName string
houseNumber string
zipCode string
cityName string
countryCode string
KBA-Staatsschlüssel
TYPLicensePlateReservationResponse
reservationCode string
validUntil string (date-time)
Bis wann die Reservierung gilt.
TYPEingangsFile
purposeType* enum
RECEIPT ist der Gebührenbescheid als PDF, UNSPECIFIED das XML der Nachricht.
CERTIFICATE · RECEIPT · APPLICATION · UNSPECIFIED
mediaType* string
fileAccessKey* string (password)
Einzulösen über GET /vehicleDeregistrations/files/content/{fileAccessKey}.
expirationTime* string
Zeitpunkt nach ISO 8601, ohne Zeitzone, sekundengenau. Die Schlüssel eines Sammelgebührenbescheids (`gb_…`) und einer Nachricht ohne Vorgang (`ek_…`) gelten 90 Tage ab dem Ablegen — nicht 72 Stunden wie ein Vorgangsbeleg. Die Einzelauskunft (GET /vehicleDeregistrations/feeNotices/{id}, GET /vehicleDeregistrations/unmatchedMessages/{id}) setzt die Frist neu an.
filename* string
Der Name, unter dem der Abruf die Datei ausliefert — nach dem Muster `Datum_Behörde_0|1_Kassenzeichen_Nachrichten-ID.xml|pdf`, wie es kennzeichen.dev verwendet hat.
TYPFeeNoticeItem
number* integer
code string
Gebührennummer nach GebOSt, z. B. 224.2.
name string
amount* integer
Betrag in Cent.
note string
TYPFeeNoticeApplication
applicationId string
Antragsnummer des KBA, 20-stellig.
paymentId string
Kassenzeichen dieses Antrags (Referenztyp 12).
licensePlate string
vehicleIdentificationNumber string
applicationDate string
businessTransaction string
AB
amount* integer
Summe der Positionen in Cent.
items* FeeNoticeItem[]
number* integer
code string
Gebührennummer nach GebOSt, z. B. 224.2.
name string
amount* integer
Betrag in Cent.
note string
assignment* enum
MATCHED — der Antrag gehört zu einem eigenen Vorgang (`order`). UNKNOWN — kein eigener Vorgang trägt diese Antragsnummer; kein Fehler, der Bescheid kann Anträge eines früheren Systems enthalten. AMBIGUOUS — die Antragsnummer steht mehrfach im Bescheid. MISMATCH — ein Vorgang trägt die Nummer, aber das Kennzeichen oder der Vertragspartner passt nicht.
MATCHED · UNKNOWN · AMBIGUOUS · MISMATCH
order object
id* integer (int64)
externalId string
contractPartner string
Kommunikationspartnerschlüssel des Vertragspartners, der den Antrag gestellt hat (Referenztyp 28), z. B. U234567 — nur, wenn die Behörde ihn nennt.
TYPFeeNotice
id* integer
messageId* string
Nachrichten-ID des KBA — eindeutig, auch bei erneuter Zustellung.
receivedAt* string
Wann die Nachricht hier ankam, ohne Zeitzone, sekundengenau.
issuedAt string
zeitpunktDerErstellung laut Nachrichtenkopf, wie das KBA ihn schreibt.
issuer* object
partnerKey* string
Kommunikationspartnerschlüssel der Zulassungsbehörde, z. B. B115779.
districtKey* string
Kreisschlüssel samt Zusatzziffer des Gebührengläubigers, z. B. 010010.
debtor* object
partnerKey* string
Kommunikationspartnerschlüssel des Gebührenschuldners — die eigene KoPa.
bank* object
accountHolder* string
iban* string
directDebit* boolean
true, wenn die Behörde per SEPA-Lastschrift einzieht — dann wird nicht überwiesen.
paymentReference string
Verwendungszweck laut Bescheid, meist Bescheidnummer und Kassenzeichen.
paymentId string
Kassenzeichen des Bescheids, sofern die Behörde eines eigens nennt.
dueDate string
amount* integer
Gesamtbetrag in Cent — der der Nachricht, nicht eine eigene Addition. Bei einem geteilten Bescheid die Summe sämtlicher Anträge aus der letzten Nachricht.
currency* string
noticeNumber string
Nummer des Gebührenbescheids laut Nachricht.
part object
Teil n von m laut Bescheidkopf (XKfz 6.0). Ab mehr als 500 Anträgen teilt die Behörde den Bescheid auf mehrere Nachrichten; nur die letzte trägt Gesamtbetrag, Bankverbindung, Kassenzeichen und PDF. Ein geteilter Bescheid erscheint deshalb nur einmal, mit seiner abschließenden Nachricht (der mit Gesamtbetrag), und `applications` enthält die Anträge aller bis dahin eingegangenen Teile. `part` gibt die Zählung laut Bescheidkopf wieder; sie kann auch eigenständige Bescheide eines Abrechnungszeitraums zählen, `part.number` muss also nicht `part.of` sein. Trifft ein früherer Teil erst danach ein, kommt das Ereignis erneut — mit derselben `id`, derselben `messageId`, demselben `amount` und der ergänzten Antragsliste.
number* integer
of* integer
applicationCount* integer
Anzahl der abgerechneten Anträge laut Nachricht; mindestens die Zahl der mitgeführten. Liegt sie über `applications`, fehlen noch Teile.
assignedCount* integer
Wie viele der Anträge zu einem eigenen Vorgang gehören.
applications* FeeNoticeApplication[]
applicationId string
Antragsnummer des KBA, 20-stellig.
paymentId string
Kassenzeichen dieses Antrags (Referenztyp 12).
licensePlate string
vehicleIdentificationNumber string
applicationDate string
businessTransaction string
AB
amount* integer
Summe der Positionen in Cent.
items* FeeNoticeItem[]
number* integer
code string
Gebührennummer nach GebOSt, z. B. 224.2.
name string
amount* integer
Betrag in Cent.
note string
assignment* enum
MATCHED — der Antrag gehört zu einem eigenen Vorgang (`order`). UNKNOWN — kein eigener Vorgang trägt diese Antragsnummer; kein Fehler, der Bescheid kann Anträge eines früheren Systems enthalten. AMBIGUOUS — die Antragsnummer steht mehrfach im Bescheid. MISMATCH — ein Vorgang trägt die Nummer, aber das Kennzeichen oder der Vertragspartner passt nicht.
MATCHED · UNKNOWN · AMBIGUOUS · MISMATCH
order object
id* integer (int64)
externalId string
contractPartner string
Kommunikationspartnerschlüssel des Vertragspartners, der den Antrag gestellt hat (Referenztyp 28), z. B. U234567 — nur, wenn die Behörde ihn nennt.
files* EingangsFile[]
purposeType* enum
RECEIPT ist der Gebührenbescheid als PDF, UNSPECIFIED das XML der Nachricht.
CERTIFICATE · RECEIPT · APPLICATION · UNSPECIFIED
mediaType* string
fileAccessKey* string (password)
Einzulösen über GET /vehicleDeregistrations/files/content/{fileAccessKey}.
expirationTime* string
Zeitpunkt nach ISO 8601, ohne Zeitzone, sekundengenau. Die Schlüssel eines Sammelgebührenbescheids (`gb_…`) und einer Nachricht ohne Vorgang (`ek_…`) gelten 90 Tage ab dem Ablegen — nicht 72 Stunden wie ein Vorgangsbeleg. Die Einzelauskunft (GET /vehicleDeregistrations/feeNotices/{id}, GET /vehicleDeregistrations/unmatchedMessages/{id}) setzt die Frist neu an.
filename* string
Der Name, unter dem der Abruf die Datei ausliefert — nach dem Muster `Datum_Behörde_0|1_Kassenzeichen_Nachrichten-ID.xml|pdf`, wie es kennzeichen.dev verwendet hat.
TYPUnmatchedMessage
id* integer
messageType* string
Nachrichtentyp des KBA, z. B. 0709 (Antragskopie/Bescheid) oder 0002 (Quittung).
messageId string
receivedAt* string
issuedAt string
issuer* object
partnerKey* string
recipient* object
partnerKey* string
applicationId string
vehicleIdentificationNumber string
licensePlate string
businessTransaction string
status string
Antragsstatus laut Nachricht, z. B. bearbeitet, abgelehnt oder — seit XKfz 6.0 in der finalen Zulassungsnachricht — abgeschlossen.
statusTime string
processingKind string
Bearbeitungsart laut Nachricht, z. B. A für automatisiert.
decision enum
APPROVED · REJECTED · UNKNOWN
messages object[]
Die Quittungseinträge, sofern die Nachricht eine Quittung ist.
state* enum
OPEN · HANDLED · IGNORED
order object
id* integer (int64)
files* EingangsFile[]
purposeType* enum
RECEIPT ist der Gebührenbescheid als PDF, UNSPECIFIED das XML der Nachricht.
CERTIFICATE · RECEIPT · APPLICATION · UNSPECIFIED
mediaType* string
fileAccessKey* string (password)
Einzulösen über GET /vehicleDeregistrations/files/content/{fileAccessKey}.
expirationTime* string
Zeitpunkt nach ISO 8601, ohne Zeitzone, sekundengenau. Die Schlüssel eines Sammelgebührenbescheids (`gb_…`) und einer Nachricht ohne Vorgang (`ek_…`) gelten 90 Tage ab dem Ablegen — nicht 72 Stunden wie ein Vorgangsbeleg. Die Einzelauskunft (GET /vehicleDeregistrations/feeNotices/{id}, GET /vehicleDeregistrations/unmatchedMessages/{id}) setzt die Frist neu an.
filename* string
Der Name, unter dem der Abruf die Datei ausliefert — nach dem Muster `Datum_Behörde_0|1_Kassenzeichen_Nachrichten-ID.xml|pdf`, wie es kennzeichen.dev verwendet hat.
TYPFeeNoticeList
feeNotices* FeeNotice[]
id* integer
messageId* string
Nachrichten-ID des KBA — eindeutig, auch bei erneuter Zustellung.
receivedAt* string
Wann die Nachricht hier ankam, ohne Zeitzone, sekundengenau.
issuedAt string
zeitpunktDerErstellung laut Nachrichtenkopf, wie das KBA ihn schreibt.
issuer* object
partnerKey* string
Kommunikationspartnerschlüssel der Zulassungsbehörde, z. B. B115779.
districtKey* string
Kreisschlüssel samt Zusatzziffer des Gebührengläubigers, z. B. 010010.
debtor* object
partnerKey* string
Kommunikationspartnerschlüssel des Gebührenschuldners — die eigene KoPa.
bank* object
accountHolder* string
iban* string
directDebit* boolean
true, wenn die Behörde per SEPA-Lastschrift einzieht — dann wird nicht überwiesen.
paymentReference string
Verwendungszweck laut Bescheid, meist Bescheidnummer und Kassenzeichen.
paymentId string
Kassenzeichen des Bescheids, sofern die Behörde eines eigens nennt.
dueDate string
amount* integer
Gesamtbetrag in Cent — der der Nachricht, nicht eine eigene Addition. Bei einem geteilten Bescheid die Summe sämtlicher Anträge aus der letzten Nachricht.
currency* string
noticeNumber string
Nummer des Gebührenbescheids laut Nachricht.
part object
Teil n von m laut Bescheidkopf (XKfz 6.0). Ab mehr als 500 Anträgen teilt die Behörde den Bescheid auf mehrere Nachrichten; nur die letzte trägt Gesamtbetrag, Bankverbindung, Kassenzeichen und PDF. Ein geteilter Bescheid erscheint deshalb nur einmal, mit seiner abschließenden Nachricht (der mit Gesamtbetrag), und `applications` enthält die Anträge aller bis dahin eingegangenen Teile. `part` gibt die Zählung laut Bescheidkopf wieder; sie kann auch eigenständige Bescheide eines Abrechnungszeitraums zählen, `part.number` muss also nicht `part.of` sein. Trifft ein früherer Teil erst danach ein, kommt das Ereignis erneut — mit derselben `id`, derselben `messageId`, demselben `amount` und der ergänzten Antragsliste.
number* integer
of* integer
applicationCount* integer
Anzahl der abgerechneten Anträge laut Nachricht; mindestens die Zahl der mitgeführten. Liegt sie über `applications`, fehlen noch Teile.
assignedCount* integer
Wie viele der Anträge zu einem eigenen Vorgang gehören.
applications* FeeNoticeApplication[]
applicationId string
Antragsnummer des KBA, 20-stellig.
paymentId string
Kassenzeichen dieses Antrags (Referenztyp 12).
licensePlate string
vehicleIdentificationNumber string
applicationDate string
businessTransaction string
AB
amount* integer
Summe der Positionen in Cent.
items* FeeNoticeItem[]
number* integer
code string
Gebührennummer nach GebOSt, z. B. 224.2.
name string
amount* integer
Betrag in Cent.
note string
assignment* enum
MATCHED — der Antrag gehört zu einem eigenen Vorgang (`order`). UNKNOWN — kein eigener Vorgang trägt diese Antragsnummer; kein Fehler, der Bescheid kann Anträge eines früheren Systems enthalten. AMBIGUOUS — die Antragsnummer steht mehrfach im Bescheid. MISMATCH — ein Vorgang trägt die Nummer, aber das Kennzeichen oder der Vertragspartner passt nicht.
MATCHED · UNKNOWN · AMBIGUOUS · MISMATCH
order object
id* integer (int64)
externalId string
contractPartner string
Kommunikationspartnerschlüssel des Vertragspartners, der den Antrag gestellt hat (Referenztyp 28), z. B. U234567 — nur, wenn die Behörde ihn nennt.
files* EingangsFile[]
purposeType* enum
RECEIPT ist der Gebührenbescheid als PDF, UNSPECIFIED das XML der Nachricht.
CERTIFICATE · RECEIPT · APPLICATION · UNSPECIFIED
mediaType* string
fileAccessKey* string (password)
Einzulösen über GET /vehicleDeregistrations/files/content/{fileAccessKey}.
expirationTime* string
Zeitpunkt nach ISO 8601, ohne Zeitzone, sekundengenau. Die Schlüssel eines Sammelgebührenbescheids (`gb_…`) und einer Nachricht ohne Vorgang (`ek_…`) gelten 90 Tage ab dem Ablegen — nicht 72 Stunden wie ein Vorgangsbeleg. Die Einzelauskunft (GET /vehicleDeregistrations/feeNotices/{id}, GET /vehicleDeregistrations/unmatchedMessages/{id}) setzt die Frist neu an.
filename* string
Der Name, unter dem der Abruf die Datei ausliefert — nach dem Muster `Datum_Behörde_0|1_Kassenzeichen_Nachrichten-ID.xml|pdf`, wie es kennzeichen.dev verwendet hat.
limit* integer
offset* integer
total* integer
hasMore* boolean
TYPUnmatchedMessageList
messages* UnmatchedMessage[]
id* integer
messageType* string
Nachrichtentyp des KBA, z. B. 0709 (Antragskopie/Bescheid) oder 0002 (Quittung).
messageId string
receivedAt* string
issuedAt string
issuer* object
partnerKey* string
recipient* object
partnerKey* string
applicationId string
vehicleIdentificationNumber string
licensePlate string
businessTransaction string
status string
Antragsstatus laut Nachricht, z. B. bearbeitet, abgelehnt oder — seit XKfz 6.0 in der finalen Zulassungsnachricht — abgeschlossen.
statusTime string
processingKind string
Bearbeitungsart laut Nachricht, z. B. A für automatisiert.
decision enum
APPROVED · REJECTED · UNKNOWN
messages object[]
Die Quittungseinträge, sofern die Nachricht eine Quittung ist.
state* enum
OPEN · HANDLED · IGNORED
order object
id* integer (int64)
files* EingangsFile[]
purposeType* enum
RECEIPT ist der Gebührenbescheid als PDF, UNSPECIFIED das XML der Nachricht.
CERTIFICATE · RECEIPT · APPLICATION · UNSPECIFIED
mediaType* string
fileAccessKey* string (password)
Einzulösen über GET /vehicleDeregistrations/files/content/{fileAccessKey}.
expirationTime* string
Zeitpunkt nach ISO 8601, ohne Zeitzone, sekundengenau. Die Schlüssel eines Sammelgebührenbescheids (`gb_…`) und einer Nachricht ohne Vorgang (`ek_…`) gelten 90 Tage ab dem Ablegen — nicht 72 Stunden wie ein Vorgangsbeleg. Die Einzelauskunft (GET /vehicleDeregistrations/feeNotices/{id}, GET /vehicleDeregistrations/unmatchedMessages/{id}) setzt die Frist neu an.
filename* string
Der Name, unter dem der Abruf die Datei ausliefert — nach dem Muster `Datum_Behörde_0|1_Kassenzeichen_Nachrichten-ID.xml|pdf`, wie es kennzeichen.dev verwendet hat.
limit* integer
offset* integer
total* integer
hasMore* boolean
TYPUnmatchedMessageStateRequest
state* enum
OPEN · HANDLED · IGNORED
orderId integer
Der eigene Vorgang, dem die Nachricht zugeordnet wurde — nur mit HANDLED sinnvoll.