Prozess erstellen

Dieser Endpunkt verarbeitet zwei Anwendungsfälle, die denselben Pfad teilen, sich aber in Body-Parametern, Funktionen und Antwortfeldern unterscheiden:

Einführung — überprüft die Identität des Benutzers, indem sein Gesicht mit der Unico-Identitätsbasis verglichen wird (subject.code erforderlich).
Transaktional — verifiziert, dass es sich um dieselbe Person aus einem früheren Prozess handelt, indem Gesicht-zu-Gesicht verglichen wird (referenceProcessId ODER references-Array mit Selfie / process id erforderlich).

Der aktive Anwendungsfall wird durch den in der Anfrage-Header gesendeten APIKEY bestimmt.

Den vollständigen Integrationsablauf finden Sie in der 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

Header

Header	Wert
`Authorization`	`Bearer <access_token>` (siehe Authentifizierung)
`APIKEY`	Bereitgestellter API-Schlüssel — definiert den aktiven Anwendungsfall und aktivierte Funktionen.
`Content-Type`	`application/json`

Body-Parameter

Einführung
Transaktional

Feld	Typ	Erforderlich	Beschreibung
`subject.code`	string	ja	CPF (BR) oder CURP (MX).
`subject.name`	string	ja	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	E.164-Telefonnummer.
`useCase`	string	nein	Operationskontext, z. B. `Onboarding`.
`imageBase64`	string	ja	Von Ihrem Frontend aufgenommenes Selfie, in Base64.

Feld	Typ	Erforderlich	Beschreibung
`references`	array	bedingt	Referenzeingaben für 1:1-Validierungsabläufe. Jedes Element enthält `referenceType` (`REFERENCE_TYPE_IMAGE_BASE64` oder `REFERENCE_TYPE_PROCESS_ID`) und `referenceContent` (Base64-codiertes Bild oder Prozess-UUID).
`referenceProcessId`	string	bedingt	Veraltet. Verwenden Sie stattdessen `references`. ID des Referenz-Onboarding-Prozesses für den Vergleich. Bei einem Unico-Prozess verwenden Sie `authenticationInfo.authenticationId`.
`imageBase64`	string	ja	Von Ihrem Frontend aufgenommenes Selfie, in Base64.
`subject`	object	nein	Container für Benutzerinformationen.
`subject.code`	string	nein	CPF (BR) oder CURP (MX).
`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	E.164-Telefonnummer.
`useCase`	string	nein	Operationskontext, z. B. `Transactional`.
`subsidiaryId`	string	nein	Zweig-ID — nur erforderlich, wenn mehrere Zweige vorhanden sind.

Information

Für diesen Anwendungsfall ist keine Orchestrierung mit der Betrugsrisikoklassifizierung möglich. Das Ergebnis wird immer synchron in der POST-Antwort zurückgegeben.

Bildanforderungen

Mindestauflösung: 640 × 480 (HD-Standard)
Maximale Dateigröße: 800 KB (JPEG92-Komprimierung empfohlen)
Akzeptierte Formate: PNG, JPEG, WebP
JWT-Tokens aus dem 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": {
      "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: {
      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 '{
    "referenceProcessId": "80371b2a-3ac7-432e-866d-57fe37896ac6",
    "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({
    referenceProcessId: referenceProcessId,
    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" },
  "identityFraudsters": { "result": "inconclusive" },
  "government": { "serpro": 87 },
  "liveness": 1
}

Feld	Typ	Beschreibung
`id`	string (UUID)	Prozesskennung. Verwenden Sie diese mit Prozess abrufen für erneute Abfragen.
`status`	integer	`1` (in Verarbeitung), `3` (erfolgreich abgeschlossen), `5` (Fehler). Alle möglichen Werte finden Sie unter Prozess abrufen.
`unicoId.result`	string	`yes`, `no`, `inconclusive` — siehe Identitätsprüfung.
`identityFraudsters.result`	string	`yes`, `inconclusive` — siehe Betrugsrisikoklassifizierung.
`government.serpro`	integer	Serpro-Ähnlichkeitspunktzahl (0–100, -1, -2). Siehe Serpro-Ähnlichkeitsabgleich.
`liveness`	integer	`1` (bestanden), `2` (nicht bestanden) — siehe Lebenderkennung.

Information

Wenn unicoId.result = inconclusive und die Betrugsrisikoklassifizierungs-Orchestrierung aktiv ist, kann der Prozess status: 1 (in Verarbeitung) zurückgeben. Rufen 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). Alle möglichen Werte finden Sie unter Prozess abrufen.
`biometryToken.result`	boolean	`true`, wenn das übermittelte 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

Ratenlimit erreicht. Wiederholen Sie die Anfrage nach dem im Retry-After-Antwortheader angegebenen Intervall. Siehe Ratenlimits.

Fehlercodes

400 Bad Request
403 Forbidden
409 Conflict
500 Internal Server Error

Code	Message	Beschreibung
`20900`	O base64 informado não é válido.	Der Base64-Parameter ist ungültig. Mögliche Ursachen: kein Bild oder Injektionsversuch.
`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 standardmäßige oder nicht vorhandene 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 nicht unterstützt.
`20065`	The referenceProcessId field is invalid.	Die `referenceProcessId` ist keine gültige UUID.
`20062`	The useCase field is invalid.	Unbekannter Wert im Feld `useCase`.
`20024`	The referenceProcessId field is missing.	Der Parameter `referenceProcessId` 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` entspricht nicht dem ISO-8601-Format (`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 Parameter subject.name fehlt.
`20005`	O parâmetro subject.code não foi informado.	Der Parameter subject.code 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ültiger JWT des SDK.

Code	Message	Beschreibung
`30017`	User does not have permission to perform this action.	Fehlerhafter JWT oder Benutzer ohne Berechtigung für diesen Vorgang.
`10502`	O token informado está expirado.	Der 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	Message	Beschreibung
`20073`	The processID already exists.	Die angegebene `processId` existiert bereits für diesen Mandanten.

Code	Message	Beschreibung
`99999`	Internal failure! Try again later	Bei einem internen Fehler.

Nächste Schritte

Um ein Einführungsprozessergebnis abzufragen, siehe Prozess abrufen.
Für Dokument- und Altersverifizierungsoperationen, siehe die jeweiligen Seiten in diesem Abschnitt.

Endpunkt​

Anfrage​

Beispiel​

Antworten​

Fehlercodes​

Nächste Schritte​