Créer un processus

Il s'agit du point d'entrée de toute 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, consultez Aperçu Web & SDK.

Point de terminaison

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 natif où le callback est géré dans l'application.
flow	string	oui	Identifiant du flux — détermine les capacités exécutées. Exemples : idunicodocs, idunicosign, idchecktrust, idtoken, idsmart. Voir Flux disponibles.
purpose	string	oui	Finalité commerciale. 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.
person.duiValue	string	oui	Numéro de document, sans formatage.
person.friendlyName	string	non	Nom d'affichage de l'utilisateur 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 pour 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 contient 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 la 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 du processus).
useCase	string	conditionnel	Cas d'usage 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 référencement croisé dans le portail).
companyBranchId	string (UUID)	non	ID de la filiale. Requis uniquement si le compte de service possède plus d'une filiale associée.
expiresIn	string	non	Fenêtre de validité du processus à partir de la création. Format : "3600s". Par défaut, 7 jours si omis.
flow_config	object	non	Configurations de substitution par flux.
flow_config.biometry_capture.enabled_back_camera	boolean	non	Utiliser la caméra arrière de l'appareil. Non compatible avec la capture de documents ou les flux de Signature Électronique.
contextualization	object	non	Contexte de transaction affiché à l'utilisateur pendant le parcours pour expliquer la capture.
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 de raison localisé. Clés : ptBr, enUs, esMx — chacune avec une chaîne reason affichée pendant le parcours.

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 Obtenir le processus.
process.state	enum	PROCESS_STATE_CREATED — processus créé, parcours non encore démarré. PROCESS_STATE_FAILED — échec de la création du processus.
process.flow	string	Identifiant du flux envoyé à la création.
process.purpose	string	Finalité métier envoyée à la création.
process.callbackUri	string	URI de callback 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 la filiale. Présent uniquement s'il a été fourni dans la requête.
process.userRedirectUrl	string	URL vers laquelle rediriger l'utilisateur (intégrations Web Redirect et iFrame). Ne modifiez pas cette URL.
process.token	string	JWT pour initialiser le Web SDK iFrame.
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	Copie de l'objet person envoyé à la création.
process.companyData.branchId	string (UUID)	ID de la filiale associée au processus.
process.companyData.countryCode	string	Code pays associé à la filiale (ex. : BR, MX).

400 Bad Request

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

401 Unauthorized

Jeton Bearer manquant, expiré ou invalide. Voir Authentification.

429 Too Many Requests

Limite de débit atteinte. Réessayez après l'intervalle indiqué dans les en-têtes de réponse.

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 la finalité fournie 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 par 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.
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 token d'accès utilisé contient des caractères incorrects.
Jwt is expired	Lorsque le token d'accès utilisé a expiré.

429 Too Many Requests

Aucun code d'erreur détaillé n'est fourni pour ce statut — statut HTTP uniquement.

500 Internal Server Error

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

Étapes suivantes

• Après que l'utilisateur a terminé le parcours, appelez Obtenir le processus pour récupérer le résultat, ou attendez le webhook.