Prozess erstellen

Dies ist der Einstiegspunkt jeder Web- & SDK-Integration. Ihr Back-End ruft ihn auf, um einen Prozess zu erstellen; Ihr Front-End verwendet die zurückgegebenen Tokens, um den iFrame zu rendern, den Benutzer weiterzuleiten oder ein natives SDK zu initialisieren.

Den vollständigen Integrationsablauf finden Sie unter Web & SDK – Übersicht.

Endpunkt

Umgebung	URL
Produktion	POST https://api.idcloud.unico.app/client/v1/process
Sandbox	POST https://api.idcloud.uat.unico.app/client/v1/process

Anfrage

Headers

Header	Wert
Authorization	Bearer <access_token> (siehe Authentifizierung)
Content-Type	application/json

Body-Parameter

Feld	Typ	Erforderlich	Beschreibung
callbackUri	string	ja	URL, zu der der Benutzer nach Abschluss der Journey weitergeleitet wird. Verwenden Sie / für native SDK-Flows, bei denen der Callback in der App verarbeitet wird.
flow	string	ja	Flow-Bezeichner — bestimmt, welche Funktionen ausgeführt werden. Beispiele: idunicodocs, idunicosign, idchecktrust, idtoken, idsmart. Siehe Verfügbare Flows.
purpose	string	ja	Geschäftszweck. Zulässige Werte: creditprocess, biometryonboarding, carpurchase, ageverification.
person.duiType	enum	ja	Dokumenttyp. Zulässige Werte: DUI_TYPE_BR_CPF, DUI_TYPE_MX_CURP, DUI_TYPE_US_SSN, DUI_TYPE_BR_PASSPORT, DUI_TYPE_AR_PASSPORT, DUI_TYPE_AR_DNI, DUI_TYPE_NG_NIN, DUI_TYPE_CL_RUN, DUI_TYPE_EC_NI, DUI_TYPE_US_PASSPORT, DUI_TYPE_GT_CUI, DUI_TYPE_UY_CI, DUI_TYPE_ZZ_EMAIL, DUI_TYPE_ID_NIK, DUI_TYPE_ZZ_PHONE_NUMBER, DUI_TYPE_US_DRIVER_LICENSE, DUI_TYPE_NG_BVN.
person.duiValue	string	ja	Dokumentnummer ohne Formatierung.
person.friendlyName	string	nein	Anzeigename des Benutzers, der in der Journey-Oberfläche angezeigt wird. Maximal 50 Zeichen.
person.phone	string	nein	Telefonnummer im Format DDI + DDD + Nummer, ohne Trennzeichen. Erforderlich beim Versand von Benachrichtigungen per SMS oder WhatsApp.
person.email	string	nein	E-Mail-Adresse. Erforderlich für Flows mit elektronischer Signatur.
person.notifications	array	nein	Benachrichtigungskanäle zum Versand des Journey-Links. Jedes Element enthält notificationChannel: NOTIFICATION_CHANNEL_WHATSAPP, NOTIFICATION_CHANNEL_SMS oder NOTIFICATION_CHANNEL_EMAIL.
bioTokenId	string (UUID)	bedingt	Veraltet. Verwenden Sie stattdessen references. ID des biometrischen Referenzprozesses. Erforderlich für 1:1-Validierungs-Flows (idtoken, idtokentrust, idtokensign) und Smart Revalidierung (idsmart).
references	array	bedingt	Referenzeingaben für 1:1-Validierungs- und Smart-Revalidierungs-Flows, die bioTokenId ersetzen. Jedes Element enthält referenceType (REFERENCE_TYPE_IMAGE_BASE64 oder REFERENCE_TYPE_PROCESS_ID) und referenceContent (Base64-kodiertes Bild oder Prozess-UUID).
useCase	string	bedingt	Anwendungsfall der Smart Revalidierung. Erforderlich für idsmart. Beispiele: USE_CASE_LOGIN, USE_CASE_IDENTITY_REVALIDATION_7_DAYS, USE_CASE_FIN_TRANSACTIONS.
clientReference	string	nein	Ihre interne Kennung für diesen Prozess (Fremdschlüssel zur Querverknüpfung im Portal).
companyBranchId	string (UUID)	nein	Filial-ID. Nur erforderlich, wenn dem Servicekonto mehr als eine Filiale zugeordnet ist.
expiresIn	string	nein	Gültigkeitszeitraum des Prozesses ab Erstellung. Format: "3600s". Standardmäßig 7 Tage, wenn nicht angegeben.
flow_config	object	nein	Flow-spezifische Konfigurationsüberschreibungen.
flow_config.biometry_capture.enabled_back_camera	boolean	nein	Verwendung der rückseitigen Kamera des Geräts. Nicht kompatibel mit Dokumenterfassungs- oder Elektronische-Signatur-Flows.
contextualization	object	nein	Transaktionskontext, der dem Benutzer während der Journey zur Erläuterung der Erfassung angezeigt wird.
contextualization.currency	string	nein	Dem Benutzer angezeigter Währungscode. Zulässige Werte: BRL, MXN, USD.
contextualization.price	number	nein	Dem Benutzer angezeigter Transaktionsbetrag.
contextualization.locale	object	nein	Lokalisierter Begründungstext. Schlüssel: ptBr, enUs, esMx — jeweils mit einem reason-String, der während der Journey angezeigt wird.

Beispiel

cURL

curl -X POST https://api.idcloud.unico.app/client/v1/process \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "callbackUri": "https://app.client.com/callback",
    "flow": "idunicodocs",
    "purpose": "biometryonboarding",
    "person": {
      "duiType": "DUI_TYPE_BR_CPF",
      "duiValue": "12345678909",
      "friendlyName": "Luke Skywalker",
      "phone": "5511912345678",
      "email": "[email protected]"
    }
  }'

Node.js

import fetch from 'node-fetch';

const res = await fetch('https://api.idcloud.unico.app/client/v1/process', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    callbackUri: 'https://app.client.com/callback',
    flow: 'idunicodocs',
    purpose: 'biometryonboarding',
    person: {
      duiType: 'DUI_TYPE_BR_CPF',
      duiValue: '12345678909',
      friendlyName: 'Luke Skywalker',
      phone: '5511912345678',
      email: '[email protected]'
    }
  })
});

const { process: proc } = await res.json();
// proc.userRedirectUrl, proc.token, proc.webAppToken

Antworten

200 OK

{
  "process": {
    "id": "53060f52-f146-4c12-a234-5bb5031f6f5b",
    "state": "PROCESS_STATE_CREATED",
    "flow": "idunicosign",
    "purpose": "biometryonboarding",
    "callbackUri": "https://app.client.com/callback",
    "clientReference": "your-internal-id-123",
    "companyBranchId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "userRedirectUrl": "https://cadastro.unico.app/process/53060f52-f146-4c12-a234-5bb5031f6f5b",
    "token": "eyJhbGciOiJSUzI1NiIs...",
    "webAppToken": "eyJhbGciOiJSUzI1NiIs...",
    "createdAt": "2023-10-09T09:15:25.417105Z",
    "expiresAt": "2023-10-09T16:15:25.417105Z",
    "capacities": [],
    "authenticationInfo": {},
    "person": {
      "duiType": "DUI_TYPE_BR_CPF",
      "duiValue": "12345678909",
      "friendlyName": "Luke Skywalker",
      "phone": "5511912345678",
      "email": "[email protected]",
      "notifications": []
    },
    "companyData": {
      "branchId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "countryCode": "BR"
    }
  }
}

Feld	Typ	Beschreibung
process.id	string (UUID)	Prozesskennung. Verwenden Sie sie, um das Ergebnis über Prozess abrufen abzufragen.
process.state	enum	PROCESS_STATE_CREATED — Prozess erstellt, Journey noch nicht gestartet. PROCESS_STATE_FAILED — Prozesserstellung fehlgeschlagen.
process.flow	string	Bei der Erstellung übermittelter Flow-Bezeichner.
process.purpose	string	Bei der Erstellung übermittelter Geschäftszweck.
process.callbackUri	string	Bei der Erstellung übermittelte Callback-URI.
process.clientReference	string	Ihre bei der Erstellung übermittelte interne Kennung. Nur vorhanden, wenn in der Anfrage angegeben.
process.companyBranchId	string (UUID)	Filial-ID. Nur vorhanden, wenn in der Anfrage angegeben.
process.userRedirectUrl	string	URL zur Weiterleitung des Benutzers (Web-Redirect- und iFrame-Integrationen). Diese URL nicht verändern.
process.token	string	JWT zur Initialisierung des Web-SDK-iFrames.
process.webAppToken	string	JWT zur Initialisierung nativer SDKs (Android, iOS, Flutter).
process.createdAt	string (date-time)	Zeitstempel der Prozesserstellung.
process.expiresAt	string (date-time)	Zeitstempel, nach dem der Prozess abläuft und nicht mehr abgeschlossen werden kann.
process.capacities	array	Für diesen Prozess konfigurierte Funktionen.
process.authenticationInfo	object	Authentifizierungsinformationen für den Prozess (zum Erstellungszeitpunkt leer).
process.person	object	Rückgabe des bei der Erstellung übermittelten person-Objekts.
process.companyData.branchId	string (UUID)	Mit dem Prozess verknüpfte Filial-ID.
process.companyData.countryCode	string	Mit der Filiale verknüpfter Ländercode (z. B. BR, MX).

400 Bad Request

Wird zurückgegeben, wenn der Anfrage-Payload fehlerhaft ist, erforderliche Felder fehlen oder der flow-Wert unbekannt ist.

401 Unauthorized

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

429 Too Many Requests

Rate-Limit erreicht. Wiederholen Sie den Versuch nach dem in den Antwort-Headern angegebenen Intervall.

Fehlercodes

400 Bad Request

Code	Nachricht	Beschreibung
3	invalid flow	Wenn der angegebene Flow nicht existiert.
3	invalid person: friendly name exceeds 50 characters.	Wenn der Anzeigename 50 Zeichen überschreitet.
3	invalid purpose	Wenn der angegebene Zweck ungültig ist.
3	invalid callbackUri: unable to parse callbackUri: parse "": empty url, invalid callbackUri: url:	Wenn die angegebene callbackUri ungültig ist.
3	invalid person: email required for notification channel NOTIFICATION_CHANNEL_EMAIL, invalid email address for notification channel NOTIFICATION_CHANNEL_EMAIL	Wenn die angegebene E-Mail ungültig und E-Mail-Benachrichtigung konfiguriert ist.
3	invalid person: phone number required for notification channel NOTIFICATION_CHANNEL_WHATSAPP, phone number does not contain 13 chars for notification channel NOTIFICATION_CHANNEL_WHATSAPP	Wenn die angegebene Telefonnummer ungültig und SMS- oder WhatsApp-Benachrichtigung konfiguriert ist.
3	idnsv2/GetPublicID request error: rpc error: code = InvalidArgument desc = invalid dui value	Wenn der angegebene Bezeichner (duiValue) ungültig ist.
3	invalid expiresIn argument	Wenn der Wert expiresIn ungültig ist.
9	XX ID Apikeys are not set	Wenn der API-Schlüssel nicht korrekt konfiguriert ist.

401 Unauthorized

Nachricht	Beschreibung
Jwt header is an invalid JSON	Wenn das verwendete Zugriffstoken ungültige Zeichen enthält.
Jwt is expired	Wenn das verwendete Zugriffstoken abgelaufen ist.

429 Too Many Requests

Für diesen Status wird kein detaillierter Fehlercode bereitgestellt — nur HTTP-Status.

500 Internal Server Error

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

Nächste Schritte

• Nachdem der Benutzer die Journey abgeschlossen hat, rufen Sie Prozess abrufen auf, um das Ergebnis abzufragen, oder warten Sie auf den Webhook.