Obtenir le processus

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
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": "idunicosign",
    "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
      },
      "serproResult": {
        "score": 92
      }
    },
    "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é lors de la création.
`process.callbackUri`	string	URL de callback configurée pour les événements du processus.
`process.userRedirectUrl`	string	URL vers laquelle rediriger l'utilisateur une fois le parcours terminé.
`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 d'expiration du processus.
`process.purpose`	string	Finalité du processus telle que configurée dans le flux.
`process.clientReference`	string	Référence facultative côté client pour l'indexation dans le portail.
`process.useCase`	string	Identifiant du cas d'usage 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 lors de 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 filiale.
`process.companyData.branchId`	string	Identifiant de la filiale.
`process.companyData.countryCode`	string	Code pays ISO 3166-1 alpha-2.
`process.bioTokenData`	object	Informations du processus de référence — présentes 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 qu'il soit défini via Définir le document du processus. Présent uniquement lorsque le flux personnalisé 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 négatif définitif (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`	Processus pas encore terminé.

Résultats des capacités dans authenticationInfo

Tous les champs sont toujours retournés quel que soit le flux. Les champs pour les capacités non utilisées dans le flux retournent *_UNSPECIFIED.

Valeurs enum abrégées

Les formes abrégées (ex. livenessResult = LIVE, authenticationResult = INCONCLUSIVE) correspondent directement aux valeurs 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 de 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 la Classification du risque de fraude est activée.
`serproResult.score`	Retour de similarité Serpro	`0`–`100` (similarité) ; `-1` (aucun visage enregistré pour ce CPF) ; `-2` (erreur d'intégration).

Champs de process.services

Champ	Type	Description
`envelopeId`	string (UUID)	Identifiant de l'enveloppe signée.
`documentIds`	array of strings	Identifiants des documents capturés dans ce service.
`consent_granted`	boolean	Indique si l'utilisateur a accordé son 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	Indique si le type de document a été identifié avec succès.
`documents[].cpf_match`	boolean	Indique si le CPF sur le document correspond au CPF fourni.
`documents[].face_match`	boolean	Indique si le selfie correspond à la photo sur le document.
`documents[].validate_doc`	boolean	Indique si le document a passé la validation d'authenticité.
`documents[].reused_doc`	boolean	Indique 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 — récupérez à nouveau pour renouveler).
`documents[].doc.version`	integer	Version du schéma OCR.
`documents[].doc.code`	string	Code de 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.

400 Bad Request

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

401 Unauthorized

Token Bearer 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.

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'identifiant de processus est invalide.

Message	Description
Jwt header is an invalid JSON	Lorsque le token d'accès utilisé contient des caractères incorrects.
Jwt is expired	Lorsque le token d'accès utilisé a expiré.

Code	Message	Description
`5`	error getting process: rpc error: code = NotFound desc = process not found	Lorsque l'identifiant de processus est introuvable.

Code	Message	Description
`99999`	Internal failure! Try again later	Lorsqu'une erreur interne se produit.

Interrogation vs webhook

Vous pouvez interroger cet endpoint pour vérifier la progression, mais le schéma recommandé est de vous abonner à un webhook et de n'appeler cet endpoint qu'en secours. Voir Webhooks et événements.

Étapes suivantes

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

Point de terminaison​

Requête​

Exemple​

Réponses​

Codes d'erreur​

Interrogation vs webhook​

Étapes suivantes​