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.

MarkdownChatGPTClaude
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. Valeurs PROCESS_STATE_* (ex. CREATED, FAILED, FINISHED, AWAITING_FOR_DOCUMENT, 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

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 : IDCARD, DRIVERLICENSE, PASSPORT ou VOTERID. Les passeports américains conservent leur variante au lieu d'être ramenés à PASSPORT, donc des valeurs comme POLYCARBONATEPASSPORT, PASSPORTCARD et PAPERPASSPORT sont également renvoyées. Par exemple, unico.moja.dictionary.ar.generic.v1.IdCard et unico.moja.dictionary.us.generic.v1.PolycarbonatePassport sont rapportés comme IDCARD et POLYCARBONATEPASSPORT.

process.services[].documents[].doc.code rapporte le type de document sous forme d'un code court en majuscules. unico.moja.dictionary.br.cnh.v2.Cnh devient CNH. Le code ne porte ni le pays ni la version du schéma ; la version est renvoyée séparément dans doc.version.

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é — doc.data est vide
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": "BR"
    },
    "bioTokenData": {
      "referenceProcessId": "ref-proc-123",
      "authenticationId": "auth-ref-123"
    },
    "services": [
      {
        "envelopeId": "4d4f3d90-04a3-4259-b63b-930ab10d2e47",
        "documentIds": ["doc-abc-123"],
        "consent_granted": true,
        "documents": [
          {
            "doc_id": "doc-abc-123",
            "typified": true,
            "cpf_match": true,
            "face_match": true,
            "validate_doc": true,
            "reused_doc": false,
            "signed_url": "https://example.com/doc?token=xyz",
            "doc": {
              "version": 1,
              "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-2.
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.
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.
Incohérence de nomenclature d'état

AWAITING_FOR_DOCUMENT ne suit pas la convention de préfixe PROCESS_STATE_* utilisée par les autres états. C'est une incohérence de nomenclature connue dans l'API actuelle.

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).
Champs de process.services
Conventions de nommage mixtes dans services

Le tableau services utilise le camelCase pour les champs au niveau de l'enveloppe (envelopeId, documentIds) et le snake_case pour les champs au niveau du document (doc_id, consent_granted, face_match, etc.). Cela reflète la réponse réelle de l'API — les deux conventions sont intentionnelles et non une erreur de documentation.

ChampTypeDescription
envelopeIdstring (UUID)Identifiant de l'enveloppe signée.
documentIdsarray of stringsIDs des documents capturés dans ce service.
consent_grantedbooleanIndique si l'utilisateur a accordé le consentement au partage de données.
documentsarrayDocuments capturés avec les données OCR et les résultats de validation.
documents[].doc_idstringIdentifiant du document.
documents[].​typifiedbooleanIndique si le type de document a été identifié avec succès.
documents[].​cpf_matchbooleanIndique si le CPF du document correspond au CPF fourni (Brésil uniquement).
documents[].​face_matchbooleanIndique si le selfie correspond à la photo du document.
documents[].​validate_docbooleanIndique si le document a passé la validation d'authenticité.
documents[].​reused_docbooleanIndique si ce document a été réutilisé à partir d'un processus précédent.
documents[].​signed_urlstringURL pré-signée pour télécharger le PDF du document (valide 5 minutes — récupérez-la à nouveau pour la renouveler).
documents[].​doc.​versionintegerVersion du schéma OCR.
documents[].​doc.​codestringCode court du type de document (ex. CNH). 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 dans doc.data (ex. nomeCivil, dataNascimento) sont renvoyés en portugais — ce sont les valeurs réelles produites par le moteur OCR.

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​

Dernière mise à jour le