Créer un processus

C'est le point d'entrée de chaque intégration Web & SDK. Votre back-end l'appelle pour créer un processus ; votre front-end utilise les jetons retournés pour afficher l'iFrame, rediriger l'utilisateur ou initialiser un SDK natif.

Pour le flux d'intégration complet, voir Vue d'ensemble Web & SDK.

Endpoint

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

Requête

En-têtes

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

Paramètres du corps

Champ	Type	Requis	Description
callbackUri	string	oui	URL vers laquelle l'utilisateur est redirigé après la fin du parcours. Utilisez / pour les flux SDK natifs où le rappel est géré dans l'application.
flow	string	oui	Identifiant du flux -- détermine quelles capacités s'exécutent. Exemples : idunicodocs, idunicosign, idchecktrust, idtoken, idsmart. Voir Flux disponibles.
purpose	string	oui	Objectif commercial. Valeurs acceptées : creditprocess, biometryonboarding, carpurchase, ageverification.
person.duiType	enum	oui	Type de document. Valeurs acceptées : 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	oui	Numéro de document, sans formatage.
person.friendlyName	string	non	Nom d'affichage de l'utilisateur montré dans l'interface du parcours. Maximum 50 caractères.
person.phone	string	non	Numéro de téléphone au format DDI + DDD + numéro, sans séparateurs. Requis lors de l'envoi de notifications par SMS ou WhatsApp.
person.email	string	non	Adresse e-mail. Requise pour les flux avec Signature Électronique.
person.notifications	array	non	Canaux de notification pour l'envoi du lien de parcours. Chaque élément a un notificationChannel : NOTIFICATION_CHANNEL_WHATSAPP, NOTIFICATION_CHANNEL_SMS ou NOTIFICATION_CHANNEL_EMAIL.
bioTokenId	string (UUID)	conditionnel	Déprécié. Utilisez references à la place. ID du processus biométrique de référence. Requis pour les flux de Validation 1:1 (idtoken, idtokentrust, idtokensign) et de Revalidation intelligente (idsmart).
references	array	conditionnel	Entrées de référence pour les flux de Validation 1:1 et de Revalidation intelligente, remplaçant bioTokenId. Chaque élément contient referenceType (REFERENCE_TYPE_IMAGE_BASE64 ou REFERENCE_TYPE_PROCESS_ID) et referenceContent (image encodée en base64 ou UUID de processus).
useCase	string	conditionnel	Cas d'utilisation de la Revalidation intelligente. Requis pour idsmart. Exemples : USE_CASE_LOGIN, USE_CASE_IDENTITY_REVALIDATION_7_DAYS, USE_CASE_FIN_TRANSACTIONS.
clientReference	string	non	Votre identifiant interne pour ce processus (clé étrangère pour le croisement dans le portail).
companyBranchId	string (UUID)	non	ID de succursale. Requis uniquement si le compte de service a plus d'une succursale associée.
expiresIn	string	non	Fenêtre de validité du processus à partir de sa création. Format : "3600s". Par défaut 7 jours si omis.
flow_config	object	non	Surcharges de configuration par flux.
flow_config.biometry_capture.enabled_back_camera	boolean	non	Utiliser la caméra arrière de l'appareil. Non compatible avec les flux de capture de documents ou de Signature Électronique.
contextualization	object	non	Contexte de la transaction montré à l'utilisateur pendant le parcours pour expliquer la capture.
contextualization.company_name	string	non	Nom de l'entreprise affiché pendant le parcours. Maximum 20 caractères.
contextualization.currency	string	non	Code de devise affiché à l'utilisateur. Valeurs acceptées : BRL, MXN, USD.
contextualization.price	number	non	Montant de la transaction affiché à l'utilisateur.
contextualization.locale	object	non	Texte localisé affiché pendant le parcours. Clés : ptBr, enUs, esMx.
contextualization.locale.{ptBr|enUs|esMx}.reason	string	non	Courte raison de la capture, affichée pendant le parcours. Maximum 50 caractères.
contextualization.locale.{ptBr|enUs|esMx}.title	string	non	Titre de l'avis client affiché pendant le parcours. Maximum 100 caractères. Doit être fourni avec text. Les balises HTML sont supprimées.
contextualization.locale.{ptBr|enUs|esMx}.text	string	non	Corps de l'avis client affiché pendant le parcours. Maximum 210 caractères. Doit être fourni avec title. Les balises HTML sont supprimées.

Exemple

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

Réponses

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

Champ	Type	Description
process.id	string (UUID)	Identifiant du processus. Utilisez-le pour récupérer le résultat via Get Process.
process.state	enum	PROCESS_STATE_CREATED -- processus créé, parcours non encore démarré. PROCESS_STATE_FAILED -- la création du processus a échoué.
process.flow	string	Identifiant du flux envoyé à la création.
process.purpose	string	Objectif commercial envoyé à la création.
process.callbackUri	string	URI de rappel envoyée à la création.
process.clientReference	string	Votre identifiant interne envoyé à la création. Présent uniquement s'il a été fourni dans la requête.
process.companyBranchId	string (UUID)	ID de succursale. Présent uniquement s'il a été fourni dans la requête.
process.userRedirectUrl	string	URL pour rediriger l'utilisateur (intégrations Web Redirect et iFrame). Ne modifiez pas cette URL.
process.token	string	JWT pour initialiser l'iFrame du Web SDK.
process.webAppToken	string	JWT pour initialiser les SDK natifs (Android, iOS, Flutter).
process.createdAt	string (date-time)	Horodatage de la création du processus.
process.expiresAt	string (date-time)	Horodatage après lequel le processus expire et ne peut plus être complété.
process.capacities	array	Capacités configurées pour ce processus.
process.authenticationInfo	object	Informations d'authentification du processus (vide au moment de la création).
process.person	object	Écho de l'objet person envoyé à la création.
process.companyData.branchId	string (UUID)	ID de succursale associé au processus.
process.companyData.countryCode	string	Code pays associé à la succursale (ex. BR, MX).

400 Bad Request

Retourné lorsque le payload de la requête est malformé, que des champs requis sont manquants ou que la valeur de flow est inconnue.

401 Unauthorized

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

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	invalid flow	Lorsque le flux spécifié n'existe pas.
3	invalid person: friendly name exceeds 50 characters.	Lorsque le nom d'affichage dépasse 50 caractères.
3	invalid purpose	Lorsque l'objectif fourni est invalide.
3	invalid callbackUri: unable to parse callbackUri: parse "": empty url, invalid callbackUri: url:	Lorsque le callbackUri fourni est invalide.
3	invalid person: email required for notification channel NOTIFICATION_CHANNEL_EMAIL, invalid email address for notification channel NOTIFICATION_CHANNEL_EMAIL	Lorsque l'e-mail fourni est invalide et que la notification par e-mail est configurée.
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	Lorsque le numéro de téléphone fourni est invalide et que la notification SMS ou WhatsApp est configurée.
3	idnsv2/GetPublicID request error: rpc error: code = InvalidArgument desc = invalid dui value	Lorsque l'identifiant fourni (duiValue) est invalide.
3	invalid expiresIn argument	Lorsque la valeur expiresIn est invalide.
3	invalid company_name argument in process contextualization, max length is 20	Lorsque contextualization.company_name dépasse 20 caractères.
3	title and text must be provided together in process contexts	Lorsque seulement l'un de title ou text est fourni dans une locale.
3	invalid title argument in process contexts, max length is 100	Lorsque le title d'une locale dépasse 100 caractères.
3	invalid text argument in process contexts, max length is 210	Lorsque le text d'une locale dépasse 210 caractères.
3	invalid reason argument in process contexts, max length is 50	Lorsque le reason d'une locale dépasse 50 caractères.
9	XX ID Apikeys are not set	Lorsque la clé API n'est pas correctement configurée.

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é.

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'il y a une erreur interne.

Prochaines étapes

• Après que l'utilisateur ait terminé le parcours, appelez Get Process pour récupérer le résultat, ou attendez le webhook.