Aller au contenu principal
Récupérer un processusGET

Récupérer un processus existant par son identifiant. Selon le contrat de l'API, le résultat est déjà renvoyé de manière synchrone à la création du processus — utilisez cet endpoint pour les nouvelles interrogations, l'audit et le support.

Markdown
avertissement

Avant de récupérer le processus, consultez notre configuration de webhook et nos stratégies de fallback — cliquez ici.

Endpoint​

EnvironnementURL
ProductionGET https://api.idcloud.unico.app/client/v1/process/{processId}
SandboxGET https://api.idcloud.uat.unico.app/client/v1/process/{processId}

Requête​

En-têtes
En-têteValeur
AuthorizationBearer <access_token>
Paramètres de chemin
ParamètreTypeRequisDescription
processIdstring (UUID)ouiIdentifiant du processus renvoyé par Créer un processus.

Exemple​

curl -X GET https://api.idcloud.unico.app/client/v1/process/$PROCESS_ID \
-H "Authorization: Bearer $TOKEN"

Réponses​

200 OK
{
"process": {
"id": "226fd950-4b80-4da6-a476-ba9d397ddc91",
"flow": "id_r2",
"callbackUri": "/",
"userRedirectUrl": "https://cadastro.uat.unico.app/flow?collect-data=true&dynamic-wrapper=true&id=226fd950-4b80-4da6-a476-ba9d397ddc91",
"state": "PROCESS_STATE_FINISHED",
"result": "PROCESS_RESULT_APPROVED",
"createdAt": "2026-08-06T01:42:21.693615Z",
"finishedAt": "2026-08-06T01:43:03.080508Z",
"person": {
"duiType": "DUI_TYPE_BR_CPF",
"duiValue": "40*******50",
"friendlyName": "teste",
"email": "",
"phone": "5511999999999",
"notifications": [
{ "notificationChannel": "NOTIFICATION_CHANNEL_WHATSAPP" }
],
"phoneCountryCodeAlpha3": ""
},
"purpose": "personAuthentication",
"services": [],
"authenticationInfo": { "authenticationId": "55cba227-9828-49df-a16f-bcdaa7bdaa4d" },
"capacities": ["PROCESS_CAPACITY_IDCLOUDONE"],
"expiresAt": "2026-08-13T01:42:21.536500Z",
"token": "",
"companyData": { "branchId": "", "countryCode": "BRA" },
"simulated": false
}
}
Champs du processus
ChampSignification
idUUID du processus ; la clé utilisée pour interroger et suivre le flux.
flowType de parcours exécuté (ex. id_r2, idlivetrust_r2, idtrust_r2, ...).
callbackUriURI de callback vers laquelle l'application cliente est redirigée à la fin du flux.
userRedirectUrlURL complète de la page CbU que l'utilisateur ouvre pour effectuer le parcours (contient l'id et les indicateurs de comportement).
stateÉtat du cycle de vie du processus (ex. PROCESS_STATE_CREATED, PROCESS_STATE_FAILED, PROCESS_STATE_FINISHED, PROCESS_STATE_AWAITING_FOR_DOCUMENT, PROCESS_STATE_UNSPECIFIED).
resultVerdict final de l'évaluation. Valeurs PROCESS_RESULT_* (ex. APPROVED, AUTHENTICATED, NOT_APPROVED, ...). Concluant uniquement lorsque state = PROCESS_STATE_FINISHED.
createdAtHorodatage de création du processus (UTC).
finishedAtHorodatage de fin du processus (UTC).
personSous-objet contenant les données de la personne vérifiée.
purposeFinalité du processus (ex. personAuthentication, enregistrement de personne).
servicesListe des services additionnels attachés au processus ; vide en l'absence de service.
authenticationInfo.​authenticationIdID de l'événement d'authentification d'identité généré par le flux.
capacitiesCapacités/produits utilisés. Valeurs PROCESS_CAPACITY_* (ex. IDCLOUDONE).
expiresAtHorodatage d'expiration du processus/lien (UTC).
tokenJeton de session/accès associé au processus (peut être vide).
companyDataSous-objet contenant les données de l'entreprise/tenant propriétaire du processus.
simulatedBooléen ; indique s'il s'agit d'un processus de simulation/sandbox (true) ou réel (false).
Champs de la personne
ChampSignification
duiTypeType du document d'identification unique. Valeurs DUI_TYPE_* (ex. BR_CPF).
duiValueValeur du document (ex. le numéro de CPF).
friendlyNameNom convivial/surnom de la personne (texte libre, non validé).
emailE-mail de la personne ; peut être vide.
phoneNuméro de téléphone au format E.164 (code pays + code régional + numéro).
notificationsListe des canaux de notification. Chaque élément porte notificationChannel avec des valeurs NOTIFICATION_CHANNEL_* (ex. WHATSAPP, SMS, EMAIL).
phoneCountryCodeAlpha3Code pays ISO alpha-3 du numéro de téléphone (ex. BRA) ; peut être vide.
Champs des données de l'entreprise
ChampSignification
branchIdIdentifiant de la filiale du tenant ; vide lorsqu'il n'y a pas de segmentation par filiale.
countryCodePays de l'entreprise en ISO alpha-3 (ex. BRA).
Types de documents et champs OCR

process.services[].documents[].doc.code rapporte le type de document sous l'une de deux formes. Les documents traités par le module de documents d'Unico, y compris les documents réutilisés, portent un code court en majuscules (CNH). Les processus créés uniquement via l'API portent généralement le type de dictionnaire complet (unico.moja.dictionary.br.cnh.v2.Cnh), mais peuvent aussi porter un code court. Gérez les deux formes, quel que soit le mode d'intégration. Le code court ne porte ni le pays ni la version du schéma ; la version est renvoyée séparément dans doc.version.

Dans la forme courte, les types de documents qui utilisent le schéma unifié — unified_schema dans la référence des champs — sont rapportés sous forme du type identifié pendant la capture, en majuscules. Les valeurs les plus courantes sont IDCARD, DRIVERLICENSE, PASSPORT et VOTERID, mais la liste est ouverte : les autres types identifiés pendant la capture sont renvoyés tels quels, en majuscules. Gérez les valeurs hors de cette liste. Les passeports américains conservent leur variante au lieu d'être ramenés à PASSPORT : POLYCARBONATEPASSPORT, PASSPORTCARD, PAPERPASSPORT, CONSULARPASSPORT, ALIENPASSPORT et REFUGEEPASSPORT sont également renvoyés. Par exemple, unico.moja.dictionary.ar.generic.v1.IdCard et unico.moja.dictionary.us.generic.v1.PolycarbonatePassport sont rapportés comme IDCARD et POLYCARBONATEPASSPORT.

Schémas spécifiques

Les types de documents qui utilisent leur propre schéma de champs — listés sous specific_document_schemas dans la référence des champs — sont présentés dans le tableau ci-dessous. Utilisez le type de dictionnaire pour rechercher chaque schéma dans ce fichier.

Paysdoc.codeType de dictionnaireDocument
BRRGunico.​moja.​dictionary.​br.​rg.​v2.​RgRG
BRCNHunico.​moja.​dictionary.​br.​cnh.​v2.​CnhCNH (permis de conduire)
BRCINunico.​moja.​dictionary.​br.​cin.​v1.​CinCIN
BRPASSAPORTEunico.​moja.​dictionary.​br.​passaporte.​v1.​PassaportePasseport
MXINEunico.​moja.​dictionary.​mx.​ine.​v1.​IneTitre d'électeur INE
MXLPCunico.​moja.​dictionary.​mx.​lpc.​v1.​LpcLicencia para conducir (permis de conduire)
MXPASAPORTEunico.​moja.​dictionary.​mx.​pasaporte.​v1.​PasaportePasseport
—UNKNOWNunico.​moja.​dictionary.​other.​unknown.​v1.​UnknownLe type n'a pas pu être identifié, ou il s'agit d'un type brésilien ou mexicain sans schéma propre — doc.data est vide

Les documents brésiliens et mexicains utilisent uniquement les schémas spécifiques ci-dessus. Un document brésilien ou mexicain de tout autre type — par exemple, une carte de résident mexicaine — est rapporté comme UNKNOWN, et non avec le schéma unifié.

PASSAPORTE et PASAPORTE sont des documents différents

Le passeport brésilien est PASSAPORTE (double S) et le mexicain est PASAPORTE (S simple), chacun reflétant l'orthographe de son propre dictionnaire. Ce n'est pas une faute de frappe — ne traitez pas les deux valeurs comme équivalentes.

Aucune extraction OCR n'est effectuée et aucun champ n'est rapporté dans doc.data lorsque doc.code est UNKNOWN.

BrazilLes clients au Brésil peuvent recevoir le payload complet du processus

La structure globale de la réponse reste la même — le résultat unique est la valeur par défaut.

Les intégrations au Brésil peuvent recevoir l'objet processus complet ci-dessous, avec les résultats par capacité dans authenticationInfo.

{
"process": {
"id": "53060f52-f146-4c12-a234-5bb5031f6f5b",
"flow": "iddocs_r2",
"callbackUri": "https://example.com/callback",
"userRedirectUrl": "https://example.com/redirect",
"state": "PROCESS_STATE_FINISHED",
"result": "PROCESS_RESULT_OK",
"createdAt": "2024-01-01T10:00:00Z",
"finishedAt": "2024-01-01T10:15:00Z",
"expiresAt": "2024-01-08T10:00:00Z",
"purpose": "VERIFICATION",
"clientReference": "client-ref-abc",
"useCase": "USE_CASE_LOGIN",
"capacities": ["liveness", "face_match"],
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"person": {
"duiType": "DUI_TYPE_BR_CPF",
"duiValue": "12345678909",
"friendlyName": "Luke Skywalker",
"notifications": [
{
"notificationChannel": "email"
}
]
},
"authenticationInfo": {
"authenticationId": "auth-123",
"livenessResult": "LIVENESS_RESULT_LIVE",
"authenticationResult": "AUTHENTICATION_RESULT_INCONCLUSIVE",
"identityFraudstersResult": "TRUST_RESULT_UNSPECIFIED",
"bioTokenEngineResult": "BIO_TOKEN_ENGINE_RESULT_UNSPECIFIED",
"smartRevalidationResult": "SMART_REVALIDATION_RESULT_UNSPECIFIED",
"idAgeResult": "ID_AGE_RESULT_UNSPECIFIED",
"scoreEngineResult": {
"scoreEnabled": "SCORE_ENABLED_TRUE",
"score": 85.5
}
},
"companyData": {
"branchId": "branch-123",
"countryCode": "BRA"
},
"bioTokenData": {
"referenceProcessId": "ref-proc-123",
"authenticationId": "auth-ref-123"
},
"services": [
{
"consent_granted": true,
"documents": [
{
"doc_id": "doc-abc-123",
"share_id": "share-abc-123",
"typified": true,
"cpf_match": true,
"validate_doc": true,
"face_match": true,
"verified": true,
"reused_doc": false,
"signed_url": "https://example.com/doc?token=xyz",
"doc": {
"version": 2,
"code": "CNH",
"data": {
"numero": "044589731564",
"cpfNumero": "12345678909",
"nomeCivil": "Luke Skywalker",
"dataNascimento": "1990-05-12T00:00:00Z",
"dataExpiracao": "2027-12-07T00:00:00Z",
"categoria": "B"
}
}
}
]
}
]
}
}
Champs de premier niveau
ChampTypeDescription
process.idstring (UUID)Identifiant du processus.
process.flowstringIdentifiant du flux envoyé à la création.
process.callbackUristringURL de callback configurée pour les événements du processus.
process.​userRedirectUrlstringURL pour rediriger l'utilisateur une fois le parcours terminé.
process.stateenumÉtat actuel du processus. Voir les valeurs ci-dessous.
process.resultenumRésultat de la vérification. Présent uniquement lorsque state = PROCESS_STATE_FINISHED.
process.createdAtstring (datetime)Horodatage ISO 8601 de la création du processus.
process.finishedAtstring (datetime)Horodatage ISO 8601 de fin du processus. Présent uniquement lorsque state = PROCESS_STATE_FINISHED.
process.expiresAtstring (datetime)Horodatage ISO 8601 d'expiration du processus.
process.purposestringFinalité du processus telle que configurée dans le flux.
process.​clientReferencestringRéférence côté client optionnelle pour l'indexation dans le portail.
process.useCasestringIdentifiant du scénario associé au flux.
process.capacitiesarray of stringsListe des capacités activées dans ce processus.
process.tokenstringJWT signé pour l'intégration SDK.
process.personobjectIdentification fournie à la création.
process.​person.​notificationsarrayCanaux de notification configurés pour le parcours (ex. email).
process.​authenticationInfoobjectRésultats par capacité. Voir ci-dessous.
process.companyDataobjectContexte de l'entreprise et de la filiale.
process.​companyData.​branchIdstringIdentifiant de la filiale.
process.​companyData.​countryCodestringCode pays ISO 3166-1 alpha-3 (ex. BRA).
process.​bioTokenDataobjectInformations du processus de référence — présent uniquement dans les flux de Validation 1:1 et de Revalidation intelligente.
process.servicesarrayEnveloppes signées, documents capturés, et autres sorties de service. Voir ci-dessous.
Valeurs de process.state
ValeurSignification
PROCESS_STATE_CREATEDProcessus créé ; l'utilisateur n'a pas encore terminé le parcours.
PROCESS_STATE_AWAITING_FOR_DOCUMENTProcessus créé sans document d'identification. Présent uniquement lorsque le Custom Flow autorise un document optionnel. Envoyez le document avec Définir le document du processus.
PROCESS_STATE_FINISHEDParcours terminé. Vérifiez result et authenticationInfo.
PROCESS_STATE_FAILEDErreur de traitement.
Valeurs de process.result
ValeurSignification
PROCESS_RESULT_OKToutes les capacités ont renvoyé des résultats positifs.
PROCESS_RESULT_INVALID_IDENTITYAu moins une capacité a renvoyé un résultat négatif définitif (ex. échec de la détection de vie, identité non correspondante).
PROCESS_RESULT_ERRORErreur pendant le traitement du résultat.
PROCESS_RESULT_EXPIREDLe processus a expiré avant que le parcours ne soit terminé.
PROCESS_RESULT_UNSPECIFIEDProcessus pas encore terminé.
Résultats de capacité dans authenticationInfo

Tous les champs sont toujours renvoyés, quel que soit le flux. Les champs des capacités non utilisées dans le flux renvoient *_UNSPECIFIED.

Valeurs d'enum abrégées

Les valeurs abrégées (ex. livenessResult = LIVE, authenticationResult = INCONCLUSIVE) correspondent directement aux valeurs d'enum complètes documentées ici (LIVENESS_RESULT_LIVE, AUTHENTICATION_RESULT_INCONCLUSIVE, etc.) — le préfixe est omis par souci de concision.

ChampCapacitéValeurs possibles
authenticationId—Identifiant unique de cette tentative d'authentification.
livenessResultDétection de VieLIVENESS_RESULT_LIVE, LIVENESS_RESULT_NOT_LIVE, LIVENESS_RESULT_UNSPECIFIED
authenticationResultVérification d'identitéAUTHENTICATION_RESULT_POSITIVE, AUTHENTICATION_RESULT_NEGATIVE, AUTHENTICATION_RESULT_INCONCLUSIVE, AUTHENTICATION_RESULT_UNSPECIFIED
identityFraudstersResultClassification du risque de fraudeTRUST_RESULT_YES, TRUST_RESULT_INCONCLUSIVE, TRUST_RESULT_UNSPECIFIED
bioTokenEngineResultValidation 1:1BIO_TOKEN_ENGINE_RESULT_POSITIVE, BIO_TOKEN_ENGINE_RESULT_NEGATIVE, BIO_TOKEN_ENGINE_RESULT_UNSPECIFIED
smartRevalidationResultRevalidation intelligenteSMART_REVALIDATION_RESULT_POSITIVE, SMART_REVALIDATION_RESULT_NEGATIVE, SMART_REVALIDATION_RESULT_UNSPECIFIED
idAgeResultVérification de l'âgeID_AGE_RESULT_POSITIVE, ID_AGE_RESULT_NEGATIVE, ID_AGE_RESULT_INCONCLUSIVE, ID_AGE_RESULT_UNSPECIFIED
scoreEngineResult.​scoreEnabledScore de RisqueSCORE_ENABLED_TRUE, SCORE_ENABLED_FALSE, SCORE_ENABLED_UNSPECIFIED
scoreEngineResult.​scoreScore de RisqueNombre de -100 à +100. Présent lorsque authenticationResult = AUTHENTICATION_RESULT_INCONCLUSIVE et que le Score de Risque est activé.
serproResult.scoreRetour de similarité Serpro0–100 (similarité) ; -1 (aucun visage enregistré pour ce CPF) ; -2 (erreur d'intégration).
deviceMetadataMétadonnées de l'AppareilObjet avec status (found, not_found, unavailable) et les données de l'appareil. Absent lorsque la capacité n'est pas activée dans le flux.
Champs de process.services
Un élément par module

services contient un élément par module terminé dans le processus : la dernière exécution terminée de chaque module, et seulement tant que le processus est PROCESS_STATE_FINISHED ou PROCESS_STATE_AWAITING_FOR_DOCUMENT. Les processus créés uniquement via l'API portent leur élément de document quel que soit leur état. Un élément de capture de documents porte documents et consent_granted. Un élément de signature électronique porte envelope_id et document_ids. Les éléments n'ont pas de champ de type et leur ordre n'est pas stable : identifiez chacun par ses clés, et non par sa position, et ignorez les éléments que vous ne reconnaissez pas. Les clés sont en snake_case, sauf celles de doc.data, qui suivent le schéma du document (ex. nomeCivil).

ChampTypeDescription
consent_grantedbooleanÉlément de capture de documents. Indique si l'utilisateur a accordé le consentement au partage des documents avec votre entreprise.
documentsarrayÉlément de capture de documents. Documents capturés avec les données OCR et les résultats de validation.
documents[].doc_idstringIdentifiant du document.
documents[].​share_idstringIdentifiant du partage que l'utilisateur a accordé à votre entreprise pour ce processus.
documents[].​typifiedbooleanIndique si le type de document a été identifié.
documents[].​cpf_matchbooleanBrésil uniquement. Indique si le CPF du document correspond au CPF envoyé à la création. Toujours présent pour les entreprises dont le pays est défini sur le Brésil ; omis pour les autres pays et pour les entreprises sans pays défini.
documents[].​validate_docbooleanBrésil uniquement. Indique si le document a réussi la validation de documents d'Unico. Toujours présent pour les entreprises dont le pays est défini sur le Brésil (false lorsque la validation n'a pas été exécutée) ; omis pour les autres pays et pour les entreprises sans pays défini.
documents[].​face_matchboolean or nullIndique si le selfie correspond à la photo du document. null signifie que la vérification n'a pas été exécutée — ce n'est pas un résultat négatif.
documents[].​verifiedboolean or nulltrue uniquement lorsque le type de document est connu, que le document n'a pas été supprimé, que face_match vaut true et que le document a réussi les contrôles de qualité. false sinon, y compris lorsque face_match n'a pas été exécuté. null lorsque le processus n'est pas passé par le module de documents.
documents[].​reused_docbooleanIndique si ce document a été réutilisé à partir d'un processus précédent.
documents[].​signed_urlstringURL signée de courte durée pour télécharger l'image du document. Elle expire : ne la stockez pas et ne comptez pas sur une durée de validité fixe ; appelez à nouveau cet endpoint pour en obtenir une nouvelle.
documents[].​doc.​versionintegerVersion du dictionnaire du type de document (ex. 2 pour unico.moja.dictionary.br.cnh.v2.Cnh).
documents[].​doc.​codestringType de document, sous forme de code court (ex. CNH) ou de type de dictionnaire complet (ex. unico.moja.dictionary.br.cnh.v2.Cnh). Les documents traités par le module de documents portent le code court. Gérez les deux. Voir Types de documents et champs OCR pour toutes les valeurs et la manière dont le code est dérivé.
documents[].​doc.​dataobjectChamps OCR extraits. Le contenu varie selon le type de document — voir la référence complète des champs pour le catalogue complet. Les noms de champs suivent le schéma du document : portugais pour les documents brésiliens (ex. nomeCivil, dataNascimento), espagnol pour les documents mexicains et anglais pour le schéma unifié.
envelope_idstring (UUID)Élément de signature électronique. Identifiant de l'enveloppe signée.
document_idsarray of stringsÉlément de signature électronique. IDs des documents de l'enveloppe.
Processus créés uniquement via l'API

Dans un processus créé uniquement via l'API, l'élément de document provient de l'appel à l'API, et non du module de documents d'Unico, et certaines valeurs diffèrent du tableau ci-dessus :

  • consent_granted vaut toujours false : votre entreprise recueille le consentement, et Unico ne le suit pas.
  • share_id et signed_url sont vides.
  • face_match vaut toujours true ou false, jamais null.
  • verified vaut toujours null.
  • doc.version vaut 0.
  • doc.code porte généralement le type de dictionnaire complet (ex. unico.moja.dictionary.br.cnh.v2.Cnh), mais peut porter un code court.
  • doc.data vaut null lorsque les données OCR n'ont pas pu être lues.

Codes d'erreur​

CodeMessageDescription
3process id is invalidLorsque l'ID du processus est invalide.

Polling ou webhook​

Vous pouvez interroger (polling) cet endpoint pour vérifier la progression, mais le pattern recommandé consiste à vous abonner à un webhook et à n'appeler cet endpoint qu'en fallback. Voir Webhooks et événements.

Prochaines étapes​