API-Schnittstelle
Die API-Schnittstelle ermöglicht es akkreditierten Partnern, direkt und strukturiert auf zentrale Funktionen unserer Plattform zuzugreifen. Als digitaler Zugangspunkt wurde die Schnittstelle speziell dafür entwickelt, bestehende Arbeitsprozesse effizient zu ergänzen und eine nahtlose Integration in externe Systeme zu ermöglichen. Im Mittelpunkt steht dabei der sichere und standardisierte Austausch von zertifikatsrelevanten Daten rund um Altfahrzeuge.
1. Authentifizierung & Berechtigungen
Um auf die REST-API zugreifen zu können, ist eine Authentifizierung erforderlich. Nur registrierte Partner mit gültiger Partner-ID erhalten Zugang zu den Schnittstellenfunktionen.
Zugangsdaten
Bei jeder Anfrage müssen folgende Informationen übermittelt werden:
| Parameter | Beschreibung | Pflicht |
|---|---|---|
partner_id |
Eindeutige Partnerkennung | ✅ |
api_key |
Persönlicher API-Schlüssel des Nutzers | ✅ |
Diese Angaben werden im Request-Body gesendet. Die Übertragung erfolgt verschlüsselt.
Beispielstruktur einer Anfrage
Die Authentifizierungsdaten werden nicht in der URL, sondern im Body übermittelt – im Format application/x-www-form-urlencoded.
2. Nutzer-Login-Link erstellen
Mit dieser Funktion kann ein temporärer Login-Link für unsere Plattform generiert werden. Der Link ermöglicht autorisierten Nutzern den direkten Zugang zu einem Zertifikatsvorgang – ohne separates Login, aber dennoch abgesichert über eine einmalige Gültigkeit (30 Minuten) und Token-Verifizierung.
Endpoint:
GET /wp-json/afz-api/v1/get-user-login-link/
| Parameter | Beschreibung | Pflicht |
|---|---|---|
case_number |
Interne Fallnummer/ Identifikationsnummer des Partners | ✅ |
vin |
Fahrzeug-Identifizierungsnummer | ✅ |
vehicle_registration_date |
Erstzulassungsdatum | ✅ |
initial_price |
Neupreis des Fahrzeugs | optional |
replacement_value |
Wiederbeschaffungswert des Fahrzeugs | ✅ |
trade_name |
Handelsbezeichnung des Fahrzeugs | ✅ |
certificate_date |
Datum/Stichtag des Zertifikats | ✅ |
vehicle_operational_safety |
Betriebsfähigkeit des Fahrzeugs | ✅ |
Weitere Details zu den erforderlichen Datenformaten und Eingaberegeln finden Sie im Abschnitt Validierung.
Beispielaufruf
Erfolgreiche Antwort (200)
3. Altfahrzeug-Zertifikat herunterladen
Über diese Schnittstellenfunktion kann ein vorhandenes Altfahrzeug-Zertifikat zu einem bestimmten Schadensfall digital abgerufen werden. Die Ausgabe erfolgt im PDF-Format, verschlüsselt als Base64-kodierter String. Zusätzlich wird das Erstellungsdatum des Zertifikats als Unix-Zeitstempel mitgeliefert.
Endpoint:
GET /wp-json/afz-api/v1/get-certificate/
| Parameter | Beschreibung | Pflicht |
|---|---|---|
case_number |
Interne Fallnummer/ Identifikationsnummer des Partners | ✅ |
Beispielaufruf
Erfolgreiche Antwort (200)
Technisches Beispiel zur Umsetzung
Ein Beispiel, wie das Zertifikat über die API abgerufen werden kann – inklusive Übergabe der Authentifizierungsdaten und Interpretation der Base64-Ausgabe – finden Sie auf folgender Seite:
Beispiel-Code (PHP) zur Zertifikatsabfrage ansehen
Dort wird Ihnen exemplarisch aufgezeigt, wie die Schnittstelle in ein bestehendes System integriert werden kann.
4. Validierung
| Parameter | Regeln & Anforderungen |
|---|---|
case_number |
Alphanumerisch, mindestens 1 Zeichen |
vin |
1–17 Zeichen, nur Großbuchstaben und Zahlen (ausgenommen: O, I, Q) |
vehicle_registration_date |
Format: YYYY-MM-DD, nicht in der Zukunft, nicht vor 1886 |
certificate_date |
Format: YYYY-MM-DD, darf nicht vor dem Erstzulassungsdatum (vehicle_registration_date) liegen |
initial_price |
Gültige Dezimalzahl im Format 12345.67, keine Kommas, Leerzeichen und ohne Tausendertrennzeichen |
replacement_value |
Gültige Dezimalzahl im Format 12345.67, keine Kommas, Leerzeichen und ohne Tausendertrennzeichen |
trade_name |
Mindestens 1 Zeichen |
vehicle_operational_safety |
Boolescher Wert: (1 = ja / 0 = nein) |
Hinweis: Die API verwendet eine Anfragenbegrenzung, um die Anzahl der Anfragen pro Zeitraum zu begrenzen. Wenn das Limit erreicht ist, wird eine Fehlermeldung mit dem Statuscode 429 zurückgegeben. Aktuell sind 10 Anfragen pro Minute pro Nutzer eingestellt.
5. Fehlerbehandlung
Die API gibt bei Fehlern entsprechende Statuscodes und Fehlermeldungen zurück. Beispiele hierfür sind:
| Code | Fehlerbeschreibung |
|---|---|
400 Bad Request |
Bei ungültigen Parametern |
401 Unauthorized |
Wenn die Authentifizierung fehlschlägt |
402 Payment Required |
Wenn das SEPA-Mandat bei AFZ noch nicht erteilt wurde |
404 Not Found |
Wenn kein Zertifikat für die angegebene Fallnummer gefunden wurde |
429 Too Many Requests |
Wenn das Rate-Limit erreicht wurde |