Prozessdokument festlegenPOST

Erstellen Sie einen Prozess ohne Dokument, lassen Sie den Nutzer die Erfassung abschließen und senden Sie anschließend das Dokument von Ihrem Back-end. Danach wird der Prozess abgeschlossen.

MarkdownChatGPTClaude

Lebenszyklus

1. Ihr Back-end erstellt den Prozess mit Prozess erstellen, ohne person.duiType und person.duiValue. Der Flow muss ein optionales Dokument erlauben. Der Prozess beginnt als PROCESS_STATE_CREATED.
2. Der Nutzer durchläuft die Journey und führt die Erfassung durch.
3. Die Unico API versetzt den Prozess in AWAITING_FOR_DOCUMENT, den Zustand, den Prozess abrufen zurückgibt, während der Prozess auf das Dokument wartet. Sie können bereits die Teilergebnisse der Funktionen lesen, die nicht von duiValue abhängen.
4. Ihr Back-end ruft diesen Endpunkt mit der Prozess-ID in der URL und dem Dokument im Body auf. Die Unico API schließt den Prozess dann ab, und er wechselt zu PROCESS_STATE_FINISHED.

Die Antwort enthält nicht das endgültige Ergebnis

Lesen Sie den endgültigen Zustand und das Ergebnis mit Prozess abrufen oder warten Sie auf den Webhook.

Endpunkt

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

Request

Headers

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

Die Zugangsdaten benötigen dieselbe Berechtigung, die für den Aufruf von Prozess erstellen verwendet wird.

Pfadparameter

Parameter	Typ	Erforderlich	Beschreibung
processId	string (UUID)	ja	Prozesskennung, die von Prozess erstellen zurückgegeben wird.

Body-Parameter

Feld	Typ	Erforderlich	Beschreibung
duiType	enum	ja	Dokumenttyp. DUI_TYPE_UNSPECIFIED wird abgelehnt. Siehe duiType-Werte unten.
duiValue	string	ja	Dokumentnummer, ohne Formatierung. Bis zu 320 Zeichen.

duiType-Werte

Land	Wert	Beschreibung
AR	DUI_TYPE_AR_PASSPORT	Argentinischer Reisepass
AR	DUI_TYPE_AR_DNI	Argentinische DNI
AR	DUI_TYPE_AR_LNC	Argentinischer Führerschein (Licencia Nacional de Conducir)
AT	DUI_TYPE_AT_STNR	Österreichische Steuernummer (STNR)
BE	DUI_TYPE_BE_NN	Belgische Nationalnummer (NN)
BR	DUI_TYPE_BR_CPF	Brasilianische CPF
BR	DUI_TYPE_BR_PASSPORT	Brasilianischer Reisepass
BR	DUI_TYPE_BR_CNPJ	Brasilianische CNPJ
CA	DUI_TYPE_CA_SIN	Kanadische SIN
CH	DUI_TYPE_CH_AHV	Schweizer AHV/AVS-Nummer
CL	DUI_TYPE_CL_RUN	Chilenische RUN
CL	DUI_TYPE_CL_PASSPORT	Chilenischer Reisepass
CL	DUI_TYPE_CL_LICENCIA_CONDUCIR	Chilenischer Führerschein (Licencia de Conducir)
CO	DUI_TYPE_CO_NIT	Kolumbianische NIT
CO	DUI_TYPE_CO_PASSPORT	Kolumbianischer Reisepass
CO	DUI_TYPE_CO_LICENCIA_CONDUCCION	Kolumbianischer Führerschein (Licencia de Conducción)
CO	DUI_TYPE_CO_CC	Kolumbianischer Bürgerausweis (Cédula de Ciudadanía)
DE	DUI_TYPE_DE_IDNR	Deutsche Steuer-Identifikationsnummer (IdNr)
DK	DUI_TYPE_DK_CPR	Dänische CPR
EC	DUI_TYPE_EC_NI	Ecuadorianische NI
ES	DUI_TYPE_ES_NIE	Spanische Ausländer-Identifikationsnummer (NIE)
ES	DUI_TYPE_ES_DNI	Spanischer Personalausweis (DNI)
FI	DUI_TYPE_FI_HETU	Finnische Personenkennung (HETU)
FR	DUI_TYPE_FR_SPI	Französische Steuerreferenznummer (SPI)
GB	DUI_TYPE_GB_NINO	Britische Sozialversicherungsnummer (NINO)
GT	DUI_TYPE_GT_CUI	Guatemaltekische CUI
ID	DUI_TYPE_ID_NIK	Indonesische NIK
IE	DUI_TYPE_IE_PPSN	Irische Sozialversicherungsnummer (PPSN)
IT	DUI_TYPE_IT_CF	Italienischer Codice Fiscale (CF)
LK	DUI_TYPE_LK_NIC	Sri-lankische NIC
LU	DUI_TYPE_LU_MATRICULE	Luxemburgische nationale Identifikationsnummer (Matricule)
MX	DUI_TYPE_MX_CURP	Mexikanische CURP
MX	DUI_TYPE_MX_RFC_PERSONA_FISICA	Mexikanische RFC (Persona Física)
MX	DUI_TYPE_MX_LICENCIA_CONDUCIR	Mexikanischer Führerschein (Licencia de Conducir)
NG	DUI_TYPE_NG_NIN	Nigerianische NIN
NG	DUI_TYPE_NG_BVN	Nigerianische Bankverifizierungsnummer (BVN)
NG	DUI_TYPE_NG_BVN_TOKEN	Nigerianisches BVN-Token (gehasht)
NG	DUI_TYPE_NG_NIN_TOKEN	Nigerianisches NIN-Token (gehasht)
NL	DUI_TYPE_NL_BSN	Niederländische Bürgerservicenummer (BSN)
NO	DUI_TYPE_NO_FNR	Norwegische nationale Identitätsnummer (Fødselsnummer)
PE	DUI_TYPE_PE_RUC	Peruanische RUC
PE	DUI_TYPE_PE_DNI	Peruanische DNI
PE	DUI_TYPE_PE_PASSPORT	Peruanischer Reisepass
PL	DUI_TYPE_PL_PESEL	Polnische PESEL
PT	DUI_TYPE_PT_NIF	Portugiesische Steueridentifikationsnummer (NIF)
SE	DUI_TYPE_SE_PNR	Schwedische Personennummer (PNR)
SE	DUI_TYPE_SE_SAMORDNINGSNUMMER	Schwedische Koordinierungsnummer (Samordningsnummer)
TR	DUI_TYPE_TR_TCKN	Türkische Identifikationsnummer (TCKN)
US	DUI_TYPE_US_SSN	US-amerikanische SSN
US	DUI_TYPE_US_PASSPORT	US-amerikanischer Reisepass
US	DUI_TYPE_US_DRIVER_LICENSE	US-amerikanischer Führerschein
US	DUI_TYPE_US_PASSPORT_CARD	US-amerikanische Passkarte
US	DUI_TYPE_US_POLYCARBONATE_PASSPORT	US-amerikanischer Polycarbonat-Reisepass
US	DUI_TYPE_US_ID_CARD	US-amerikanische ID-Karte
UY	DUI_TYPE_UY_CI	Uruguayische CI
ZZ	DUI_TYPE_ZZ_EMAIL	E-Mail-Adresse
ZZ	DUI_TYPE_ZZ_PHONE_NUMBER	Telefonnummer

Wann der Aufruf akzeptiert wird

• Der Prozess befindet sich in AWAITING_FOR_DOCUMENT: Der Nutzer hat die Erfassung bereits abgeschlossen.
• Der Prozess ist nicht abgelaufen.
• Der Flow erlaubt ein optionales Dokument.

Das Dokument ist unveränderlich. Ein zweiter Aufruf schlägt fehl, da der Prozess nicht mehr auf ein Dokument wartet.

Beispiel

cURL

curl -X POST https://api.idcloud.unico.app/client/v1/process/$PROCESS_ID/document \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "duiType": "DUI_TYPE_BR_CPF",
    "duiValue": "12345678909"
  }'

Node.js

import fetch from 'node-fetch';

const res = await fetch(
  `https://api.idcloud.unico.app/client/v1/process/${processId}/document`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      duiType: 'DUI_TYPE_BR_CPF',
      duiValue: '12345678909',
    }),
  }
);
const { processId: id, duiType, duiValue } = await res.json();

Antworten

200 OK

{
  "processId": "3116552c-6a3e-4c1f-9d2b-8f0e7a5b4c21",
  "duiType": "DUI_TYPE_BR_CPF",
  "duiValue": "12345678909"
}

Feld	Typ	Beschreibung
processId	string (UUID)	Prozesskennung.
duiType	enum	Für den Prozess registrierter Dokumenttyp.
duiValue	string	Für den Prozess registrierte Dokumentnummer.

Die Beispielwerte sind Platzhalter.

Fehlercodes

400 Bad Request

Code	Beschreibung
3	processId fehlt oder ist ungültig, duiType ist nicht angegeben, oder duiValue ist leer oder länger als 320 Zeichen.
9	Der Prozess wartet nicht auf ein Dokument (dies schließt ein bereits festgelegtes Dokument ein), ist abgelaufen oder abgeschlossen, oder der Flow erlaubt kein optionales Dokument.

401 Unauthorized

Code	Nachricht	Beschreibung
—	Jwt header is an invalid JSON	Wenn das verwendete Access-Token ungültige Zeichen enthält.
—	Jwt is expired	Wenn das verwendete Access-Token abgelaufen ist.

403 Forbidden

Code	Beschreibung
7	Den Zugangsdaten fehlt die Berechtigung, die von Prozess erstellen verlangt wird.

404 Not Found

Code	Beschreibung
5	Der Prozess existiert nicht oder gehört nicht zu Ihrem Unternehmen.

429 Too Many Requests

Rate-Limit erreicht. Wenn Ihr System einen HTTP-429-Fehler erhält, müssen Sie Mechanismen implementieren, um kaskadierende Ausfä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 kontinuierlich 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.
• Exponentieller Backoff mit Jitter: Erhöhen Sie beim erneuten Versuch 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 in der Warteschlange befindlichen Anfragen exakt zur gleichen Millisekunde erneut versucht werden.

Warnung

Das kontinuierliche Ansprechen eines rate-limitierten Endpunkts ohne Backoff kann die Einschränkungsperiode verlängern und den operativen Durchsatz Ihres Systems erheblich beeinträchtigen. Eine ordnungsgemäße Drosselung der Anfragen auf Ihrer Seite gewährleistet eine reibungslosere und widerstandsfähigere Integration.

Informationen zu Standardlimits, Erhöhung von Anfragen und weiteren Details finden Sie unter Rate Limits.

500 Internal Server Error

Code	Beschreibung
13	Das Dokument konnte nicht gespeichert werden.

Hinweis

Das Dokument wird beim Identitätsdienst registriert, bevor es gespeichert wird. Wenn diese Registrierung fehlschlägt, gibt der Aufruf den Status dieses Fehlers zurück.

Nächste Schritte

• Um den endgültigen Zustand und das Ergebnis zu lesen, siehe Prozess abrufen.
• Um benachrichtigt zu werden, wenn der Prozess abgeschlossen ist, siehe Webhooks und Events.