Prozess erstellen

MarkdownChatGPTClaude

Dieser Endpunkt deckt drei Produkte ab, die denselben Pfad teilen, sich aber in Body-Parametern, Fähigkeiten und Antwortfeldern unterscheiden:

• Einführung -- validiert, wer der Benutzer ist, indem sein Gesicht mit der Identitätsdatenbank von Unico verglichen wird (subject.duiType + subject.code erforderlich).
• Transaktional -- verifiziert, dass es sich um dieselbe Person eines vorherigen Prozesses handelt, durch Gesicht-zu-Gesicht-Vergleich (referenceProcessId ODER references-Array mit Selfie / Prozess-ID erforderlich).
• Cardholder Verification -- bestätigt, dass eine Karte zu ihrem angegebenen Inhaber gehört, ohne jegliche Selfie-Aufnahme (subject.code + card erforderlich). Optional wird ein zuvor validierter Prozess über referenceProcessId wiederverwendet, um die Prüfung auszulösen; ohne dieses Feld fällt die Antwort standardmäßig auf unsure zurück. Siehe die Fähigkeit Cardholder Verification.

Das aktive Produkt wird durch den APIKEY bestimmt, der im Anfrage-Header gesendet wird.

Für den vollständigen Integrationsablauf siehe API-Übersicht.

Endpunkt

Umgebung	URL
Produktion	POST https://api.id.unico.app/processes/v1
Sandbox	POST https://api.id.uat.unico.app/processes/v1

Anfrage

Headers

Header	Wert
Authorization	Bearer <access_token> (siehe Authentifizierung)
APIKEY	Bereitgestellter API-Schlüssel -- definiert das aktive Produkt und die aktivierten Fähigkeiten.
Content-Type	application/json

Body-Parameter

Einführung

Feld	Typ	Erforderlich	Beschreibung
subject.duiType	integer	ja	Dokumenttypkennung. Siehe duiType-Werte unten.
subject.code	string	ja	Identifikatorwert gemäß subject.duiType. Keine Punkte oder Bindestriche.
subject.name	string	nein	Vollständiger Name.
subject.gender	string	nein	M oder F.
subject.birthDate	string (ISO 8601)	nein	Geburtsdatum (YYYY-MM-DD).
subject.email	string	nein	E-Mail-Adresse.
subject.phone	string	nein	Telefonnummer im E.164-Format.
subject.clientReference	string	bedingt	Eindeutiger Bezeichner des Benutzers in Ihrem System. Erforderlich für die Fähigkeit Mehrfachkonten. Eindeutig in Ihrer Datenbank, maximal 256 Zeichen, keine Leerzeichen.
useCase	string	nein	Operationskontext, z. B. Onboarding.
subsidiaryId	string	nein	Filial-ID — nur erforderlich, wenn mehrere Filialen vorhanden sind.
imageBase64	string	ja	Vom Frontend erfasstes Selfie, in Base64.

Transaktional

Feld	Typ	Erforderlich	Beschreibung
references	array	bedingt	Referenz-Eingaben für 1:1-Validierungsabläufe. Jedes Element enthält referenceType (REFERENCE_TYPE_IMAGE_BASE64 oder REFERENCE_TYPE_PROCESS_ID) und referenceContent (Base64-kodiertes Bild oder Prozess-UUID).
referenceProcessId	string	bedingt	Veraltet. Verwenden Sie stattdessen references. ID des Referenz-Einführungsprozesses für den Vergleich. Wenn die Referenz ein by-Unico-Prozess ist, verwenden Sie authenticationInfo.authenticationId.
imageBase64	string	ja	Vom Frontend erfasstes Selfie, in Base64.
subject	object	nein	Container für Benutzerinformationen.
subject.duiType	string	nein	Kennzeichentyp. Mögliche Werte: DUI_TYPE_AR_DNI, DUI_TYPE_BR_CPF, DUI_TYPE_ID_NIK, DUI_TYPE_MX_CURP, DUI_TYPE_NG_NIN, DUI_TYPE_US_SSN.
subject.code	string	nein	Identifikatorwert gemäß subject.duiType. Keine Punkte oder Bindestriche.
subject.name	string	nein	Vollständiger Name des Benutzers.
subject.gender	string	nein	M oder F.
subject.birthDate	string (ISO 8601)	nein	Geburtsdatum (YYYY-MM-DD).
subject.email	string	nein	E-Mail-Adresse.
subject.phone	string	nein	Telefonnummer im E.164-Format.
useCase	string	nein	Operationskontext, z. B. Transactional.
subsidiaryId	string	nein	Filial-ID -- nur erforderlich, wenn mehrere Filialen existieren.

Information

Für dieses Produkt ist eine Orchestrierung mit Risiko-Score nicht möglich. Das Ergebnis wird immer synchron in der POST-Antwort zurückgegeben.

Cardholder Verification

Feld	Typ	Erforderlich	Beschreibung
subject.duiType	integer	ja	Dokumenttypkennung. Siehe duiType-Werte unten. Derzeit nur DUI_TYPE_BR_CPF.
subject.code	string	ja	CPF des zu verifizierenden Karteninhabers. Keine Punkte oder Bindestriche.
card.bin	string	bedingt	Die ersten 6 oder 8 Ziffern der Karte (BIN). Erforderlich zusammen mit card.last4.
card.last4	string	bedingt	Die letzten 4 Ziffern der Karte. Erforderlich zusammen mit card.bin.
card.name	string	nein	Name des Karteninhabers, wie auf der Karte aufgedruckt.
referenceProcessId	string (UUID)	nein	ID eines zuvor validierten Prozesses, der wiederverwendet wird -- eines mit einem genehmigten Ergebnis der Identitätsprüfung oder Lebenderkennung für dieselbe CPF-Nummer. Die aktuelle Version dieser Fähigkeit basiert auf Wiederverwendung: Ohne dieses Feld wird die Prüfung nie ausgelöst, und die Antwort fällt standardmäßig auf das reguläre unsure-Ergebnis zurück — die Anfrage selbst schlägt nie fehl.
useCase	string	nein	Operationskontext, z. B. CardholderVerification.
subsidiaryId	string	nein	Filial-ID -- nur erforderlich, wenn mehrere Filialen vorhanden sind.

Information

Für dieses Produkt wird kein imageBase64 gesendet -- Cardholder Verification läuft vollständig im Backend, ohne Selfie-Erfassungsschritt.

duiType-Werte

Land	Code	Beschreibung
AR	6	Argentinischer Reisepass
AR	7	Argentinische DNI
AR	49	Argentinischer Führerschein (Licencia Nacional de Conducir)
AT	34	Österreichische Steuernummer (STNR)
BE	36	Belgische Nationalnummer (NN)
BR	1	Brasilianische CPF
BR	5	Brasilianischer Reisepass
BR	14	Brasilianische CNPJ
CA	28	Kanadische SIN
CH	33	Schweizer AHV/AVS-Nummer
CL	9	Chilenische RUN
CL	52	Chilenischer Reisepass
CL	57	Chilenischer Führerschein (Licencia de Conducir)
CO	26	Kolumbianische NIT
CO	53	Kolumbianischer Reisepass
CO	55	Kolumbianischer Führerschein (Licencia de Conducción)
CO	56	Kolumbianischer Bürgerausweis (Cédula de Ciudadanía)
DE	41	Deutsche Steuer-Identifikationsnummer (IdNr)
DK	29	Dänische CPR
EC	10	Ecuadorianische NI
ES	50	Spanische Ausländer-Identifikationsnummer (NIE)
ES	51	Spanischer Personalausweis (DNI)
FI	35	Finnische Personenkennung (HETU)
FR	46	Französische Steuerreferenznummer (SPI)
GB	30	Britische Sozialversicherungsnummer (NINO)
GT	12	Guatemaltekische CUI
ID	16	Indonesische NIK
IE	47	Irische Sozialversicherungsnummer (PPSN)
IT	37	Italienischer Codice Fiscale (CF)
LU	48	Luxemburgische nationale Identifikationsnummer (Matricule)
MX	2	Mexikanische CURP
MX	25	Mexikanische RFC (Persona Física)
MX	58	Mexikanischer Führerschein (Licencia de Conducir)
NG	8	Nigerianische NIN
NG	20	Nigerianische Bankverifizierungsnummer (BVN)
NG	43	Nigerianisches BVN-Token (gehasht)
NG	44	Nigerianisches NIN-Token (gehasht)
NL	42	Niederländische Bürgerservicenummer (BSN)
NO	39	Norwegische nationale Identitätsnummer (Fødselsnummer)
PE	27	Peruanische RUC
PE	40	Peruanische DNI
PE	54	Peruanischer Reisepass
PL	31	Polnische PESEL
PT	45	Portugiesische Steueridentifikationsnummer (NIF)
SE	32	Schwedische Personennummer (PNR)
SE	38	Schwedische Koordinierungsnummer (Samordningsnummer)
TR	24	Türkische Identifikationsnummer (TCKN)
US	4	US-amerikanische SSN
US	11	US-amerikanischer Reisepass
US	18	US-amerikanischer Führerschein
US	21	US-amerikanische Passkarte
US	22	US-amerikanischer Polycarbonat-Reisepass
US	23	US-amerikanische ID-Karte
UY	13	Uruguayische CI
ZZ	15	E-Mail-Adresse
ZZ	17	Telefonnummer
—	0	Nicht angegeben
—	3	Interner Unico-Identifikator

Bildanforderungen

• Mindestauflösung: 640 x 480 (HD-Standard)
• Maximale Dateigröße: 800 KB (JPEG92-Komprimierung empfohlen)
• Akzeptierte Formate: PNG, JPEG, WebP
• JWT-Tokens des SDK laufen nach 10 Minuten ab und können nur einmal verwendet werden

Komprimierte Anfragen

Die API unterstützt das Senden des Anfrage-Bodys komprimiert, unter Verwendung des Standard-HTTP-Headers Content-Encoding. Dies ist optional und vollständig abwärtskompatibel: Clients, die diesen Header nicht senden, funktionieren weiterhin genau wie zuvor.

Unterstützte Formate

Encoding	Content-Encoding-Header	Status
Gzip	gzip	✅ Empfohlen
Deflate	deflate	✅ Unterstützt
Keine Komprimierung	(Header nicht vorhanden)	✅ Unterstützt (Standardverhalten)

Empfehlung

Verwenden Sie gzip. Es bietet die universellste Unterstützung über Sprachen und HTTP-Bibliotheken hinweg und vermeidet die Implementierungsmehrdeutigkeiten, die bei anderen Formaten auftreten.

Komprimierung wird für Anfragen mit einem großen Body empfohlen (z. B. umfangreiche JSON-Payloads, base64-kodierte Bild-Uploads, Batch-Übermittlungen). Bei kleinen Anfragen bringt der Overhead der Komprimierung möglicherweise keinen relevanten Vorteil.

So senden Sie eine komprimierte Anfrage

1. Komprimieren Sie den Anfrage-Body (z. B. das serialisierte JSON) mit dem gewählten Algorithmus.
2. Senden Sie den komprimierten Body als Binärdaten in der Anfrage.
3. Fügen Sie den Header Content-Encoding mit dem passenden Wert hinzu (gzip oder deflate).
4. Behalten Sie Content-Type bei, um das ursprüngliche Inhaltsformat zu beschreiben (z. B. application/json), nicht die Transportkodierung.

cURL

echo '{"subject":{"code":"12345678909"},"useCase":"Onboarding","imageBase64":"/9j/4AAQSkZJR..."}' | gzip > body.json.gz

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Content-Encoding: gzip" \
  --data-binary @body.json.gz

Python (requests)

import gzip
import json
import requests

payload = {
    "subject": {"code": "12345678909"},
    "useCase": "Onboarding",
    "imageBase64": capturedImage,
}
compressed_body = gzip.compress(json.dumps(payload).encode("utf-8"))

response = requests.post(
    "https://api.id.unico.app/processes/v1",
    data=compressed_body,
    headers={
        "Authorization": f"Bearer {token}",
        "APIKEY": api_key,
        "Content-Type": "application/json",
        "Content-Encoding": "gzip",
    },
)

.NET (C#, HttpClient)

using System.IO.Compression;
using System.Text;
using System.Text.Json;

var json = JsonSerializer.Serialize(payload);
var jsonBytes = Encoding.UTF8.GetBytes(json);

using var outputStream = new MemoryStream();
using (var gzipStream = new GZipStream(outputStream, CompressionMode.Compress, leaveOpen: true))
{
    await gzipStream.WriteAsync(jsonBytes, 0, jsonBytes.Length);
}
outputStream.Position = 0;

var content = new ByteArrayContent(outputStream.ToArray());
content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
content.Headers.ContentEncoding.Add("gzip");

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", $"Bearer {token}");
client.DefaultRequestHeaders.Add("APIKEY", apiKey);

var response = await client.PostAsync("https://api.id.unico.app/processes/v1", content);

Tipp

Verwenden Sie für das Python-Beispiel den Parameter data=, nicht json=. Der Parameter json= serialisiert die Payload automatisch, komprimiert sie jedoch nicht.

Verwendung von deflate stattdessen: Der obige Ablauf ist identisch – nur der Komprimierungsaufruf und der Wert von Content-Encoding ändern sich.

Sprache	deflate
Bash / cURL	zlib-flate -compress < body.json > body.json.deflate (aus qpdf), dann -H "Content-Encoding: deflate"
Python	zlib.compress(data) statt gzip.compress(data)
.NET (C#)	System.IO.Compression.DeflateStream statt GZipStream

deflate ist in der Praxis mehrdeutig

Die deflate-Content-Encoding von HTTP ist als zlib-Stream (RFC 1950) spezifiziert, aber manche Clients und Server erzeugen oder erwarten historisch stattdessen rohes DEFLATE (RFC 1951). Diese API erwartet den Standard-zlib-verpackten Stream – dieselbe Ausgabe, die zlib.compress() (Python) oder DeflateStream (.NET) standardmäßig erzeugen. Im Zweifel bevorzugen Sie gzip, da dort keine solche Mehrdeutigkeit besteht.

Fehlerverhalten

Wenn Content-Encoding mit einem nicht unterstützten Wert gesendet wird oder der Body beschädigt oder für die angegebene Kodierung ungültig ist, gibt die API 400 Bad Request mit einer Meldung zurück, dass die Dekomprimierung des Anfrage-Bodys fehlgeschlagen ist.

FAQ

Muss ich etwas ändern, wenn ich keine Komprimierung verwenden möchte? Nein. Die Unterstützung für Content-Encoding ist additiv — Anfragen ohne diesen Header werden weiterhin normal verarbeitet.

Beeinflusst das die API-Antwort? Nein. Diese Funktion betrifft nur den vom Client gesendeten Body (Anfrage). Die Komprimierung der Antwort (was die API zurückgibt) wird separat über den Header Accept-Encoding gesteuert.

Welches Format sollte ich wählen? Verwenden Sie gzip, sofern keine besondere Einschränkung in Ihrer Umgebung ein anderes Format erfordert.

Beispiel

Einführung -- cURL

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": {
      "duiType": 1,
      "code": "12345678909",
      "name": "Luke Skywalker",
      "gender": "M",
      "birthDate": "2000-05-20",
      "email": "[email protected]",
      "phone": "5519725570707"
    },
    "useCase": "Onboarding",
    "imageBase64": "/9j/4AAQSkZJR..."
  }'

Einführung -- Node.js

import fetch from 'node-fetch';

const res = await fetch('https://api.id.unico.app/processes/v1', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
    'APIKEY': process.env.UNICO_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    subject: {
      duiType: 1,
      code: '12345678909',
      name: 'Luke Skywalker',
      gender: 'M',
      birthDate: '2000-05-20',
      email: '[email protected]',
      phone: '5519725570707'
    },
    useCase: 'Onboarding',
    imageBase64: capturedImage
  })
});

const result = await res.json();

Transaktional -- cURL

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "references": [
      {
        "referenceType": "REFERENCE_TYPE_PROCESS_ID",
        "referenceContent": "4f00b35f-69d4-415a-a843-d975cefcb169"
      }
    ],
    "useCase": "Transactional",
    "imageBase64": "/9j/4AAQSkZJR..."
  }'

Transaktional -- Node.js

import fetch from 'node-fetch';

const res = await fetch('https://api.id.unico.app/processes/v1', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
    'APIKEY': process.env.UNICO_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    references: [
      {
        referenceType: 'REFERENCE_TYPE_PROCESS_ID',
        referenceContent: '4f00b35f-69d4-415a-a843-d975cefcb169'
      }
    ],
    useCase: 'Transactional',
    imageBase64: capturedImage
  })
});

const result = await res.json();

Cardholder Verification -- cURL

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": {
      "duiType": 1,
      "code": "12345678909"
    },
    "card": {
      "bin": "12345678",
      "last4": "4321",
      "name": "Luke Skywalker"
    },
    "referenceProcessId": "4f00b35f-69d4-415a-a843-d975cefcb169",
    "useCase": "CardholderVerification"
  }'

Cardholder Verification -- Node.js

import fetch from 'node-fetch';

const res = await fetch('https://api.id.unico.app/processes/v1', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
    'APIKEY': process.env.UNICO_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    subject: {
      duiType: 1,
      code: '12345678909'
    },
    card: {
      bin: '12345678',
      last4: '4321',
      name: 'Luke Skywalker'
    },
    referenceProcessId: '4f00b35f-69d4-415a-a843-d975cefcb169',
    useCase: 'CardholderVerification'
  })
});

const result = await res.json();

Antworten

Einführung

200 OK

Der Contract ist einheitlich — das Feld idCloud.result trägt das konsolidierte Urteil der verwendeten Fähigkeiten.

Unico konsolidiert die Ergebnisse der ausgeführten Fähigkeiten in einem einzigen idCloud.result, bereit, um den nächsten Schritt Ihres Flows zu entscheiden — ohne dass Sie einzelne Ergebnisse orchestrieren müssen.

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

Feld	Typ	Beschreibung
id	string (UUID)	Prozesskennung. Verwenden Sie sie mit Prozess abrufen für erneute Abfragen.
status	integer	1 (in Bearbeitung), 3 (erfolgreich abgeschlossen), 5 (Fehler).

Mögliche Ergebniswerte

idCloud.result	Bedeutung	Empfohlene Aktion
approved	Echte Person und validierte Identität.	Mit dem Flow fortfahren.
denied	Identität nicht validiert, Lebenderkennung fehlgeschlagen oder extremes Risiko erkannt.	Flow beenden oder zu einem alternativen Flow weiterleiten.
critical-risk	Kritisches Risikoniveau erkannt.	Flow beenden oder an die manuelle Prüfung weiterleiten.
high-risk	Hohes Risikoniveau erkannt.	An die manuelle Prüfung oder einen alternativen Flow weiterleiten.
retry	Unzureichende Erfassung oder Score zur Auswertung.	Den Benutzer um eine neue Erfassung bitten.
inconclusive	Nicht genügend Nachweise für ein Urteil.	An die manuelle Prüfung oder einen alternativen Flow weiterleiten.

Die zurückgegebenen Werte hängen vom Recipe ab, das in Ihrem APIKey konfiguriert ist. Siehe Flows für die Ergebniswerte, die jedes Recipe zurückgeben kann.

Kunden in Brasilien erhalten möglicherweise die Antwort nach Fähigkeit

Die Gesamtstruktur der Antwort bleibt gleich — das einzelne Ergebnis ist der Standard.

Integrationen in Brasilien erhalten möglicherweise die offenen Ergebnisse pro Fähigkeit. Jede in der APIKey aktivierte Fähigkeit fügt der Antwort einen eigenen Block hinzu — Felder für deaktivierte Fähigkeiten werden weggelassen.

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "unicoId": {
    "result": "yes"
  },
  "riskLevel": {
    "result": "inconclusive"
  },
  "idFace": {
    "personId": "a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890",
    "result": "FOUND"
  },
  "government": {
    "serpro": 87
  },
  "liveness": 1
}

Antwortfelder hängen von Ihrem APIKey ab

Das obige Beispiel zeigt alle möglichen Capability-Felder. Ihre tatsächliche Antwort enthält nur Felder für die in Ihrer APIKey-Konfiguration aktivierten Capabilities — Felder für deaktivierte Capabilities werden vollständig weggelassen. Wenden Sie sich an Ihren Unico-Projektmanager, um Capabilities zu aktivieren oder anzupassen.

Feld	Typ	Beschreibung
unicoId.result	string	yes, no, inconclusive -- siehe Identitätsprüfung.
riskLevel.result	string	approved, reproved, risk-critical, risk-high, inconclusive -- siehe mögliche Werte unten oder Betrugseinstufung nach Risiko.
idFace.result	string	FOUND — siehe Gesichts-Identifikator.
idFace.personId	string	Stabiler, opaker Bezeichner für das Gesicht, zurückgegeben zusammen mit idFace.result = FOUND. Kann kein Gesicht im Bild identifiziert werden, schlägt die Anfrage mit Fehler 20532 fehl, anstatt einen idFace-Block zurückzugeben.
identityFraudsters.result	string	Veraltet. Verwenden Sie stattdessen riskLevel. Kunden mit laufenden Integrationen können es weiterhin verwenden, während sie die Migration mit dem verantwortlichen Projektteam koordinieren.
government.serpro	integer	Serpro-Ähnlichkeitswert (0--100, -1, -2). Nur in Brasilien verfügbar. Siehe Serpro-Ähnlichkeitsabgleich.
liveness	integer	1 (bestanden), 2 (nicht bestanden) -- siehe Lebenderkennung.

riskLevel.result — mögliche Werte

Wert	Bedeutung
approved	Es handelt sich um das Gesicht des Ausweisinhabers, und es wurden keine Hinweise auf Betrug gefunden.
reproved	Eine Ablehnung wird empfohlen, da mehrere Betrugsindikatoren erkannt wurden.
risk-critical	Eine Ablehnung wird empfohlen, die endgültige Entscheidung liegt jedoch in Ihrem Ermessen. Kritisches Risiko bedeutet, dass mindestens 2 starke Betrugsnachweise gefunden wurden.
risk-high	Eine Ablehnung wird ebenfalls empfohlen, die Entscheidung verbleibt jedoch bei Ihnen. Hohes Risiko bedeutet, dass mindestens ein starker Betrugsnachweis gefunden wurde.
inconclusive	Es wurden keine starken Betrugsnachweise gefunden. Daher ist es nicht möglich zu beurteilen, ob ein relevantes Risiko vorliegt oder nicht.

Information

Wenn unicoId.result = inconclusive und die Risiko-Score-Orchestrierung aktiv ist, kann der Prozess status: 1 (in Bearbeitung) zurückgeben. Fragen Sie Prozess abrufen ab oder verwenden Sie Webhooks, um das Endergebnis zu erhalten.

Kunden in Mexiko erhalten möglicherweise den Block der RENAPO-Verifizierung

Die Antwort behält dieselbe Struktur und ergänzt den idGov-Block.

Integrationen in Mexiko mit aktivierter RENAPO-Verifizierung erhalten einen zusätzlichen idGov-Block mit dem Eintrag, den RENAPO zur CURP des Benutzers führt. Er ist eine separate Antwort neben dem Identitätsergebnis.

{
  "id": "11111111-2222-3333-4444-555555555555",
  "status": 3,
  "idCloud": { "result": "approved" },
  "idGov": {
    "government_valid": true,
    "curp": "PUEA880304MDFRJN04",
    "government_name": "ANA PRUEBA EJEMPLO",
    "date_of_birth": "1988-03-04",
    "age": 38,
    "gender": "F",
    "deceased": false,
    "is_mexican": true,
    "citizenship": "MEXICO",
    "state_of_birth": "Ciudad de México",
    "state_iso": "MX-CMX",
    "issuing_entity_code": "DF",
    "municipality_registration": ""
  }
}

Feld	Typ	Beschreibung
idGov	object	RENAPO-Eintrag zur CURP. Fehlt, wenn die Capability nicht aktiviert ist. {}, wenn RENAPO nicht geantwortet hat. Nur Mexiko. Siehe RENAPO-Verifizierung.

Transaktional

200 OK

Der Contract ist einheitlich — das Feld idCloud.result trägt das konsolidierte Urteil der verwendeten Fähigkeiten.

Unico konsolidiert die Ergebnisse der ausgeführten Fähigkeiten in einem einzigen idCloud.result, bereit, um den nächsten Schritt Ihres Flows zu entscheiden — ohne dass Sie einzelne Ergebnisse orchestrieren müssen.

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

Feld	Typ	Beschreibung
id	string (UUID)	Prozesskennung.
status	integer	3 (erfolgreich abgeschlossen), 5 (Fehler). Für alle möglichen Werte siehe Prozess abrufen.

Mögliche Ergebniswerte

idCloud.result	Bedeutung	Empfohlene Aktion
approved	Echte Person und validierte Identität.	Mit dem Flow fortfahren.
denied	Identität nicht validiert, Lebenderkennung fehlgeschlagen oder extremes Risiko erkannt.	Flow beenden oder zu einem alternativen Flow weiterleiten.
critical-risk	Kritisches Risikoniveau erkannt.	Flow beenden oder an die manuelle Prüfung weiterleiten.
high-risk	Hohes Risikoniveau erkannt.	An die manuelle Prüfung oder einen alternativen Flow weiterleiten.
retry	Unzureichende Erfassung oder Score zur Auswertung.	Den Benutzer um eine neue Erfassung bitten.
inconclusive	Nicht genügend Nachweise für ein Urteil.	An die manuelle Prüfung oder einen alternativen Flow weiterleiten.

Die zurückgegebenen Werte hängen vom Recipe ab, das in Ihrem APIKey konfiguriert ist. Siehe Flows für die Ergebniswerte, die jedes Recipe zurückgeben kann.

Kunden in Brasilien erhalten möglicherweise die Antwort nach Fähigkeit

Die Gesamtstruktur der Antwort bleibt gleich — das einzelne Ergebnis ist der Standard.

Integrationen in Brasilien erhalten möglicherweise die offenen Ergebnisse pro Fähigkeit. Jede in der APIKey aktivierte Fähigkeit fügt der Antwort einen eigenen Block hinzu — Felder für deaktivierte Fähigkeiten werden weggelassen.

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "biometryToken": {
    "result": true
  },
  "liveness": 1
}

Feld	Typ	Beschreibung
biometryToken.result	boolean	true, wenn das eingereichte Gesicht mit dem Referenzprozess übereinstimmt; andernfalls false.
liveness	integer	1 (bestanden), 2 (nicht bestanden) -- siehe Lebenderkennung.

Cardholder Verification

200 OK

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

Feld	Typ	Beschreibung
id	string (UUID)	Prozesskennung.
status	integer	1 (in Bearbeitung), 3 (erfolgreich abgeschlossen), 5 (Fehler). Für alle Werte siehe Prozess abrufen.
cardholderVerification.result	string	approved -- die CPF-Nummer und die Karte gehören zur selben Person. unsure -- entweder wurde die Wiederverwendungsvoraussetzung nicht erfüllt, oder die Verifizierung selbst war nicht eindeutig. Fehlt, solange status noch nicht 3 ist. Siehe Cardholder Verification.

Fehlercodes

400 Bad Request

Code	Nachricht	Beschreibung
40221	This flow does not support reusing a prior process (referenceProcessId or bioTokenId) without an image; send an image (imageBase64, or references[0] with type IMAGE_BASE64) instead.	Der Wiederverwendungs-Flow (referenceProcessId/bioTokenId, ohne Bild) wurde abgelehnt, da die Prozesswiederverwendung für diesen API-Schlüssel nicht aktiviert ist.
20900	O base64 informado não é válido.	Der base64-Parameter ist ungültig. Mögliche Ursachen: Es handelt sich nicht um ein Bild oder es liegt ein Injektionsversuch vor.
20807	A imagem precisa estar no padrão HD ou possuir uma resolução superior a 640 x 480.	Die Auflösung des hochgeladenen Bildes ist zu niedrig.
20532	No face detected in image.	Im übermittelten Bild konnte kein Gesicht erkannt werden.
20513	The referenced process was not found.	Die referenceProcessId verweist auf einen Prozess, der nicht existiert oder nicht mehr zugänglich ist.
20512	The referenced process is not available for reuse.	Der referenzierte Prozess existiert, ist aber nicht zur Wiederverwendung verfügbar.
20509	The subject.name field is invalid.	subject.name enthält ungültige Zeichen.
20508	The subject.gender field is invalid.	subject.gender muss M oder F sein.
20507	O parâmetro subject.code é inválido.	Nicht standardgemäßer oder nicht existierender CPF.
20506	O base64 informado é muito grande. O tamanho máximo suportado é até 800kb.	Bildgröße überschreitet 800 KB; auf JPEG92 komprimieren.
20505	O base64 informado não é suportado. Os formatos aceitos são png, jpeg e webp.	Das Base64-Format ist ungültig oder wird nicht unterstützt.
20065	The referenceProcessId field is invalid.	Die referenceProcessId ist keine gültige UUID.
20062	The useCase field is invalid.	Nicht erkannter Wert im Feld useCase.
20024	The referenceProcessId field is missing.	Der referenceProcessId-Parameter wurde nicht angegeben und references wurde nicht als Alternative gesendet. Gilt nicht für Cardholder Verification -- ihr referenceProcessId wird nie als erforderlich validiert; eine nicht erfüllte Wiederverwendungsvoraussetzung liefert stattdessen unsure.
20533	The card field is missing.	Cardholder Verification: Das Objekt card wurde nicht angegeben.
20534	The card.bin field is missing.	Cardholder Verification: card.bin wurde nicht angegeben.
20535	The card.last4 field is missing.	Cardholder Verification: card.last4 wurde nicht angegeben.
20536	The card data is invalid.	Cardholder Verification: Die Kartendaten wurden als ungültig zurückgewiesen.
20021	The subject.phone field is invalid.	Format von subject.phone ist ungültig (IDD + Vorwahl + Nummer, 13 Zeichen).
20019	The subject.birthDate field is invalid.	subject.birthDate liegt außerhalb des ISO-8601-Formats (YYYY-MM-DD).
20009	O parâmetro imagebase64 não foi informado.	Der Selfie-Bildparameter fehlt.
20008	The subject.email field is invalid.	Ungültiges E-Mail-Format in subject.email.
20006	O parâmetro subject.name não foi informado.	Der subject.name-Parameter fehlt.
20005	O parâmetro subject.code não foi informado.	Der subject.code-Parameter fehlt.
20004	O parâmetro subject não foi informado.	Der subject-Parameter fehlt.
20003	The request body is missing or invalid.	Null oder ungültiger Payload.
20002	O parâmetro APIKey não foi informado.	Der APIKEY-Parameter fehlt im Anfrage-Header.
20001	O parâmetro authtoken não foi informado.	Der Integrationstoken-Parameter fehlt im Anfrage-Header.
10508	The JWT with the captured face has already been used.	Das JWT kann nur einmal verwendet werden.
10507	The JWT with the captured face is expired.	JWT abgelaufen; muss innerhalb von 10 Minuten gesendet werden.
10506	The imageBase64 field is not a valid JWT from SDK.	Das imageBase64 ist kein gültiges vom SDK generiertes JWT.

403 Forbidden

Bearer-Token oder APIKEY fehlt, ist abgelaufen oder ungültig. Siehe Authentifizierung.

Code	Nachricht	Beschreibung
30017	User does not have permission to perform this action.	Fehlerhaftes JWT oder Benutzer ohne Berechtigung für diese Operation.
10502	O token informado está expirado.	Das Access-Token ist abgelaufen.
10501	O token informado é inválido.	Das Authentifizierungstoken ist ungültig.
10201	O AppKey informado é inválido.	Der APIKEY ist ungültig oder existiert nicht.

409 Conflict

Code	Nachricht	Beschreibung
20073	The processID already exists.	Die angegebene processId existiert bereits für diesen Mandanten.

429 Too Many Requests

Rate-Limit erreicht. Wenn Ihr System einen HTTP-429-Fehler empfängt, müssen Sie Mechanismen implementieren, um Kaskadenausfälle zu verhindern und eine Verschärfung der Einschränkung zu vermeiden.

Best Practices:

• Abkühlphase (Backoff): Stoppen oder drosseln Sie nachfolgende Anfragen aus Ihrem System sofort. Wiederholen Sie fehlgeschlagene Anfragen nicht in einer engen Schleife.
• Warteschlange & Drosselung: Puffern oder reihen Sie ausgehende Anfragen auf Ihrer Seite ein, um den Datenverkehr zu kontrollieren, bevor Sie sie erneut senden.
• Exponentielles Backoff mit Jitter: Erhöhen Sie beim Wiederholen die Wartezeit zwischen den Versuchen exponentiell (z. B. 1 s, 2 s, 4 s, 8 s) und fügen Sie eine kleine zufällige Verzögerung ("Jitter") hinzu, um einen Herdeneffekt zu vermeiden, bei dem alle wartenden Anfragen exakt zur gleichen Millisekunde erneut gesendet werden.

Warnung

Das kontinuierliche Ansteuern eines rate-limitierten Endpunkts ohne Backoff kann die Einschränkungsdauer verlängern und den operativen Durchsatz Ihres Systems erheblich beeinträchtigen. Ordnungsgemäßes Drosseln der Anfragen auf Ihrer Seite gewährleistet eine reibungslosere und widerstandsfähigere Integration.

Für Standardlimits, Erhöhungsanfragen und weitere Details siehe Rate-Limits.

500 Internal Server Error

Code	Nachricht	Beschreibung
99999	Internal failure! Try again later	Wenn ein interner Fehler auftritt.

Nächste Schritte

• Zum Abfragen eines Einführungsprozess-Ergebnisses siehe Prozess abrufen.
• Um alle Recipe-Kombinationen und ihre möglichen Ergebniswerte zu sehen, siehe Flows.
• Für Dokument- und Altersverifizierungs-Operationen siehe die entsprechenden Seiten in diesem Abschnitt.