Obtenir le processusGET

Récupérez un processus existant par son identifiant. Selon le contrat API, le résultat est déjà retourné de manière synchrone à la création du processus — utilisez ce endpoint pour les re-requêtes, l'audit et le support.

avertissement

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

Point de terminaison

Environnement	URL
Production	GET https://api.idcloud.unico.app/client/v1/process/{processId}
Sandbox	GET https://api.idcloud.uat.unico.app/client/v1/process/{processId}

Requête

En-têtes

En-tête	Valeur
Authorization	Bearer <access_token>

Paramètres de chemin

Paramètre	Type	Requis	Description
processId	string (UUID)	oui	Identifiant du processus retourné par Créer un processus.

Exemple

cURL

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

Node.js

import fetch from 'node-fetch';

const res = await fetch(
  `https://api.idcloud.unico.app/client/v1/process/${processId}`,
  { headers: { Authorization: `Bearer ${accessToken}` } }
);
const { process: proc } = await res.json();

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

Champ	Signification
id	UUID du processus ; la clé utilisée pour interroger et suivre le flux.
flow	Type de parcours exécuté (ex. id_r2, idlivetrust_r2, idtrust_r2, ...).
callbackUri	URI de rappel vers laquelle l'application cliente est redirigée à la fin du flux.
userRedirectUrl	URL complète de la page CbU que l'utilisateur ouvre pour exécuter le parcours (porte 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).
result	Verdict final de l'évaluation. Valeurs PROCESS_RESULT_* (ex. APPROVED, AUTHENTICATED, NOT_APPROVED, ...). Concluant uniquement lorsque state = PROCESS_STATE_FINISHED.
createdAt	Horodatage de création du processus (UTC).
finishedAt	Horodatage de fin du processus (UTC).
person	Sous-objet contenant les données de la personne vérifiée.
purpose	Objectif du processus (ex. personAuthentication, enregistrement de personne).
services	Liste des services additionnels associés au processus ; vide si aucun.
authenticationInfo.authenticationId	ID de l'événement d'authentification d'identité généré par le flux.
capacities	Capacités/produits utilisés. Valeurs PROCESS_CAPACITY_* (ex. IDCLOUDONE).
expiresAt	Horodatage d'expiration du processus/lien (UTC).
token	Jeton de session/accès associé au processus (peut être vide).
companyData	Sous-objet contenant les données de l'entreprise/tenant propriétaire du processus.
simulated	Booléen ; indique s'il s'agit d'un processus de simulation/sandbox (true) ou réel (false).

Champs de la personne

Champ	Signification
duiType	Type du document d'identification unique. Valeurs DUI_TYPE_* (ex. BR_CPF).
duiValue	Valeur du document (ex. le numéro de CPF).
friendlyName	Nom convivial/surnom de la personne (texte libre, non validé).
email	Email de la personne ; peut être vide.
phone	Numéro de téléphone au format E.164 (code pays + code régional + numéro).
notifications	Liste des canaux de notification. Chaque élément porte notificationChannel avec des valeurs NOTIFICATION_CHANNEL_* (ex. WHATSAPP, SMS, EMAIL).
phoneCountryCodeAlpha3	Code pays ISO alpha-3 du numéro de téléphone (ex. BRA) ; peut être vide.

Champs des données de l'entreprise

Champ	Signification
branchId	Identifiant de la succursale du tenant ; vide lorsqu'il n'y a pas de segmentation par succursale.
countryCode	Pays de l'entreprise en ISO alpha-3 (ex. BRA).

Types de document et champs OCR

process.services[].documents[].doc.code rapporte le type de document sous la 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 retournée séparément dans doc.version.

Les types de document qui utilisent le schéma unifié — unified_schema dans la référence des champs — sont rapportés comme le type identifié lors de la capture, en majuscules : IDCARD, DRIVERLICENSE, PASSPORT ou VOTERID. Les passeports américains conservent leur variante au lieu d'être regroupés sous PASSPORT ; des valeurs telles que POLYCARBONATEPASSPORT, PASSPORTCARD et PAPERPASSPORT sont donc également retourné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.

Schémas spécifiques

Les types de document 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 du dictionnaire pour rechercher chaque schéma dans ce fichier.

Pays	doc.code	Type du dictionnaire	Document
BR	RG	unico.moja.dictionary.br.rg.v2.Rg	RG
BR	CNH	unico.moja.dictionary.br.cnh.v2.Cnh	CNH (permis de conduire)
BR	CIN	unico.moja.dictionary.br.cin.v1.Cin	CIN
BR	PASSAPORTE	unico.moja.dictionary.br.passaporte.v1.Passaporte	Passeport
MX	INE	unico.moja.dictionary.mx.ine.v1.Ine	Carte d'électeur INE
MX	LPC	unico.moja.dictionary.mx.lpc.v1.Lpc	Licencia para conducir (permis de conduire)
MX	PASAPORTE	unico.moja.dictionary.mx.pasaporte.v1.Pasaporte	Passeport
—	UNKNOWN	unico.moja.dictionary.other.unknown.v1.Unknown	Le 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 (deux S) et le mexicain PASAPORTE (un seul S), chacun reflétant l'orthographe de son propre dictionnaire. Ce n'est pas une faute de frappe — ne traitez pas ces deux valeurs comme équivalentes.

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

Les 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": "idchecktrust",
    "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": "smart_revalidation",
    "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_INCONCLUSIVE",
      "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

Champ	Type	Description
process.id	string (UUID)	Identifiant du processus.
process.flow	string	Identifiant du flux envoyé à la création.
process.callbackUri	string	URL de rappel configurée pour les événements du processus.
process.userRedirectUrl	string	URL pour rediriger l'utilisateur après la fin du parcours.
process.state	enum	État actuel du processus. Voir les valeurs ci-dessous.
process.result	enum	Résultat de la vérification. Présent uniquement lorsque state = PROCESS_STATE_FINISHED.
process.createdAt	string (datetime)	Horodatage ISO 8601 de la création du processus.
process.finishedAt	string (datetime)	Horodatage ISO 8601 de la fin du processus. Présent uniquement lorsque state = PROCESS_STATE_FINISHED.
process.expiresAt	string (datetime)	Horodatage ISO 8601 de l'expiration du processus.
process.purpose	string	Objectif du processus tel que configuré dans le flux.
process.clientReference	string	Référence côté client optionnelle pour l'indexation dans le portail.
process.useCase	string	Identifiant du scénario associé au flux.
process.capacities	array of strings	Liste des capacités activées dans ce processus.
process.token	string	JWT signé pour l'intégration SDK.
process.person	object	Identification fournie à la création.
process.person.notifications	array	Canaux de notification configurés pour le parcours (ex. email).
process.authenticationInfo	object	Résultats par capacité. Voir ci-dessous.
process.companyData	object	Contexte de l'entreprise et de la succursale.
process.companyData.branchId	string	Identifiant de la succursale.
process.companyData.countryCode	string	Code pays ISO 3166-1 alpha-2.
process.bioTokenData	object	Informations du processus de référence — présent uniquement dans les flux de Validation 1:1 et de Revalidation intelligente.
process.services	array	Enveloppes signées, documents capturés et autres sorties de service. Voir ci-dessous.

Valeurs de process.state

Valeur	Signification
PROCESS_STATE_CREATED	Processus créé ; l'utilisateur n'a pas encore terminé le parcours.
AWAITING_FOR_DOCUMENT	Processus créé sans document d'identification ; en attente de sa configuration via Définir le document du processus. Présent uniquement lorsque le Custom Flow autorise un document optionnel.
PROCESS_STATE_FINISHED	Parcours terminé. Vérifiez result et authenticationInfo.
PROCESS_STATE_FAILED	Erreur de traitement.

Incohérence de nommage des états

AWAITING_FOR_DOCUMENT ne suit pas la convention de préfixe PROCESS_STATE_* utilisée par les autres états. Il s'agit d'une incohérence de nommage connue dans l'API actuelle.

Valeurs de process.result

Valeur	Signification
PROCESS_RESULT_OK	Toutes les capacités ont retourné des résultats positifs.
PROCESS_RESULT_INVALID_IDENTITY	Au moins une capacité a retourné un résultat définitivement négatif (ex. détection de vie échouée, identité non correspondante).
PROCESS_RESULT_ERROR	Erreur lors du traitement du résultat.
PROCESS_RESULT_EXPIRED	Le processus a expiré avant la fin du parcours.
PROCESS_RESULT_UNSPECIFIED	Le processus n'est pas encore terminé.

Résultats des capacités dans authenticationInfo

Tous les champs sont toujours retournés indépendamment du flux. Les champs pour les capacités non utilisées dans le flux retournent *_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.

Champ	Capacité	Valeurs possibles
authenticationId	—	Identifiant unique pour cette tentative d'authentification.
livenessResult	Détection de Vie	LIVENESS_RESULT_LIVE, LIVENESS_RESULT_NOT_LIVE, LIVENESS_RESULT_UNSPECIFIED
authenticationResult	Vérification d'identité	AUTHENTICATION_RESULT_POSITIVE, AUTHENTICATION_RESULT_NEGATIVE, AUTHENTICATION_RESULT_INCONCLUSIVE, AUTHENTICATION_RESULT_UNSPECIFIED
identityFraudstersResult	Classification du risque de fraude	TRUST_RESULT_YES, TRUST_RESULT_INCONCLUSIVE, TRUST_RESULT_UNSPECIFIED
bioTokenEngineResult	Validation 1:1	BIO_TOKEN_ENGINE_RESULT_POSITIVE, BIO_TOKEN_ENGINE_RESULT_NEGATIVE, BIO_TOKEN_ENGINE_RESULT_UNSPECIFIED
smartRevalidationResult	Revalidation intelligente	SMART_REVALIDATION_RESULT_POSITIVE, SMART_REVALIDATION_RESULT_NEGATIVE, SMART_REVALIDATION_RESULT_UNSPECIFIED
idAgeResult	Vérification de l'âge	ID_AGE_RESULT_POSITIVE, ID_AGE_RESULT_NEGATIVE, ID_AGE_RESULT_INCONCLUSIVE, ID_AGE_RESULT_UNSPECIFIED
scoreEngineResult.scoreEnabled	Score de Risque	SCORE_ENABLED_TRUE, SCORE_ENABLED_FALSE, SCORE_ENABLED_UNSPECIFIED
scoreEngineResult.score	Score de Risque	Nombre de -100 à +100. Présent lorsque authenticationResult = AUTHENTICATION_RESULT_INCONCLUSIVE et que le Score de Risque est activé.
serproResult.score	Retour de similarité Serpro	0–100 (similarité) ; -1 (pas de 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 ne constituent pas une erreur de documentation.

Champ	Type	Description
envelopeId	string (UUID)	Identifiant de l'enveloppe signée.
documentIds	array of strings	IDs des documents capturés dans ce service.
consent_granted	boolean	Si l'utilisateur a accordé le consentement au partage de données.
documents	array	Documents capturés avec données OCR et résultats de validation.
documents[].doc_id	string	Identifiant du document.
documents[].typified	boolean	Si le type de document a été identifié avec succès.
documents[].cpf_match	boolean	Si le CPF sur le document correspond au CPF fourni (Brésil uniquement).
documents[].face_match	boolean	Si le selfie correspond à la photo sur le document.
documents[].validate_doc	boolean	Si le document a passé la validation d'authenticité.
documents[].reused_doc	boolean	Si ce document a été réutilisé depuis un processus précédent.
documents[].signed_url	string	URL pré-signée pour télécharger le PDF du document (valide 5 minutes — refaites l'appel pour renouveler).
documents[].doc.version	integer	Version du schéma OCR.
documents[].doc.code	string	Code court du type de document (ex. CNH). Consultez Types de document et champs OCR pour toutes les valeurs et la façon dont le code est dérivé.
documents[].doc.data	object	Champs 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 retournés en portugais — ce sont les valeurs réelles produites par le moteur OCR.

Codes d'erreur

400 Bad Request

Code	Message	Description
3	process id is invalid	Lorsque l'ID du processus est invalide.

401 Unauthorized

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

404 Not Found

Code	Message	Description
5	error getting process: rpc error: code = NotFound desc = process not found	Lorsque l'ID du processus n'a pas été trouvé.

429 Too Many Requests

Rate limit reached. When your system receives an HTTP 429 error, you must implement mechanisms to prevent cascading failures and avoid worsening the restriction.

Best practices:

• Cool-down period (backoff): Immediately halt or throttle subsequent requests from your system. Do not continuously retry failed requests in a tight loop.
• Queueing & throttling: Buffer or queue outgoing requests on your end to control the traffic flow before re-sending them.
• Exponential backoff with jitter: When retrying, increase the waiting time exponentially between attempts (e.g., 1 s, 2 s, 4 s, 8 s) and add a small random delay ("jitter") to prevent a herd effect where all queued requests retry at the exact same millisecond.

avertissement

Continuously hitting a rate-limited endpoint without backing off can prolong the restriction period and severely impact your system's operational throughput. Properly throttling requests on your side ensures a smoother, more resilient integration.

For default limits, increase requests and additional details, see Rate Limits.

500 Internal Server Error

Code	Message	Description
99999	Internal failure! Try again later	Lorsqu'il y a une erreur interne.

Polling vs webhook

Vous pouvez interroger ce endpoint pour vérifier la progression, mais le modèle recommandé est de s'abonner à un webhook et d'appeler ce endpoint uniquement en secours. Voir Webhooks et événements.

Prochaines étapes

• Pour le selfie capturé, voir Obtenir le selfie.
• Pour le bundle d'audit des preuves, voir Obtenir l'ensemble des preuves.