Umgebungen und Versionen

Zwei Instanzen

Die beiden Instanzen sind getrennt: API-Benutzer, Webhooks, Vollmachtsvorgänge und Vorgänge der einen gibt es auf der anderen nicht. Legen Sie Zugänge und Webhooks auf beiden Instanzen getrennt an.

Die KBA-Testumgebung ist eine echte Umgebung des KBA. Sie prüft, ob sie das Fahrzeug kennt, und weist Anträge zu unbekannten Fahrzeugen ab. Womit sich dort üben lässt, steht unter Testumgebung und Testdaten.

Ob ein einzelner Zugang produktiv sendet, hängt am GKS-Zugang, nicht am Server: Ein Mandant kann mehrere Zugänge führen und wählt je Antrag über gksConfigurationId. Ein Zugang in der Testumgebung gerät nicht auf die Produktionsstrecke. Solange der Betreiber die Produktion für einen Mandanten nicht freigegeben hat, antwortet ein Antrag über einen produktiven Zugang mit 403 — ebenso POST /powerOfAttorneys auf der Produktionsinstanz, denn ein Vorgang bei Nect kostet dort Geld.

Versionen

Produktversion und freigegebene Vorgangsarten

Welche Geschäftsvorfälle eine Instanz annimmt, hängt an der Produktversion, mit der sie beim KBA sendet:

API- und Webhook-Vertrag sind Konstanten dieser Software; die Produktversion ist es nicht. Sie wird je Instanz eingestellt, und Produktion und Test-Instanz können verschiedene Versionen führen. Diese Seite sagt deshalb nicht zu, mit welcher Version eine bestimmte Instanz sendet — das steht unter Diese Instanz am Ende der Seite, erzeugt aus der Einstellung der Instanz, die die Seite gerade ausliefert.

Einen Geschäftsvorfall außerhalb des Umfangs beantwortet eine Instanz mit 403 und der Begründung „… ist noch nicht freigegeben", bevor der Rumpf geprüft wird.

Kompatibilität zu kennzeichen.dev

Ein bestehender Client von kennzeichen.dev wechselt durch Umstellen des Hosts. Gleich geblieben sind:

• der Pfadaufbau /dropshipping-api/{clientId}/2.3.0/… und HTTP Basic Authentication,
• der Antrag der Außerbetriebsetzung POST /vehicleDeregistrations/deregistrations und seine Antwort { "order": { "id": … } },
• das Fehlerformat { "error": … }, hier ergänzt um traceId,
• der Webhook: Rumpf nach Webhooks 3.1.0, Kopfzeilen X-Signature, X-Webhook-Id, X-Webhook-Version, Wiederholung bei ausbleibender Bestätigung,
• das Vokabular von status und derivedStatus im Ereignis, einschließlich messages[].type QUITTUNG.

Hinzugekommen sind — alles zusätzlich, ein bestehender Aufrufer merkt davon nichts:

• die übrigen Geschäftsvorfälle: vehicleHolderChanges, vehicleTransfers, vehicleReRegistrations (zwei Endpunkte), vehicleRegistrations (zwei Endpunkte),
• Vollmachtsvorgänge: POST /powerOfAttorneys, GET /powerOfAttorneys/{processId},
• Auftragsliste und Vorgangsauskunft unter allen fünf Präfixen: GET …/orders, GET …/orders/{orderId},
• für die Außerbetriebsetzung die optionalen Felder recycling, vehicleRegistrationCertificatePartII, vehicleRegistrationCertificateNumber und contractPartner,
• GET /registrationOffices/{districtKey}/availability, GET /serviceStatus, GET /invoices,
• Sammelgebührenbescheide und Nachrichten ohne Vorgang: GET /vehicleDeregistrations/feeNotices, GET /vehicleDeregistrations/unmatchedMessages samt Ereignissen,
• im Webhook-Rumpf unter anderem businessTransaction, licensePlate, attemptOf, attempt, retryable, registrationData, registrationDocumentsReady, parties und files[].filename,
• die Kopfzeile X-Event-Id an jeder Zustellung.

Die GKS-Zugänge /gksConfigurations (POST, PUT, DELETE und zwei GET auf …/overviews) werden vertragstreu bedient; über sie verwaltet ein Mandant seine eigenen KBA-Identitäten. Beschrieben sind sie unter Kfz-Steuer, Lieferung, Vertragspartner.

Nicht bedient werden die Kennzeichenreservierung (POST /licensePlateReservations/availabilityChecks, POST /licensePlateReservations/reservations antworten mit 501). Physische Bestellungen (POST /orders, POST /orders/emissionStickerOrders, POST /orders/reshippedOrders) werden an einen Schilderdienst weitergereicht, wenn einer hinterlegt ist; sonst antworten sie mit 501, und kommt die Weitergabe nicht zustande, mit 502.

400 kommt vor 501. Ein nicht bedienter Endpunkt prüft zuerst die Pflichtfelder des Rumpfs: Fehlt eines, antwortet er mit 400 und dem Hinweis, dass er mit vollständigem Rumpf ohnehin 501 gäbe. So lässt sich schon heute gegen ihn bauen. Ein 400 von dort ist also kein Zeichen dafür, dass der Vorgang angeboten wird.

Kopfzeilen jeder Antwort

Jede Antwort — API, /health, Dashboard und diese Dokumentation — trägt vier Kopfzeilen:

Für eine Anbindung ändert sich damit nichts: Die Kopfzeilen betreffen den Browser, nicht den HTTP-Client. Wer das Dashboard in einen eigenen Rahmen (iframe) stellen wollte, kann das nicht mehr — das ist Absicht, denn ein gerahmtes Formular trägt die echte Herkunft mit und käme damit an der Herkunftsprüfung vorbei. Strict-Transport-Security setzt der Reverse Proxy vor der Anwendung, nicht die Anwendung selbst.

Betriebszustand

GET /health ist ohne Anmeldung erreichbar und antwortet immer mit 200. Es steht außerhalb des Kundenvertrags und hat deshalb keinen paths-Eintrag in spec/api.yaml: Der Pfad trägt weder das Präfix /dropshipping-api/ noch die Mandantennummer.

status, apiVersion und gksLogin stehen immer. Die übrigen Felder fallen weg, wenn es nichts zu melden gibt: overdueOrders und stalledPowerOfAttorneys nur bei einer Zahl über null, trustService, trustServiceLegalPersons, sepaMandateTemplate, returnChannel, signatureCertificate und gksCertificates nur, wenn diese Instanz das Betreffende überhaupt führt. Fragen Sie die Felder deshalb mit einer Vorgabe ab, statt sie vorauszusetzen. Namen, Kennungen und Vorgangsnummern nennt /health nie — wer wissen will, wer betroffen ist, meldet sich an.

gksCertificates.needAttention zählt Zertifikate, die in den nächsten 60 Tagen ablaufen, bereits abgelaufen sind, länger als ein Jahr laufen — oder deren Datei fehlt bzw. sich nicht lesen lässt. Die X.509-Version prüft es nicht: Ein hinterlegtes v1-Zertifikat signiert weiter und fällt hier nicht auf.

/health belegt keinen Kontakt zum KBA: gksLogin: ok heißt nur, dass keine Anmeldesperre besteht. Störungen und Wartungen, die der Betrieb meldet, liefert angemeldet GET /serviceStatus — mit operational, den aktiven Meldungen (announcements) und den angekündigten (scheduled).

Diese Instanz

Produktversion im Nachrichtenkopf jedes Antrags an das KBA: POWRdrive 1.0.0. Freigegeben ist bisher die Außerbetriebsetzung. Die übrigen Geschäftsvorfälle kommen mit der Umstellung auf POWRdrive 2.0.0 dazu; das KBA hat diese Version am 14.09.2026 eingetragen.

Die Angabe gilt für die Instanz, die diese Seite ausliefert. Die jeweils andere Instanz kann eine andere Version führen — lesen Sie diesen Abschnitt dort erneut.