Créez un processus sans document, laissez l'utilisateur terminer la capture, puis envoyez le document depuis votre back-end. Le processus reprend ensuite.
Cycle de vie
- Votre back-end crée le processus avec Créer un processus, sans
person.duiTypeniperson.duiValue. Le flux doit autoriser un document optionnel. Le processus démarre à l'étatPROCESS_STATE_CREATED. - L'utilisateur suit le parcours et effectue la capture.
- La Unico API fait passer le processus à
PROCESS_STATE_AWAITING_FOR_DOCUMENT, l'état que Récupérer un processus renvoie tant que le processus attend le document. Vous pouvez déjà lire les résultats partiels des capacités qui ne dépendent pas deduiValue. - Votre back-end appelle cet endpoint avec l'ID du processus dans l'URL et le document dans le corps. Le processus revient à
PROCESS_STATE_CREATEDet reprend : les capacités qui dépendent du document s'exécutent, et le processus passe àPROCESS_STATE_FINISHEDlorsqu'elles se terminent.
Lisez l'état final et le résultat avec Récupérer un processus, ou attendez le webhook.
Endpoint
| Environnement | URL |
|---|---|
| Production | POST https://api.idcloud.unico.app/client/v1/process/{processId}/document |
| Sandbox | POST https://api.idcloud.uat.unico.app/client/v1/process/{processId}/document |
Requête
| En-tête | Valeur |
|---|---|
Authorization | Bearer <access_token> (voir Authentification) |
Content-Type | application/json |
Les identifiants doivent disposer de la même permission que celle utilisée pour appeler Créer un processus.
| Paramètre | Type | Requis | Description |
|---|---|---|---|
processId | string (UUID) | oui | Identifiant du processus renvoyé par Créer un processus. |
| Champ | Type | Requis | Description |
|---|---|---|---|
duiType | enum | oui | Type de document. DUI_TYPE_UNSPECIFIED est rejeté. Voir les valeurs de duiType ci-dessous. |
duiValue | string | oui | Numéro du document, sans mise en forme. Jusqu'à 320 caractères. |
Valeurs de duiType
| Pays | Valeur | Description |
|---|---|---|
| AR | DUI_TYPE_AR_PASSPORT | Passeport argentin |
| AR | DUI_TYPE_AR_DNI | DNI argentin |
| AR | DUI_TYPE_AR_LNC | Permis de conduire argentin (Licencia Nacional de Conducir) |
| AT | DUI_TYPE_AT_STNR | Numéro fiscal autrichien (STNR) |
| BE | DUI_TYPE_BE_NN | Numéro national belge (NN) |
| BR | DUI_TYPE_BR_CPF | CPF brésilien |
| BR | DUI_TYPE_BR_PASSPORT | Passeport brésilien |
| BR | DUI_TYPE_BR_CNPJ | CNPJ brésilien |
| CA | DUI_TYPE_CA_SIN | NAS canadien |
| CH | DUI_TYPE_CH_AHV | Numéro AVS/AHV suisse |
| CL | DUI_TYPE_CL_RUN | RUN chilien |
| CL | DUI_TYPE_CL_PASSPORT | Passeport chilien |
| CL | DUI_TYPE_CL_LICENCIA_CONDUCIR | Permis de conduire chilien (Licencia de Conducir) |
| CO | DUI_TYPE_CO_NIT | NIT colombien |
| CO | DUI_TYPE_CO_PASSPORT | Passeport colombien |
| CO | DUI_TYPE_CO_LICENCIA_CONDUCCION | Permis de conduire colombien (Licencia de Conducción) |
| CO | DUI_TYPE_CO_CC | Carte de citoyenneté colombienne (Cédula de Ciudadanía) |
| DE | DUI_TYPE_DE_IDNR | Numéro d'identification fiscale allemand (IdNr) |
| DK | DUI_TYPE_DK_CPR | CPR danois |
| EC | DUI_TYPE_EC_NI | NI équatorien |
| ES | DUI_TYPE_ES_NIE | Numéro d'identité d'étranger espagnol (NIE) |
| ES | DUI_TYPE_ES_DNI | Document national d'identité espagnol (DNI) |
| FI | DUI_TYPE_FI_HETU | Code d'identité personnelle finlandais (HETU) |
| FR | DUI_TYPE_FR_SPI | Numéro de référence fiscale français (SPI) |
| GB | DUI_TYPE_GB_NINO | Numéro d'assurance nationale britannique (NINO) |
| GT | DUI_TYPE_GT_CUI | CUI guatémaltèque |
| ID | DUI_TYPE_ID_NIK | NIK indonésien |
| IE | DUI_TYPE_IE_PPSN | Numéro personnel de service public irlandais (PPSN) |
| IT | DUI_TYPE_IT_CF | Codice Fiscale italien (CF) |
| LK | DUI_TYPE_LK_NIC | NIC du Sri Lanka |
| LU | DUI_TYPE_LU_MATRICULE | Numéro d'identification national luxembourgeois (Matricule) |
| MX | DUI_TYPE_MX_CURP | CURP mexicain |
| MX | DUI_TYPE_MX_RFC_PERSONA_FISICA | RFC mexicain (Persona Física) |
| MX | DUI_TYPE_MX_LICENCIA_CONDUCIR | Permis de conduire mexicain (Licencia de Conducir) |
| NG | DUI_TYPE_NG_NIN | NIN nigérian |
| NG | DUI_TYPE_NG_BVN | Numéro de vérification bancaire nigérian (BVN) |
| NG | DUI_TYPE_NG_BVN_TOKEN | Jeton BVN nigérian (haché) |
| NG | DUI_TYPE_NG_NIN_TOKEN | Jeton NIN nigérian (haché) |
| NL | DUI_TYPE_NL_BSN | Numéro de service aux citoyens néerlandais (BSN) |
| NO | DUI_TYPE_NO_FNR | Numéro d'identité national norvégien (Fødselsnummer) |
| PE | DUI_TYPE_PE_RUC | RUC péruvien |
| PE | DUI_TYPE_PE_DNI | DNI péruvien |
| PE | DUI_TYPE_PE_PASSPORT | Passeport péruvien |
| PL | DUI_TYPE_PL_PESEL | PESEL polonais |
| PT | DUI_TYPE_PT_NIF | Numéro d'identification fiscale portugais (NIF) |
| SE | DUI_TYPE_SE_PNR | Numéro personnel suédois (PNR) |
| SE | DUI_TYPE_SE_SAMORDNINGSNUMMER | Numéro de coordination suédois (Samordningsnummer) |
| TR | DUI_TYPE_TR_TCKN | Numéro d'identification turc (TCKN) |
| US | DUI_TYPE_US_SSN | SSN des États-Unis |
| US | DUI_TYPE_US_PASSPORT | Passeport des États-Unis |
| US | DUI_TYPE_US_DRIVER_LICENSE | Permis de conduire des États-Unis |
| US | DUI_TYPE_US_PASSPORT_CARD | Carte de passeport des États-Unis |
| US | DUI_TYPE_US_POLYCARBONATE_PASSPORT | Passeport en polycarbonate des États-Unis |
| US | DUI_TYPE_US_ID_CARD | Carte d'identité des États-Unis |
| UY | DUI_TYPE_UY_CI | CI uruguayenne |
| ZZ | DUI_TYPE_ZZ_EMAIL | Adresse e-mail |
| ZZ | DUI_TYPE_ZZ_PHONE_NUMBER | Numéro de téléphone |
- Le processus est à l'état
PROCESS_STATE_AWAITING_FOR_DOCUMENT: l'utilisateur a déjà terminé la capture. - Le processus n'a pas expiré.
- Le flux autorise un document optionnel.
Le document est immuable. Un second appel échoue, car le processus n'attend plus de document.
Exemple
- cURL
- Node.js
curl -X POST https://api.idcloud.unico.app/client/v1/process/$PROCESS_ID/document \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"duiType": "DUI_TYPE_BR_CPF",
"duiValue": "12345678909"
}'
import fetch from 'node-fetch';
const res = await fetch(
`https://api.idcloud.unico.app/client/v1/process/${processId}/document`,
{
method: 'POST',
headers: {
Authorization: `Bearer ${accessToken}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
duiType: 'DUI_TYPE_BR_CPF',
duiValue: '12345678909',
}),
}
);
const { processId: id, duiType, duiValue } = await res.json();
Réponses
{
"processId": "3116552c-6a3e-4c1f-9d2b-8f0e7a5b4c21",
"duiType": "DUI_TYPE_BR_CPF",
"duiValue": "12345678909"
}
| Champ | Type | Description |
|---|---|---|
processId | string (UUID) | Identifiant du processus. |
duiType | enum | Type de document enregistré pour le processus. |
duiValue | string | Numéro du document enregistré pour le processus. |
Les valeurs de l'exemple sont fictives.
Codes d'erreur
- 400 Bad Request
- 401 Unauthorized
- 403 Forbidden
- 404 Not Found
- 429 Too Many Requests
- 500 Internal Server Error
| Code | Description |
|---|---|
3 | processId est absent ou invalide, duiType n'est pas spécifié, ou duiValue est vide ou dépasse 320 caractères. |
3 | duiValue n'est pas un numéro valide pour le duiType indiqué. |
9 | Le processus n'attend pas de document (y compris lorsqu'un document a déjà été défini), a expiré ou est terminé, ou le flux n'autorise pas de document optionnel. |
| 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 | Description |
|---|---|
7 | Les identifiants ne disposent pas de la permission requise par Créer un processus. |
| Code | Description |
|---|---|
5 | Le processus n'existe pas ou n'appartient pas à votre entreprise. |
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 repos (backoff) : Arrêtez ou réduisez immédiatement les requêtes suivantes de votre système. Ne réessayez pas continuellement les requêtes échouées dans une boucle serrée.
- File d'attente et limitation (Queueing & throttling) : Mettez en mémoire 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 essais (par exemple, 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.
Envoyer continuellement des requêtes vers un endpoint soumis à une limite de débit sans appliquer 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é garantit 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, consultez Limites de débit.
| Code | Description |
|---|---|
13 | Le document n'a pas pu être enregistré. |
Le document est enregistré auprès du service d'identité avant d'être stocké. Si cet enregistrement échoue, l'appel renvoie le statut de cet échec.
Prochaines étapes
- Pour lire l'état final et le résultat, voir Récupérer un processus.
- Pour être notifié lorsque le processus se termine, voir Webhooks et événements.