Get Process

avertissement

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

Point de terminaison

Endpoint

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
Node.js

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

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": "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 cas d'utilisation 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 soumission via Set Process Document. 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.
`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 du type de document (ex. `CNH`, `RG`).
`documents[].doc.data`	object	Champs OCR extraits. Le contenu varie selon le type de document et les données disponibles. 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.

400 Bad Request

Le paramètre de chemin processId est manquant ou malformé.

401 Unauthorized

Le Bearer token est manquant, expiré ou invalide.

404 Not Found

Le processId n'existe pas ou n'appartient pas au tenant authentifié.

429 Too Many Requests

Limite de débit atteinte. Lorsque votre système reçoit une erreur HTTP 429, vous devez implémenter des mécanismes pour prévenir les défaillances en cascade et éviter d'aggraver la restriction.

Bonnes pratiques :

Période de refroidissement (backoff) : Arrêtez ou limitez immédiatement les requêtes suivantes de votre système. Ne réessayez pas continuellement les requêtes échouées en boucle serrée.
Mise en file d'attente et limitation : Mettez en tampon ou en file d'attente les requêtes sortantes de votre côté pour contrôler le flux de trafic avant de les renvoyer.
Backoff exponentiel avec jitter : Lors des nouvelles tentatives, augmentez le temps d'attente de manière exponentielle entre les tentatives (ex. : 1 s, 2 s, 4 s, 8 s) et ajoutez un petit délai aléatoire (« jitter ») pour éviter un effet de troupeau où toutes les requêtes en file d'attente réessaient exactement à la même milliseconde.

avertissement

Frapper continuellement un endpoint limité en débit sans faire de backoff peut prolonger la période de restriction et impacter sévèrement le débit opérationnel de votre système. Limiter correctement les requêtes de votre côté assure une intégration plus fluide et plus résiliente.

Pour les limites par défaut, l'augmentation des requêtes et des détails supplémentaires, voir Limites de débit.

Codes d'erreur

400 Bad Request
401 Unauthorized
404 Not Found
429 Too Many Requests
500 Internal Server Error

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

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

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

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 Get Selfie.
Pour le bundle d'audit des preuves, voir Get Evidence Set.

Point de terminaison​

Endpoint​

Requête​

Exemple​

Réponses​

Codes d'erreur​

Polling vs webhook​

Prochaines étapes​