Prozessdokument setzen

Setzt das Ausweisdokument (CPF, CURP, SSN oder anderer duiType) für einen Prozess, der ohne Dokument erstellt wurde. Einmal gesetzt, ist das Dokument unveränderlich.

Nur verfügbar für Prozesse, deren Custom Flow die Erstellung ohne Dokument erlaubt -- d. h. Prozesse im Status AWAITING_FOR_DOCUMENT.

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

Anfrage

Headers

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

Pfadparameter

Feld	Typ	Erforderlich	Beschreibung
processId	string	ja	Prozess-ID, die bei der Erstellung in process.id zurückgegeben wurde.

Body-Parameter

Feld	Typ	Erforderlich	Beschreibung
duiType	enum	ja	Dokumenttyp. Werte: DUI_TYPE_BR_CPF, DUI_TYPE_MX_CURP, DUI_TYPE_US_SSN. Dieser Endpunkt unterstützt eine Teilmenge der von Prozess erstellen akzeptierten Dokumenttypen -- Custom Flows, die optionale Dokumenterstellung erlauben, werden derzeit gegen diese engere Liste validiert.
duiValue	string	ja	Dokumentnummer, ohne Formatierung. Maximal 320 Zeichen (unterstützt kodierte oder zusammengesetzte Kennungen; Standard-Dokumentnummern wie CPF oder CURP sind deutlich kürzer).

Beispiel

cURL

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

Node.js

import fetch from 'node-fetch';

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

const { process: proc } = await res.json();
// proc.id, proc.person.duiType, proc.person.duiValue

Antworten

200 OK

{
  "process": {
    "id": "abc-123",
    "person": {
      "duiType": "DUI_TYPE_BR_CPF",
      "duiValue": "12345678901"
    }
  }
}

Feld	Typ	Beschreibung
process.id	string	Prozesskennung.
process.person.duiType	string	Für den Prozess gesetzter Dokumenttyp.
process.person.duiValue	string	Für den Prozess gesetzter Dokumentwert.

400 Bad Request

Wird zurückgegeben, wenn der Anfrage-Payload fehlerhaft ist, erforderliche Felder fehlen oder der Prozessstatus die Operation nicht erlaubt.

401 Unauthorized

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

404 Not Found

Prozess nicht gefunden.

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

Code	Nachricht	Beschreibung
3	process id is invalid	Wenn die Prozess-ID ungültig ist.
3	dui_type is required	Wenn der Dokumenttyp nicht angegeben wurde.
3	dui_value is required	Wenn die Dokumentnummer nicht angegeben wurde.
3	dui_value exceeds maximum length	Wenn die Dokumentnummer die maximale Zeichenanzahl überschreitet.
9	process is not awaiting for document	Wenn der angegebene Prozess keine Dokumenteinreichung akzeptiert.
9	process expired	Wenn der angegebene Prozess abgelaufen ist.
9	document already set, cannot be modified	Wenn dem Prozess bereits ein Dokument zugeordnet ist.
9	process already finished	Wenn der Prozess bereits abgeschlossen wurde.
9	flow does not allow optional document	Wenn das Dokument für den vom Prozess ausgeführten Flow obligatorisch ist.

401 Unauthorized

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.

404 Not Found

Code	Nachricht	Beschreibung
5	error getting process: rpc error: code = NotFound desc = process not found	Wenn die Prozess-ID nicht gefunden wurde.

429 Too Many Requests

Für diesen Status wird kein detaillierter Fehlercode bereitgestellt — nur der HTTP-Status. Siehe den Abschnitt 429 Too Many Requests oben für Best Practices.

500 Internal Server Error

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

Nächste Schritte

• Nach dem Setzen des Dokuments setzt der Prozess seine Pipeline fort. Rufen Sie Prozess abrufen auf, um das Ergebnis abzurufen, oder warten Sie auf den Webhook.