Set Process Document

Définit le document d'identification (CPF, CURP, SSN ou autre duiType) sur un processus qui a été créé sans document. Une fois défini, le document est immuable.

Disponible uniquement pour les processus dont le Custom Flow autorise la création sans document, c'est-à-dire les processus à l'état AWAITING_FOR_DOCUMENT.

Endpoint

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

Requête

En-têtes

En-tête	Valeur
Authorization	Bearer <access_token> (voir Authentification)
Content-Type	application/json

Paramètres de chemin

Champ	Type	Requis	Description
processId	string	oui	ID du processus retourné dans process.id à la création.

Paramètres du corps

Champ	Type	Requis	Description
duiType	enum	oui	Type de document. Valeurs : DUI_TYPE_BR_CPF, DUI_TYPE_MX_CURP, DUI_TYPE_US_SSN. Ce endpoint prend en charge un sous-ensemble des types de documents acceptés par Créer un processus -- les Custom Flows qui autorisent la création optionnelle de document sont actuellement validés contre cette liste plus restreinte.
duiValue	string	oui	Numéro de document, sans formatage. Maximum 320 caractères (pour accommoder les identifiants encodés ou composites ; les numéros de documents standards tels que CPF ou CURP sont nettement plus courts).

Exemple

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

Réponses

200 OK

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

Champ	Type	Description
process.id	string	Identifiant du processus.
process.person.duiType	string	Type de document défini sur le processus.
process.person.duiValue	string	Valeur du document définie sur le processus.

400 Bad Request

Retourné lorsque le payload de la requête est malformé, que des champs requis sont manquants ou que l'état du processus ne permet pas l'opération.

401 Unauthorized

Le Bearer token est manquant, expiré ou invalide. Voir Authentification.

404 Not Found

Processus non trouvé.

429 Too Many Requests

Limite de débit atteinte. Lorsque votre système reçoit une erreur HTTP 429, vous devez implémenter des mécanismes pour prévenir les défaillances en cascade et éviter d'aggraver la restriction.

Bonnes pratiques :

• Période de refroidissement (backoff) : Arrêtez ou limitez immédiatement les requêtes suivantes de votre système. Ne réessayez pas continuellement les requêtes échouées en boucle serrée.
• Mise en file d'attente et limitation : Mettez en tampon ou en file d'attente les requêtes sortantes de votre côté pour contrôler le flux de trafic avant de les renvoyer.
• Backoff exponentiel avec jitter : Lors des nouvelles tentatives, augmentez le temps d'attente de manière exponentielle entre les tentatives (ex. : 1 s, 2 s, 4 s, 8 s) et ajoutez un petit délai aléatoire (« jitter ») pour éviter un effet de troupeau où toutes les requêtes en file d'attente réessaient exactement à la même milliseconde.

avertissement

Frapper continuellement un endpoint limité en débit sans faire de backoff peut prolonger la période de restriction et impacter sévèrement le débit opérationnel de votre système. Limiter correctement les requêtes de votre côté assure une intégration plus fluide et plus résiliente.

Pour les limites par défaut, l'augmentation des requêtes et des détails supplémentaires, voir Limites de débit.

Codes d'erreur

400 Bad Request

Code	Message	Description
3	process id is invalid	Lorsque l'ID du processus est invalide.
3	dui_type is required	Lorsque le type de document n'est pas fourni.
3	dui_value is required	Lorsque le numéro de document n'est pas fourni.
3	dui_value exceeds maximum length	Lorsque le numéro de document dépasse la limite maximale de caractères.
9	process is not awaiting for document	Lorsque le processus spécifié n'accepte pas la soumission de document.
9	process expired	Lorsque le processus spécifié a expiré.
9	document already set, cannot be modified	Lorsque le processus a déjà un document lié.
9	process already finished	Lorsque le processus a déjà été finalisé.
9	flow does not allow optional document	Lorsque le document est obligatoire pour le flux exécuté par le processus.

401 Unauthorized

Message	Description
Jwt header is an invalid JSON	Lorsque le jeton d'accès utilisé contient des caractères incorrects.
Jwt is expired	Lorsque le jeton d'accès utilisé a expiré.

404 Not Found

Code	Message	Description
5	error getting process: rpc error: code = NotFound desc = process not found	Lorsque l'ID du processus n'a pas été trouvé.

429 Too Many Requests

Aucun code d'erreur détaillé n'est fourni pour ce statut — uniquement le statut HTTP. Voir la section 429 Too Many Requests ci-dessus pour les bonnes pratiques.

500 Internal Server Error

Code	Message	Description
99999	Internal failure! Try again later	Lorsqu'une erreur interne se produit.

Prochaines étapes

• Après avoir défini le document, le processus poursuit son pipeline. Appelez Get Process pour récupérer le résultat, ou attendez le webhook.