Anleitung zur Integration der API zur Überprüfung von Personalausweis-Fotos

​

Antragsprozess

📘 Vollständige Dokumentation: API zur Überprüfung von Personalausweis-Fotos →

​

Grundlegende Nutzung

• accept: In welchem Format Sie die Antwort erhalten möchten, hier eingetragen als application/json, also im JSON-Format.
• authorization: Der Schlüssel zur API, den Sie nach der Beantragung direkt auswählen können.

• image_url: Der Link zum zu verarbeitenden Personalausweisbild.
• config: Optionale Konfiguration, boolesches Feld, standardmäßig alle auf false, unterstützt copy_warn, border_check_warn, reshoot_warn, detect_ps_warn, temp_id_warn, quality (Schwellenwert 0-100).

{
  "sim": 99.76,
  "result": "Success",
  "description": "Erfolg",
  "name": "Name auf dem Personalausweis",
  "sex": "Geschlecht auf dem Personalausweis",
  "nation": "Nationalität auf dem Personalausweis",
  "birth": "Geburtsdatum auf dem Personalausweis",
  "address": "Wohnadresse auf dem Personalausweis",
  "id_num": "Personalausweisnummer",
  "portrait": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAEBAQEBAQEBAQEBAQEBAQEBAQEBA.....DEhE2lbPMcOtG3f/DLT/yX8if7Kxn/AD7h85wdttPifRf1e6//2Q==",
  "warnings": "",
  "quality": 0,
  "encryption": null
}

• sim, Ähnlichkeit, Wertebereich [0.00, 100.00]. Es wird empfohlen, eine Ähnlichkeit von mindestens 70 zu verwenden, um als dieselbe Person zu gelten. Der Schwellenwert kann je nach spezifischem Szenario angepasst werden (der Fehlerrate bei einem Schwellenwert von 70 beträgt eins zu tausend, bei einem Schwellenwert von 80 eins zu zehntausend).
• result, Geschäftsfehlercode, bei Erfolg wird „Success“ zurückgegeben, bei Fehlern siehe die Liste der Fehlercodes im Abschnitt „FailedOperation“.
• description, hier das Ergebnis der Überprüfung von Name und Personalausweisnummer.
• name, die Namensinformation auf dem Personalausweis, wenn kein Personalausweisbild hochgeladen wurde, ist es leer.
• sex, die Geschlechtsinformation auf dem Personalausweis, wenn kein Personalausweisbild hochgeladen wurde, ist es leer.
• nation, die Nationalitätsinformation auf dem Personalausweis, wenn kein Personalausweisbild hochgeladen wurde, ist es leer.
• birth, die Geburtsinformation auf dem Personalausweis, wenn kein Personalausweisbild hochgeladen wurde, ist es leer.
• address, die Wohnadresse auf dem Personalausweis, wenn kein Personalausweisbild hochgeladen wurde, ist es leer.
• id_num, die Personalausweisnummer auf dem Personalausweis, wenn kein Personalausweisbild hochgeladen wurde, ist es leer.
• portrait, die base64-Codierung des Personalausweisfotos, wenn das Ausschneiden fehlschlägt, wird das gesamte Personalausweisbild zum Vergleich verwendet und gibt leer zurück.
• warnings, Warninformationen, wenn in der Konfiguration Warninformationen festgelegt sind, wird der Personenvergleich gestoppt, das Ergebnis gibt einen Fehler zurück (FailedOperation.OcrWarningOccurred) und enthält diese Warninformationen.
• quality, Bildqualitätsbewertung, wenn in der Anfragekonfiguration eine Warnung für verschwommene Bilder festgelegt ist, hat dieser Parameter Bedeutung, Wertebereich (0–100), derzeit liegt der Standardwert bei 50 Punkten, unter 50 Punkten wird eine Warnung für verschwommene Bilder ausgelöst.
• encryption, Informationen zur Verschlüsselung sensibler Daten.

curl -X POST 'https://api.acedata.cloud/identity/idcard/check-1e' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "image_url": {image_url}
}'

import requests

url = "https://api.acedata.cloud/identity/idcard/check-1e"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "image_url": {image_url}
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

​

Fehlerbehandlung

• 400 token_mismatched: Ungültige Anfrage, möglicherweise aufgrund fehlender oder ungültiger Parameter.
• 400 api_not_implemented: Ungültige Anfrage, möglicherweise aufgrund fehlender oder ungültiger Parameter.
• 401 invalid_token: Unbefugt, ungültiges oder fehlendes Autorisierungstoken.
• 429 too_many_requests: Zu viele Anfragen, Sie haben das Kontingent überschritten.
• 500 api_error: Interner Serverfehler, etwas ist auf dem Server schiefgelaufen.

​

Beispiel für eine Fehlerantwort

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "Abruf fehlgeschlagen"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​

Fazit