Erste Schritte

Vom API-Schlüssel zum Ergebnis

Erste Schritte mit der i-Kfz Fahrzeugzulassung API: Testschlüssel erstellen, Testhalter anlegen, Antrag senden und Ergebnisse abrufen – ohne Übermittlung an das KBA.

Was Sie benötigen

Einen bestätigten Digital-Zulassen Dashboard-Zugang mit Zugriff auf das Unternehmenskonto.
Einen Testschlüssel mit Präfix dz_test_. Der vollständige Wert wird nur einmal bei der Erstellung angezeigt.
Eine eindeutige Referenz aus Ihrem System, beispielsweise eine Auftrags- oder Fuhrparknummer.

Was dieser Schnellstart zeigt

Der Schnellstart geht den vollständigen Weg der Zulassung für Dritte: Kunde als Halter anlegen, verifizieren, Antrag senden, Signatur einholen. Bei der Eigenzulassung — eigene Fahrzeuge, ohne holder_id — entfallen die Schritte 2, 3 und 5. Die Unterschiede erklärt Eigenzulassung und Zulassung für Dritte.

1. Testschlüssel hinterlegen

Erstellen Sie den Schlüssel ausschließlich in der geschützten Schlüsselverwaltung des Dashboards und speichern Sie ihn anschließend in einem Secret Store. Für einen ersten lokalen Aufruf genügt eine Umgebungsvariable.

export DZ_API_KEY='dz_test_••••••••••••••••••••'

2. Test-Halter anlegen

Legen Sie den Halter über POST /api/v1/holders an und speichern Sie die zurückgegebene hld_test_…-ID. Die Umgebung wird am Schlüssel erkannt; der Ressourcenpfad ist in Test und Live identisch.

curl --request POST 'https://digital-zulassen.de/api/v1/holders' \
  --header "Authorization: Bearer $DZ_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: quickstart-holder-0042' \
  --data '{
    "type": "person",
    "first_name": "Mara",
    "last_name": "Beispiel",
    "birth_date": "1988-04-12",
    "address": {
      "street": "Am Markt",
      "house_number": "12",
      "postal_code": "28195",
      "city": "Bremen",
      "country_code": "DE"
    },
    "external_reference": "quickstart-holder-0042"
  }'

3. Test-Halter verifizieren

Reichen Sie mit Vollmacht auf Digital-Zulassen ein, muss der Halter verifiziert sein. Starten Sie einen Test-Prüfversuch und übertragen Sie alle angeforderten Slots gemeinsam. Ersetzen Sie die Beispiel-IDs durch die IDs Ihrer Responses und verwenden Sie künstliche Testdateien.

curl --request POST \
  'https://digital-zulassen.de/api/v1/holders/hld_test_1a2b3c4d5e6f708192a3b4c5/verifications' \
  --header "Authorization: Bearer $DZ_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: quickstart-verification-0042' \
  --data '{"document_variant":"id_card"}'

curl --request POST \
  'https://digital-zulassen.de/api/v1/holder-verifications/hvr_test_2b3c4d5e6f708192a3b4c5d6/documents' \
  --header "Authorization: Bearer $DZ_API_KEY" \
  --header 'Idempotency-Key: quickstart-verification-documents-0042' \
  --form 'front=@./test-ausweis-vorne.png;type=image/png' \
  --form 'back=@./test-ausweis-hinten.png;type=image/png'

4. Testantrag anlegen

Senden Sie die verifizierte holder_id an den Testendpunkt. Jeder neue Antrag erhält einen eigenen Idempotency-Key. Bei AB kann der Halter entfallen; Halterverifizierung und Signatur sind nicht erforderlich.

curl --request POST 'https://digital-zulassen.de/api/v1/test/applications' \
  --header "Authorization: Bearer $DZ_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: quickstart-test-2026-0042' \
  --data '{
    "procedure": "NZ",
    "holder_id": "hld_test_1a2b3c4d5e6f708192a3b4c5",
    "external_reference": "quickstart-0042",
    "vehicle": {
      "vin": "WVWZZZ1JZXW000001",
      "type": "car",
      "drive_type": "combustion",
      "evb_number": "ABCD123"
    },
    "registration": {
      "certificate_part_2": {
        "number": "ZB2A123456",
        "security_code": "B1234567890X"
      },
      "license_plate": { "option": "next_available" }
    },
    "payment": { "iban": "DE89370400440532013000", "tax_exempt": false },
    "signer": { "email": "signatur-test@beispiel-mobilitaet.example" }
  }'

5. Signatur einholen

Die Anlage antwortet mit status: awaiting_signature und next_action.type: sign_application. Öffnen Sie die URL im Browser der signierenden Person oder übergeben Sie sie über Ihren eigenen geschützten Prozess.

Signaturlinks enthalten Zugriffstoken. Schreiben Sie sie nicht in öffentliche Logs, Analytics-Parameter oder Support-Tickets.

6. Ergebnis simulieren

Nach dem Signaturschritt können Sie über den Testereignis-Endpunkt weitere Zustände setzen.

for EVENT in signature.completed processing.started application.completed; do
  curl --request POST \
    'https://digital-zulassen.de/api/v1/test/applications/app_test_1a2b3c4d5e6f708192a3b4c5/events' \
    --header "Authorization: Bearer $DZ_API_KEY" \
    --header 'Content-Type: application/json' \
    --data "{\"type\":\"$EVENT\"}"
done

7. Status und Ergebnisse abrufen

01
Antrag lesen
GET /api/v1/applications/{id} liefert Antragsstatus und nächste Aktion.
02
Dokumente listen
GET /api/v1/applications/{id}/documents liefert bereitgestellte Dateien.
03
Gebühren lesen
GET /api/v1/applications/{id}/fees liefert Cent-Beträge und verfügbare Gebührenbescheide.

Antrag lesen

Dokumente listen

Gebühren lesen