Prozess erstellen

Dieser Endpunkt deckt zwei Anwendungsfälle 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).

Der aktive Anwendungsfall 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 den aktiven Anwendungsfall und die aktivierten Fähigkeiten.
`Content-Type`	`application/json`

Body-Parameter

Einführung
Transaktional

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.
`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.

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_BR_CPF`, `DUI_TYPE_MX_CURP`, `DUI_TYPE_US_SSN`, `DUI_TYPE_NG_NIN`, `DUI_TYPE_AR_DNI`, `DUI_TYPE_ID_NIK`.
`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 diesen Anwendungsfall ist eine Orchestrierung mit Risiko-Score nicht möglich. Das Ergebnis wird immer synchron in der POST-Antwort zurückgegeben.

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

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

Beispiel

Einführung -- cURL
Einführung -- Node.js
Transaktional -- cURL
Transaktional -- Node.js

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..."
  }'

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();

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..."
  }'

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();

Antworten

Einführung
Transaktional

200 OK

{
  "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
`id`	string (UUID)	Prozesskennung. Verwenden Sie sie mit Prozess abrufen für erneute Abfragen.
`status`	integer	`1` (in Bearbeitung), `3` (erfolgreich abgeschlossen), `5` (Fehler).
`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`, `NOT_FOUND` — siehe Gesichts-Identifikator.
`idFace.personId`	string	Stabiler, opaker Bezeichner für das Gesicht. Nur vorhanden, wenn `idFace.result = FOUND`.
`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.

200 OK

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

Feld	Typ	Beschreibung
`id`	string (UUID)	Prozesskennung.
`status`	integer	`3` (erfolgreich abgeschlossen), `5` (Fehler). Für alle möglichen Werte siehe Prozess abrufen.
`biometryToken.result`	boolean	`true`, wenn das eingereichte Gesicht mit dem Referenzprozess übereinstimmt; andernfalls `false`.
`liveness`	integer	`1` (bestanden), `2` (nicht bestanden) -- siehe Lebenderkennung.

400 Bad Request

Der Payload ist fehlerhaft, das Bild ist ungültig oder erforderliche Felder fehlen. Siehe Fehlercodes unten.

403 Forbidden

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

409 Conflict

Die angegebene processId existiert bereits für diesen Mandanten. Siehe Fehlercodes unten.

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.

Fehlercodes

400 Bad Request
403 Forbidden
409 Conflict
500 Internal Server Error

Code	Nachricht	Beschreibung
`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.
`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.
`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.

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.

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

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.
Für Dokument- und Altersverifizierungs-Operationen siehe die entsprechenden Seiten in diesem Abschnitt.

Endpunkt​

Anfrage​

Beispiel​

Antworten​

Fehlercodes​

Nächste Schritte​