Wiederverarbeitung und Import biometrischer Datenbanken

Dieser Leitfaden beschreibt, wie Sie eine Wiederverarbeitung oder einen Import biometrischer Datenbanken auf der Unico-Plattform durchführen. Er beschreibt die technischen und betrieblichen Anforderungen für eine effektive, sichere Integration gemäß den Best Practices der Plattform.

Umfang

Dieses Material umfasst zwei Arten von Prozessen:

• Wiederverarbeitung: Erneute Verarbeitung biometrischer Datensätze von Benutzern, die bereits die Datenbank des Kunden und von Unico durchlaufen haben, zur Neubewertung oder Migration zwischen Systemen.
• Import biometrischer Datenbanken: Erstmaliges Hochladen oder Aktualisieren einer Datenbank mit Selfies zur Identitätsprüfung und/oder zur Betrugsrisikoeinstufung.
• Import von Dokumentendatenbanken: Hochladen einer Dokumentendatenbank zusammen mit Selfies für die Facematch- oder CPF-Match-Verifizierung (nur Brasilien).

Voraussetzungen

• Der Kunde muss einen aktiven Vertrag oder eine NDA mit Unico unterzeichnet haben und sich in der Integrationsphase befinden (Ausnahme bei Genehmigung durch das Governance-Team).
• Das Projekt folgt formellen TPS-Vereinbarungen (Transaktionen pro Sekunde). Siehe TPS-Vereinbarung unten.
• Vor Erhalt der Produktionszugangsdaten ist eine vollständige Integrations-Homologation obligatorisch, um Datenqualität, Payload-Konformität und stabile Leistung sicherzustellen.
• Ein dediziertes Dienstkonto muss für die Wiederverarbeitung oder den Import erstellt werden (z.B. "Reprocessing" oder "Legacy_Import").
• Ein dedizierter API Key wird speziell für die Wiederverarbeitung/den Import erstellt.
• (Optional) Eine dedizierte Niederlassung kann für die Wiederverarbeitung/den Import erstellt werden. Dieser Parameter wird im Payload als subsidiaryId identifiziert. Siehe Payload-Parameter unten.
• Der API Key und das Dienstkonto werden deaktiviert nach dem vereinbarten Zeitraum oder Abschluss der Verarbeitung.

Verfügbare Capabilities

Capability	Beschreibung
Identitätsprüfung	Überprüft, ob das eingereichte Selfie dem tatsächlichen Inhaber des Identifikators gehört.
Betrugsrisikoklassifizierung	Prüft, ob eine Historie betrügerischen Verhaltens mit diesem Gesicht verbunden ist.
Facematch	Überprüft, ob das Dokumentfoto mit dem eingereichten Selfie übereinstimmt.
CPF Match Brazil only	Überprüft, ob die angegebene CPF mit der auf dem Dokument gedruckten CPF-Nummer übereinstimmt. Hinweis: Nicht alle RGs haben die CPF aufgedruckt.

Selfie-Anforderungen

• Muss im base64-Format eingereicht werden.
• Das Bild muss dem ICAO-Standard entsprechen (heller Hintergrund, zentriertes Gesicht, keine Accessoires, die die Identifizierung behindern, angemessene Beleuchtung).
• Empfohlene Abmessungen: 1080x1920 (Hochformat) oder 1920x1080 (Querformat).
• Maximale Größe: 800 KB (bei Bedarf mit JPEG 92 komprimieren).
• Ausrichtung: Hochformat.

Dokumentenanforderungen

• Unterstützte Dokumenttypen: Siehe Dokumentenerfassung und Wiederverwendung — Unterstützte Dokumente.
• Die Bilder müssen sowohl die Vorder- als auch die Rückseite des Dokuments vollständig und ohne Beschneidung zeigen.
• Das Dokument muss lesbar sein — klar, gut beleuchtet und frei von Verdeckungen.

TPS-Vereinbarung

• Die maximal vereinbarte TPS für dieses Projekt beträgt 10 TPS.
• Verteilen Sie Anfragen gleichmäßig über die Zeit, anstatt sie in großen Schüben zu senden.
• Dieses Limit darf nicht überschritten werden ohne formelle Genehmigung des Unico-Teams.
• Anfragen über dem Limit können automatisch verworfen oder blockiert werden.
• Wenn eine vorübergehende Erhöhung erforderlich ist, ist eine formelle vorherige Vereinbarung notwendig.

Integration

Endpunkte

Umgebung	Basis-URL	Zugang	Hinweise
Staging	https://api.id.uat.unico.app	Offen	Obligatorisch für Tests
Produktion	https://api.id.unico.app	Nur nach genehmigter Homologation	Erfordert strikte TPS-Kontrolle

Erforderliche Header

Authorization: Bearer {access_token}
APIKEY: {your_api_key}
Content-Type: application/json

Payload-Parameter

{
  "subject": {
    "duiType": 1,
    "code": "11032395702",
    "name": "User Name",
    "email": "[email protected]",
    "phone": "21998571922",
    "birthDate": "30/07/1989",
    "gender": "M"
  },
  "useCase": "Reprocessamento/Importação",
  "subsidiaryId": "35d734c4-7fbb-4b2f-a1dc-7e1575514819",
  "imageBase64": "/9j/4AAQSkZJR...",
  "document": {
    "purpose": "Reprocessamento",
    "documentId": "doc-001",
    "files": [
      {
        "data": "doc_base64_frente",
        "faceDocumentMatch": true
      },
      {
        "data": "doc_base64_verso"
      }
    ]
  }
}

Feld	Typ	Erforderlich	Beschreibung
subject	object	Ja	Benutzeridentifikationsdaten.
subject.duiType	integer	Ja	Dokumenttypkennung. Siehe duiType-Werte unten.
subject.code	string	Ja	CPF oder anderer Benutzeridentifikator.
subject.name	string	Ja	Vollständiger Name des Benutzers.
subject.email	string	Nein	E-Mail des Benutzers.
subject.phone	string	Nein	Telefonnummer des Benutzers.
subject.birthDate	string	Nein	Geburtsdatum des Benutzers (DD/MM/YYYY).
subject.gender	string	Nein	Geschlecht des Benutzers (M oder F).
useCase	string	Ja	Name des Anwendungsfalls ("Reprocessamento" oder "Importação de base").
subsidiaryId	string	Nein	Niederlassungs-UUID (von Unico bereitgestellt).
imageBase64	base64	Ja	Selfie-Bild des Benutzers, in base64 konvertiert.
document	object	Nein	Dokumentdaten, die dem Prozess zugeordnet sind.
document.purpose	string	Nein	Dokumentzweck (z.B. "Reprocessamento").
document.documentId	string	Nein	Dokumentkennung.
document.files	array	Nein	Liste der Dokumentbilddateien.
document.files[].data	base64	Nein	Dokumentbild, in base64 konvertiert.
document.files[].faceDocumentMatch	boolean	Nein	Gibt an, ob das Gesicht im Dokument mit dem eingereichten Selfie übereinstimmt.

duiType-Werte

Land	Code	Beschreibung
BR	1	Brasilianische CPF
BR	5	Brasilianischer Reisepass
MX	2	Mexikanische CURP
AR	6	Argentinischer Reisepass
AR	7	Argentinische DNI
US	4	US-amerikanische SSN
US	11	US-amerikanischer Reisepass
US	18	US-amerikanischer Führerschein
ID	16	Indonesische NIK
NG	8	Nigerianische NIN
CL	9	Chilenische RUN
EC	10	Ecuadorianische NI
GT	12	Guatemaltekische CUI
UY	13	Uruguayische CI
ZZ	15	E-Mail-Adresse
ZZ	17	Telefonnummer
MX	25	Mexikanische RFC (Persona Física)
CO	26	Kolumbianische NIT
PE	27	Peruanische RUC
CA	28	Kanadische SIN
DK	29	Dänische CPR
GB	30	Britische Sozialversicherungsnummer (NINO)
PL	31	Polnische PESEL
SE	32	Schwedische Personennummer (PNR)
AT	34	Österreichische Steuernummer (STNR)
FI	35	Finnische Personenkennung (HETU)
—	0	Nicht angegeben
—	3	Interner Unico-Identifikator

Wichtige Hinweise

• Das Selfie muss dem ICAO-Standard mit angemessener Qualität und Beleuchtung entsprechen.
• Das Selfie muss im base64-Format vorliegen.
• Vermeiden Sie Masseneinreichungen ohne TPS-Kontrolle — dies kann eine Ratenbegrenzung auslösen (siehe Fehlerbehandlung unten).
• Testen Sie Daten und Integration immer zuerst in der Staging-Umgebung.

Antworten

Erfolg — 200 OK

Ohne Dokument

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "unicoId": {
    "result": "inconclusive"
  },
  "identityFraudsters": {
    "result": "inconclusive"
  }
}

Feld	Typ	Beschreibung
id	string	Prozessidentifikator. Speichern Sie ihn für zukünftige Abfragen oder falls Sie später die 1:1-Validierung implementieren.
status	integer	Transaktionsstatus.
unicoId.result	string	Antwort der Identitätsprüfungs-Capability.
identityFraudsters.result	string	Antwort der Betrugsrisikoklassifizierungs-Capability.

Mit Dokument (Facematch)

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "score": 0,
  "status": 3,
  "unicoId": {
    "result": "yes"
  },
  "faceDocumentMatch": {
    "faceMatch": true
  },
  "identityFraudsters": {
    "result": "yes"
  }
}

Feld	Typ	Beschreibung
id	string	Prozessidentifikator. Speichern Sie ihn für zukünftige Abfragen oder falls Sie später die 1:1-Validierung implementieren.
status	integer	Transaktionsstatus.
score	number	Facematch-Bewertung.
unicoId.result	string	Antwort der Identitätsprüfungs-Capability.
faceDocumentMatch.faceMatch	boolean	Ob das Dokumentfoto mit dem eingereichten Selfie übereinstimmt.
identityFraudsters.result	string	Antwort der Betrugsrisikoklassifizierungs-Capability.

Bildverarbeitungsfehler

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 5
}

Häufige Fehler

Codes im Bereich 4xx weisen auf Validierungsfehler der bereitgestellten Daten hin. Codes im Bereich 5xx weisen auf serverseitige Fehler hin.

HTTP-Code	Fehlertyp	Wahrscheinliche Ursache	Empfohlene Maßnahme
400	Bad Request	Ungültiger Payload	Struktur und Inhalt validieren.
401	Unauthorized	Abgelaufener oder ungültiger Token	Token erneuern.
403	Forbidden	Falscher API Key oder unzureichende Berechtigungen	Zugangsdaten überprüfen.
429	Too Many Requests	Anfragerate überschritten	Warten und TPS-Limit einhalten.
500+	Internal Server Error	Interner Fehler	Nach einigen Sekunden erneut versuchen; bei anhaltendem Fehler ein Ticket eröffnen.

Fehlerbehandlung

• Rate Limit (HTTP 429) muss sorgfältig überwacht werden. Anfragenüberlastung kann die Pipeline blockieren.
• Halten Sie stets die mit Unico vereinbarten TPS ein (siehe TPS-Vereinbarung).
• Bei anhaltenden Fehlern (5xx) führen Sie eine erneute Verarbeitung mit Retry/Backoff-Kontrolle durch.