Aller au contenu principal

Créer un processus

MarkdownChatGPTClaude

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

Pour le flux d'intégration complet, voir Flux.

Endpoint​

EnvironnementURL
ProductionPOST https://api.idcloud.unico.app/client/v1/process
SandboxPOST https://api.idcloud.uat.unico.app/client/v1/process

Requête​

En-têtes
En-têteValeur
AuthorizationBearer <access_token> (voir Authentification)
Content-Typeapplication/json
Paramètres du corps
Les exigences des champs dépendent du flux

Le fait qu'un champ soit requis, optionnel ou non applicable dépend du flow que vous intégrez — consultez Flux pour la recette spécifique que vous utilisez avant de présumer de l'exigence d'un champ à partir de ce tableau seul.

ChampTypeDescription
callbackUristringURL vers laquelle l'utilisateur est redirigé à la fin du parcours. Utilisez / pour les flux de SDK natif où le callback est géré dans l'application.
flowstringIdentifiant du flux — détermine quelles capacités s'exécutent. Exemples : idunicodocs, idunicosign, idchecktrust, idtoken, idsmart. Voir Flux disponibles.
purposestringFinalité commerciale. Valeurs acceptées : creditprocess, biometryonboarding, carpurchase, ageverification.
person.duiTypeenumType de document. Voir les valeurs de duiType ci-dessous.
person.duiValuestringNuméro du document, sans formatage.
person.friendlyNamestringNom d'affichage de l'utilisateur montré dans l'interface du parcours. Maximum 50 caractères.
person.phonestringNumé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.emailstringAdresse e-mail. Requise pour les flux avec Signature électronique.
person.​notificationsarrayCanaux de notification pour l'envoi du lien du parcours. Chaque élément possède notificationChannel : NOTIFICATION_CHANNEL_WHATSAPP, NOTIFICATION_CHANNEL_SMS, ou NOTIFICATION_CHANNEL_EMAIL.
referencesarrayEntrées de référence pour les flux de Validation 1:1 et de Revalidation intelligente. 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). Envoyez au maximum un élément — un tableau plus long est rejeté avec 400, et referenceContent ne doit pas être vide.
useCasestringScénario de Revalidation intelligente. Requis pour 🇧🇷 idsmart, idsmart_r2, idsmart_tp1. Exemples : USE_CASE_LOGIN, USE_CASE_FIN_TRANSACTIONS.
clientReferencestringIdentifiant unique de l'utilisateur dans votre système. Requis pour la capacité Multi-comptes. Unique dans votre base, maximum 256 caractères, sans espaces.
companyBranchIdstring (UUID)ID de la filiale. Requis uniquement si le compte de service a plusieurs filiales associées.
expiresInstringFenêtre de validité du processus à partir de la création. Format : "3600s". Par défaut 7 jours si omis.
flowConfigobjectSurcharges de configuration par flux.
flowConfig.​biometryCapture.​enabledBackCamerabooleanUtiliser la caméra arrière de l'appareil. Non compatible avec les flux de capture de document ou de Signature électronique.
contextualizationobjectContexte de la transaction montré à l'utilisateur pendant le parcours pour expliquer la capture. Disponible pour les clients de toute région — non limité à un pays spécifique.
contextualization.​company_namestringNom de l'entreprise affiché pendant le parcours. Maximum 20 caractères.
contextualization.​currencystringCode de devise affiché à l'utilisateur. Valeurs acceptées : BRL, MXN, USD.
contextualization.​pricenumberMontant de la transaction affiché à l'utilisateur.
contextualization.​localeobjectTexte localisé montré pendant le parcours. Clés : ptBr, enUs, esMx — ce sont les seules langues prises en charge pour le texte, quelle que soit la région du client.
contextualization.locale.{ptBr|enUs|esMx}.reasonstringRaison courte de la capture, montrée pendant le parcours. Maximum 50 caractères.
contextualization.locale.{ptBr|enUs|esMx}.titlestringTitre de l'avis client montré pendant le parcours. Maximum 100 caractères. Doit être fourni avec text. Les balises HTML sont supprimées.
contextualization.locale.{ptBr|enUs|esMx}.textstringCorps de l'avis client montré pendant le parcours. Maximum 210 caractères. Doit être fourni avec title. Les balises HTML sont supprimées.
imageBase64stringLe selfie, envoyé directement. Accepte le JWT de capture du SDK.
document.purposeenumFinalité du document. Vocabulaire fixe : DOCUMENT_PURPOSE_ONBOARDING, DOCUMENT_PURPOSE_CREDIT_PROCESS, DOCUMENT_PURPOSE_CAR_PURCHASE, DOCUMENT_PURPOSE_PAY_BY_PAYCHECK, DOCUMENT_PURPOSE_FGTS. Utilisé uniquement avec les flux de Correspondance visage-document.
document.​files[].​databytesNouvelle capture de document, encodée en base64. Disponible à l'échelle mondiale, non limité au Brésil. Mutuellement exclusif avec document.documentId.
document.documentIdstring (UUID)Réutilise un document déjà capturé par la même personne, au lieu d'une nouvelle capture. Mutuellement exclusif avec document.files[].
expectedResultobjectSimule le résultat d'une capacité dans les environnements de test/sandbox et marque la réponse avec simulated: true. Voir Simuler des résultats (Test Mock).
Valeurs de duiType
PaysValeurDescription
ARDUI_TYPE_AR_PASSPORTPasseport argentin
ARDUI_TYPE_AR_DNIDNI argentin
ARDUI_TYPE_AR_LNCPermis de conduire argentin (Licencia Nacional de Conducir)
ATDUI_TYPE_AT_STNRNuméro fiscal autrichien (STNR)
BEDUI_TYPE_BE_NNNuméro national belge (NN)
BRDUI_TYPE_BR_CPFCPF brésilien
BRDUI_TYPE_BR_PASSPORTPasseport brésilien
BRDUI_TYPE_BR_CNPJCNPJ brésilien
CADUI_TYPE_CA_SINNAS canadien
CHDUI_TYPE_CH_AHVNuméro AVS/AHV suisse
CLDUI_TYPE_CL_RUNRUN chilien
CLDUI_TYPE_CL_PASSPORTPasseport chilien
CLDUI_TYPE_CL_LICENCIA_CONDUCIRPermis de conduire chilien (Licencia de Conducir)
CODUI_TYPE_CO_NITNIT colombien
CODUI_TYPE_CO_PASSPORTPasseport colombien
CODUI_TYPE_CO_LICENCIA_CONDUCCIONPermis de conduire colombien (Licencia de Conducción)
CODUI_TYPE_CO_CCCarte de citoyenneté colombienne (Cédula de Ciudadanía)
DEDUI_TYPE_DE_IDNRNuméro d'identification fiscale allemand (IdNr)
DKDUI_TYPE_DK_CPRCPR danois
ECDUI_TYPE_EC_NINI équatorien
ESDUI_TYPE_ES_NIENuméro d'identité d'étranger espagnol (NIE)
ESDUI_TYPE_ES_DNIDocument national d'identité espagnol (DNI)
FIDUI_TYPE_FI_HETUCode d'identité personnelle finlandais (HETU)
FRDUI_TYPE_FR_SPINuméro de référence fiscale français (SPI)
GBDUI_TYPE_GB_NINONuméro d'assurance nationale britannique (NINO)
GTDUI_TYPE_GT_CUICUI guatémaltèque
IDDUI_TYPE_ID_NIKNIK indonésien
IEDUI_TYPE_IE_PPSNNuméro personnel de service public irlandais (PPSN)
ITDUI_TYPE_IT_CFCodice Fiscale italien (CF)
LKDUI_TYPE_LK_NICNIC du Sri Lanka
LUDUI_TYPE_LU_MATRICULENuméro d'identification national luxembourgeois (Matricule)
MXDUI_TYPE_MX_CURPCURP mexicain
MXDUI_TYPE_MX_RFC_PERSONA_FISICARFC mexicain (Persona Física)
MXDUI_TYPE_MX_LICENCIA_CONDUCIRPermis de conduire mexicain (Licencia de Conducir)
NGDUI_TYPE_NG_NINNIN nigérian
NGDUI_TYPE_NG_BVNNuméro de vérification bancaire nigérian (BVN)
NGDUI_TYPE_NG_BVN_TOKENJeton BVN nigérian (haché)
NGDUI_TYPE_NG_NIN_TOKENJeton NIN nigérian (haché)
NLDUI_TYPE_NL_BSNNuméro de service aux citoyens néerlandais (BSN)
NODUI_TYPE_NO_FNRNuméro d'identité national norvégien (Fødselsnummer)
PEDUI_TYPE_PE_RUCRUC péruvien
PEDUI_TYPE_PE_DNIDNI péruvien
PEDUI_TYPE_PE_PASSPORTPasseport péruvien
PLDUI_TYPE_PL_PESELPESEL polonais
PTDUI_TYPE_PT_NIFNuméro d'identification fiscale portugais (NIF)
SEDUI_TYPE_SE_PNRNuméro personnel suédois (PNR)
SEDUI_TYPE_SE_SAMORDNINGSNUMMERNuméro de coordination suédois (Samordningsnummer)
TRDUI_TYPE_TR_TCKNNuméro d'identification turc (TCKN)
USDUI_TYPE_US_SSNSSN des États-Unis
USDUI_TYPE_US_PASSPORTPasseport des États-Unis
USDUI_TYPE_US_DRIVER_LICENSEPermis de conduire des États-Unis
USDUI_TYPE_US_PASSPORT_CARDCarte de passeport des États-Unis
USDUI_TYPE_US_POLYCARBONATE_PASSPORTPasseport en polycarbonate des États-Unis
USDUI_TYPE_US_ID_CARDCarte d'identité des États-Unis
UYDUI_TYPE_UY_CICI uruguayenne
ZZDUI_TYPE_ZZ_EMAILAdresse e-mail
ZZDUI_TYPE_ZZ_PHONE_NUMBERNuméro de téléphone
Créer un processus sans document

Lorsque le flux autorise un document optionnel, vous pouvez omettre person.duiType et person.duiValue. Après la capture, le processus reste à l'état AWAITING_FOR_DOCUMENT jusqu'à ce que votre back-end envoie le document avec Définir le document du processus.

Exemple​

curl -X POST https://api.idcloud.unico.app/client/v1/process \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"flow": "idunicodocs_r2",
"purpose": "biometryonboarding",
"clientReference": "pedido-88216",
"callbackUri": "https://your-app.example.com/onboarding/callback",
"person": {
"duiType": "DUI_TYPE_BR_CPF",
"duiValue": "12345678909"
}
}'

Réponses​

200 OK
{
"process": {
"id": "b7c1f0a2-63d4-4f3e-9a17-2c8e5d41b0aa",
"flow": "idunicodocs_r2",
"state": "PROCESS_STATE_CREATED",
"result": "PROCESS_RESULT_UNSPECIFIED",
"purpose": "biometryonboarding",
"clientReference": "pedido-88216",
"person": {
"duiType": "DUI_TYPE_BR_CPF",
"duiValue": "12345678909"
},
"capacities": [
"PROCESS_CAPACITY_IDLIVE",
"PROCESS_CAPACITY_IDUNICO",
"PROCESS_CAPACITY_IDDOCS"
],
"authenticationInfo": {
"authenticationId": ""
},
"companyData": {
"branchId": "",
"countryCode": "BRA"
},
"callbackUri": "https://your-app.example.com/onboarding/callback",
"userRedirectUrl": "https://cadastro.unico.app/flow?id=b7c1f0a2-63d4-4f3e-9a17-2c8e5d41b0aa",
"token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…",
"webAppToken": "eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiZGlyIn0…",
"simulated": false
}
}
ChampTypeDescription
process.idstring (UUID)Identifiant du processus. Utilisez-le pour récupérer le résultat via Récupérer un processus.
process.stateenumPROCESS_STATE_CREATED — processus créé, parcours pas encore démarré. PROCESS_STATE_FAILED — échec de la création du processus.
process.resultenumRésultat de la vérification. Présent uniquement lorsque state = PROCESS_STATE_FINISHED — voir Flux pour les valeurs de résultat qu'un flux donné peut retourner.
process.flowstringIdentifiant du flux envoyé à la création.
process.purposestringFinalité commerciale envoyée à la création.
process.callbackUristringURI de callback envoyée à la création.
process.​clientReferencestringVotre identifiant interne envoyé à la création. Présent uniquement s'il a été fourni dans la requête.
process.​companyBranchIdstring (UUID)ID de la filiale. Présent uniquement s'il a été fourni dans la requête.
process.​userRedirectUrlstringURL vers laquelle rediriger l'utilisateur (intégrations Web Redirect et iFrame). Ne modifiez pas cette URL.
process.tokenstringJWT pour initialiser l'iFrame du Web SDK.
process.webAppTokenstringJWT pour initialiser les SDKs natifs (Android, iOS, Flutter).
process.createdAtstring (date-time)Horodatage de la création du processus.
process.expiresAtstring (date-time)Horodatage après lequel le processus expire et ne peut plus être complété.
process.capacitiesarrayCapacités configurées pour ce processus.
process.​authenticationInfoobjectInformations d'authentification pour le processus (vide au moment de la création).
process.personobjectÉcho de l'objet person envoyé à la création.
process.​companyData.​branchIdstring (UUID)ID de la filiale associée au processus.
process.​companyData.​countryCodestringCode pays associé à la filiale (ex. : BR, MX).

Codes d'erreur​

CodeMessageDescription
3invalid flowLorsque le flux spécifié n'existe pas.
3invalid person: friendly name exceeds 50 characters.Lorsque le nom d'affichage dépasse 50 caractères.
3invalid purposeLorsque la finalité fournie est invalide.
3invalid callbackUri: unable to parse callbackUri: parse "": empty url, invalid callbackUri: url:Lorsque le callbackUri fourni est invalide.
3invalid person: email required for notification channel NOTIFICATION_CHANNEL_EMAIL, invalid email address for notification channel NOTIFICATION_CHANNEL_EMAILLorsque l'e-mail fourni est invalide et qu'une notification par e-mail est configurée.
3invalid person: phone number required for notification channel NOTIFICATION_CHANNEL_WHATSAPP, phone number does not contain 13 chars for notification channel NOTIFICATION_CHANNEL_WHATSAPPLorsque le numéro de téléphone fourni est invalide et qu'une notification par SMS ou WhatsApp est configurée.
3idnsv2/GetPublicID request error: rpc error: code = InvalidArgument desc = invalid dui valueLorsque l'identifiant fourni (duiValue) est invalide.
3invalid expiresIn argumentLorsque la valeur de expiresIn est invalide.
3invalid company_name argument in process contextualization, max length is 20Lorsque contextualization.​company_name dépasse 20 caractères.
3title and text must be provided together in process contextsLorsque seul title ou text est fourni dans une locale.
3invalid title argument in process contexts, max length is 100Lorsqu'un title de locale dépasse 100 caractères.
3invalid text argument in process contexts, max length is 210Lorsqu'un text de locale dépasse 210 caractères.
3invalid reason argument in process contexts, max length is 50Lorsqu'un reason de locale dépasse 50 caractères.
3The references array must contain at most one element.Lorsque plus d'un élément est envoyé dans references.
3The references[].referenceContent field is missing.Lorsque referenceContent est vide.
3The references[].referenceType field must be IMAGE_BASE64 or PROCESS_ID.Lorsque referenceType n'est pas l'une des valeurs prises en charge.
3A reference is required for this flow.Lorsque le flux nécessite une référence et qu'aucune n'a été envoyée. Envoyez references[0] avec referenceType PROCESS_ID ou IMAGE_BASE64.
9The referenceProcessId field is invalid.Lorsque le processus de référence n'existe pas ou ne peut pas être réutilisé. Nomme le champ que vous avez envoyé — bioTokenId si c'est celui-là que vous avez envoyé.
3INVALID_IMAGELorsque l'image n'est pas un base64 valide, ou ressemble à une tentative d'injection.
3INVALID_DUILorsque le numéro du document est non standard ou n'existe pas.
3IMAGE_TOO_LARGELorsque l'image dépasse la taille maximale de 800 Ko.
3UNSUPPORTED_IMAGE_FORMATLorsque le format de l'image n'est pas PNG, JPEG ou WebP.
3MISSING_IMAGELorsque l'image est requise pour ce flux et n'a pas été envoyée.
3MISSING_NAMELorsque le nom est requis pour ce flux et n'a pas été envoyé.
3MISSING_DUILorsque le numéro du document est requis pour ce flux et n'a pas été envoyé.
3MISSING_PERSONLorsque l'objet person est requis pour ce flux et n'a pas été envoyé.
3INVALID_REQUESTLorsque le corps de la requête est nul ou ne peut pas être interprété.
3TOKEN_ALREADY_USEDLorsque le jeton de capture a déjà été utilisé. Il est à usage unique.
3TOKEN_EXPIREDLorsque le jeton de capture a expiré. Il doit être utilisé dans les 10 minutes.
3INVALID_BUNDLELorsque la requête ne respecte pas les exigences de sécurité.
3INVALID_NAMELorsque le nom est plus long que le maximum autorisé.
3INVALID_EMAILLorsque l'adresse e-mail est malformée ou trop longue.
3INVALID_PHONELorsque le numéro de téléphone dépasse 20 caractères.
3INVALID_DUI_TYPELorsque le type de document n'est pas l'une des valeurs prises en charge.
3INVALID_CLIENT_REFERENCELorsque clientReference est trop long, ou contient un espace ou #.
3INVALID_CONSENT_TYPELorsque consentType n'est pas NONE, DIRECT ou INDIRECT.
3INVALID_USE_CASELorsque useCase n'est pas reconnu, ou est trop long.
3INVALID_DEVICE_TRUST_TOKENLorsque le jeton de confiance de l'appareil est invalide ou a déjà été consommé.
3TOO_MANY_REFERENCESLorsque plus d'un élément est envoyé dans references.
3INVALID_REFERENCE_TYPELorsque referenceType n'est pas IMAGE_BASE64 ou PROCESS_ID.
3INVALID_REFERENCE_PROCESSLorsque l'ID du processus de référence n'est pas un identifiant valide.
3REFERENCE_PROCESS_NOT_FOUNDLorsque le processus référencé n'existe pas.
3REFERENCE_PROCESS_NOT_READYLorsque le processus référencé n'a pas de résultat réutilisable, ou a déjà été consommé.
3REFERENCE_SELFIE_NOT_FOUNDLorsque le processus référencé ne comporte pas de selfie à réutiliser.
3INVALID_CAPTURE_TOKENLorsque l'image capturée n'est pas un jeton valide produit par un SDK de capture.
3INVALID_CAPTURE_SIGNATURELorsque la signature du jeton de capture n'est pas valide.
3PRIOR_CAPTURE_NOT_FOUNDLorsque la capture précédente sur laquelle cette requête s'appuie n'a pas pu être localisée. Redémarrez le processus.
3PRIOR_CAPTURE_IN_PROGRESSLorsque la capture précédente n'est pas encore terminée. Réessayez sous peu.
3PRIOR_CAPTURE_FAILEDLorsque la capture précédente n'a pas pu être complétée. Redémarrez le processus.
3INVALID_DOCUMENTLorsqu'un fichier de document est illisible, protégé par mot de passe, ou dans un format non pris en charge.
3INVALID_AUTH_PROCESSLorsque document.authProcessId est invalide, expiré, ou appartient à une autre personne.
3INVALID_DOCUMENT_PURPOSELorsque document.purpose n'est pas l'une des valeurs prises en charge.
3PROCESS_REUSE_NOT_ENABLEDLorsque le flux ne permet pas de réutiliser un processus précédent sans image. Envoyez une image à la place.
9PROCESS_FAILEDLorsque le processus a atteint un échec terminal pendant sa création.
9Tenant API key is not configuredLorsque la clé API n'est pas correctement configurée.

Prochaines étapes​