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.

Für den vollständigen Integrationsablauf siehe 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-Kennung -- bestimmt, welche Fähigkeiten ausgeführt werden. Beispiele: `idunicodocs`, `idunicosign`, `idchecktrust`, `idtoken`, `idsmart`. Siehe Verfügbare Flows.
`purpose`	string	ja	Geschäftszweck. Akzeptierte Werte: `creditprocess`, `biometryonboarding`, `carpurchase`, `ageverification`.
`person.duiType`	enum	ja	Dokumenttyp. Akzeptierte 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`, `DUI_TYPE_MX_RFC_PERSONA_FISICA`, `DUI_TYPE_CO_NIT`, `DUI_TYPE_PE_RUC`, `DUI_TYPE_CA_SIN`, `DUI_TYPE_DK_CPR`, `DUI_TYPE_GB_NINO`, `DUI_TYPE_PL_PESEL`, `DUI_TYPE_SE_PNR`, `DUI_TYPE_AT_STNR`, `DUI_TYPE_FI_HETU`.
`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 Senden 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 Senden des Journey-Links. Jedes Element hat `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-Validierungsabläufe (`idtoken`, `idtokentrust`, `idtokensign`) und Intelligente Revalidierung (`idsmart`).
`references`	array	bedingt	Referenz-Eingaben für 1:1-Validierungs- und Intelligente-Revalidierungs-Abläufe, ersetzt `bioTokenId`. 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 für Intelligente 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 für Querverweise im Portal).
`companyBranchId`	string (UUID)	nein	Filial-ID. Nur erforderlich, wenn dem Dienstkonto mehr als eine Filiale zugeordnet ist.
`expiresIn`	string	nein	Gültigkeitsfenster des Prozesses ab Erstellung. Format: `"3600s"`. Standard ist 7 Tage, wenn nicht angegeben.
`flow_config`	object	nein	Konfigurationsüberschreibungen pro Flow.
`flow_config.biometry_capture.enabled_back_camera`	boolean	nein	Rückkamera des Geräts verwenden. Nicht kompatibel mit Dokumentenerfassungs- oder elektronischen Signatur-Flows.
`contextualization`	object	nein	Transaktionskontext, der dem Benutzer während der Journey angezeigt wird, um die Erfassung zu erklären.
`contextualization.company_name`	string	nein	Unternehmensname, der während der Journey angezeigt wird. Maximal 20 Zeichen.
`contextualization.currency`	string	nein	Dem Benutzer angezeigter Währungscode. Akzeptierte Werte: `BRL`, `MXN`, `USD`.
`contextualization.price`	number	nein	Dem Benutzer angezeigter Transaktionsbetrag.
`contextualization.locale`	object	nein	Lokalisierter Text, der während der Journey angezeigt wird. Schlüssel: `ptBr`, `enUs`, `esMx`.
`contextualization.locale.{ptBr\|enUs\|esMx}.reason`	string	nein	Kurzer Grund für die Erfassung, der während der Journey angezeigt wird. Maximal 50 Zeichen.
`contextualization.locale.{ptBr\|enUs\|esMx}.title`	string	nein	Titel des Kundenhinweises, der während der Journey angezeigt wird. Maximal 100 Zeichen. Muss zusammen mit `text` angegeben werden. HTML-Tags werden entfernt.
`contextualization.locale.{ptBr\|enUs\|esMx}.text`	string	nein	Inhalt des Kundenhinweises, der während der Journey angezeigt wird. Maximal 210 Zeichen. Muss zusammen mit `title` angegeben werden. HTML-Tags werden entfernt.

Beispiel

cURL
Node.js

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

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 zum Abrufen des Ergebnisses über Prozess abrufen.
`process.state`	enum	`PROCESS_STATE_CREATED` -- Prozess erstellt, Journey noch nicht gestartet. `PROCESS_STATE_FAILED` -- Prozesserstellung fehlgeschlagen.
`process.flow`	string	Bei der Erstellung gesendete Flow-Kennung.
`process.purpose`	string	Bei der Erstellung gesendeter Geschäftszweck.
`process.callbackUri`	string	Bei der Erstellung gesendete Callback-URI.
`process.clientReference`	string	Ihre bei der Erstellung gesendete 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). Ändern Sie diese URL nicht.
`process.token`	string	JWT zur Initialisierung des Web SDK iFrame.
`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 Fähigkeiten.
`process.authenticationInfo`	object	Authentifizierungsinformationen für den Prozess (zum Erstellungszeitpunkt leer).
`process.person`	object	Echo des bei der Erstellung gesendeten `person`-Objekts.
`process.companyData.branchId`	string (UUID)	Dem Prozess zugeordnete Filial-ID.
`process.companyData.countryCode`	string	Dem Filial zugeordneter 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. 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
401 Unauthorized
429 Too Many Requests
500 Internal Server Error

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 ist 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 ist und SMS- oder WhatsApp-Benachrichtigung konfiguriert ist.
`3`	idnsv2/GetPublicID request error: rpc error: code = InvalidArgument desc = invalid dui value	Wenn die angegebene Kennung (duiValue) ungültig ist.
`3`	invalid expiresIn argument	Wenn der `expiresIn`-Wert ungültig ist.
`3`	invalid company_name argument in process contextualization, max length is 20	Wenn `contextualization.company_name` 20 Zeichen überschreitet.
`3`	title and text must be provided together in process contexts	Wenn nur eines von `title` oder `text` in einem Locale angegeben wird.
`3`	invalid title argument in process contexts, max length is 100	Wenn ein Locale-`title` 100 Zeichen überschreitet.
`3`	invalid text argument in process contexts, max length is 210	Wenn ein Locale-`text` 210 Zeichen überschreitet.
`3`	invalid reason argument in process contexts, max length is 50	Wenn ein Locale-`reason` 50 Zeichen überschreitet.
`9`	XX ID Apikeys are not set	Wenn der API Key nicht ordnungsgemäß konfiguriert ist.

Nachricht	Beschreibung
Jwt header is an invalid JSON	Wenn das verwendete Access-Token falsche Zeichen enthält.
Jwt is expired	Wenn das verwendete Access-Token abgelaufen ist.

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

Nächste Schritte

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

Endpunkt​

Anfrage​

Beispiel​

Antworten​

Fehlercodes​

Nächste Schritte​