Créer un processus de document

Ce point de terminaison gère deux flux de traitement de documents qui partagent le même chemin mais diffèrent par les paramètres du corps :

Nouvelle capture — soumet des images de document en base64 pour traitement (document.files requis).
Réutilisation — ignore la capture en référençant un document précédemment capturé (document.documentId requis).

Le flux actif est déterminé par la présence ou l'absence de document.documentId dans le corps de la requête.

Avant de créer un processus de document, utilisez Récupérer les documents réutilisables pour vérifier si l'utilisateur dispose déjà d'un document disponible à la réutilisation.

Pour le flux d'intégration complet, voir Vue d'ensemble de l'API.

Point de terminaison

Environnement	URL
Production	`POST https://api.id.unico.app/processes/v1`
Sandbox	`POST https://api.id.uat.unico.app/processes/v1`

Requête

En-têtes

En-tête	Valeur
`Authorization`	`Bearer <access_token>` (voir Authentification)
`APIKEY`	Clé API provisionnée avec la capture et la réutilisation de documents activées.
`Content-Type`	`application/json`

Paramètres du corps

Nouvelle capture
Réutilisation

Champ	Type	Requis	Description
`subject.duiType`	string	oui	Type d'identifiant. Valeurs possibles : `DUI_TYPE_BR_CPF`, `DUI_TYPE_MX_CURP`, `DUI_TYPE_US_SSN`, `DUI_TYPE_NG_NIN`, `DUI_TYPE_AR_DNI`, `DUI_TYPE_ID_NIK`.
`subject.code`	string	oui	Valeur de l'identifiant de l'utilisateur selon `subject.duiType`. Sans points ni tirets.
`subject.name`	string	non	Nom complet.
`subject.gender`	string	non	`M` ou `F`.
`subject.birthDate`	string (ISO 8601)	non	Date de naissance (`YYYY-MM-DD`).
`subject.email`	string	non	Adresse e-mail.
`subject.phone`	string	non	Numéro de téléphone au format E.164.
`document.purpose`	string	oui	Finalité métier. Valeurs : `creditprocess`, `carpurchase`, `paybypaycheck`, `onboarding`, `fgts`.
`document.authProcessId`	string	oui	ID du processus biométrique lié à cette capture de document.
`document.files`	array	oui	Images du document en base64 (recto et/ou verso).
`document.files[].data`	string	oui	Image du document en base64 (PNG, JPEG ou WebP, max 800 Ko).
`subsidiaryId`	string	non	ID de la filiale — requis uniquement si plusieurs filiales existent.

Champ	Type	Requis	Description
`subject.duiType`	string	oui	Type d'identifiant. Valeurs possibles : `DUI_TYPE_BR_CPF`, `DUI_TYPE_MX_CURP`, `DUI_TYPE_US_SSN`, `DUI_TYPE_NG_NIN`, `DUI_TYPE_AR_DNI`, `DUI_TYPE_ID_NIK`.
`subject.code`	string	oui	Valeur de l'identifiant de l'utilisateur selon `subject.duiType`. Sans points ni tirets.
`subject.name`	string	non	Nom complet.
`subject.gender`	string	non	`M` ou `F`.
`subject.birthDate`	string (ISO 8601)	non	Date de naissance (`YYYY-MM-DD`).
`subject.email`	string	non	Adresse e-mail.
`subject.phone`	string	non	Numéro de téléphone au format E.164.
`document.purpose`	string	oui	Finalité métier. Valeurs : `creditprocess`, `carpurchase`, `paybypaycheck`, `onboarding`, `fgts`.
`document.authProcessId`	string	oui	ID du processus biométrique lié à ce document.
`document.documentId`	string	oui	ID d'un document précédemment capturé (obtenu depuis Récupérer les documents réutilisables). Lorsqu'il est fourni, `document.files` peut être omis.
`subsidiaryId`	string	non	ID de la filiale — requis uniquement si plusieurs filiales existent.

Exemple

Nouvelle capture — cURL
Nouvelle capture — Node.js
Réutilisation — cURL
Réutilisation — Node.js

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": {
      "duiType": "DUI_TYPE_BR_CPF",
      "code": "12345678909",
      "name": "Luke Skywalker"
    },
    "document": {
      "purpose": "onboarding",
      "authProcessId": "80371b2a-3ac7-432e-866d-57fe37896ac6",
      "files": [
        { "data": "/9j/4AAQSkZJR..." }
      ]
    }
  }'

import fetch from 'node-fetch';

const res = await fetch('https://api.id.unico.app/processes/v1', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
    'APIKEY': process.env.UNICO_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    subject: {
      duiType: 'DUI_TYPE_BR_CPF',
      code: '12345678909',
      name: 'Luke Skywalker'
    },
    document: {
      purpose: 'onboarding',
      authProcessId: '80371b2a-3ac7-432e-866d-57fe37896ac6',
      files: [{ data: documentImageBase64 }]
    }
  })
});

const result = await res.json();

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": {
      "duiType": "DUI_TYPE_BR_CPF",
      "code": "12345678909"
    },
    "document": {
      "purpose": "onboarding",
      "authProcessId": "80371b2a-3ac7-432e-866d-57fe37896ac6",
      "documentId": "doc-abc-123"
    }
  }'

import fetch from 'node-fetch';

const res = await fetch('https://api.id.unico.app/processes/v1', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
    'APIKEY': process.env.UNICO_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    subject: {
      duiType: 'DUI_TYPE_BR_CPF',
      code: '12345678909'
    },
    document: {
      purpose: 'onboarding',
      authProcessId: '80371b2a-3ac7-432e-866d-57fe37896ac6',
      documentId: 'doc-abc-123'
    }
  })
});

const result = await res.json();

Réponses

200 OK

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "document": {
    "id": "doc-abc-123",
    "type": "unico.moja.dictionary.br.cnh.v2.Cnh",
    "cpfMatch": true,
    "faceMatch": true,
    "content": {
      "numero": "12345678",
      "nomeCivil": "Luke Skywalker",
      "dataNascimento": "2000-05-20T00:00:00Z",
      "categoria": "B",
      "dataExpiracao": "2030-05-20T00:00:00Z"
    },
    "fileUrls": [
      "https://storage.unico.app/documents/doc-abc-123/front.jpg"
    ]
  }
}

Champ	Type	Description
`id`	string (UUID)	Identifiant du processus.
`status`	integer	`3` (terminé avec succès), `5` (terminé avec échec).
`document.id`	string	Identifiant du document capturé. Utilisez cette valeur dans les futures requêtes `document.documentId` pour la réutilisation.
`document.type`	string	Type de document identifié. Valeurs possibles : `unico.moja.dictionary.br.rg.v2.Rg`, `unico.moja.dictionary.br.cnh.v2.Cnh`, `unico.moja.dictionary.br.cin.v1.Cin`, `unico.moja.dictionary.br.passaporte.v1.Passaporte`.
`document.cpfMatch`	boolean	`true` si l'identifiant extrait du document correspond à `subject.code`.
`document.faceMatch`	boolean	`true` si le visage sur le document correspond au selfie biométrique de `document.authProcessId`.
`document.content`	object	Champs extraits par OCR. La structure varie selon le type de document.
`document.fileUrls`	array	URLs temporaires (validité de 10 minutes) pour télécharger les images du document.

400 Bad Request

La charge utile est malformée, l'image est invalide ou des champs requis sont manquants. Voir Codes d'erreur ci-dessous.

403 Forbidden

Jeton Bearer ou APIKEY manquant, expiré ou invalide. Voir Authentification.

409 Conflict

Le processId fourni existe déjà pour ce locataire. Voir Codes d'erreur ci-dessous.

Codes d'erreur

400 Bad Request
403 Forbidden
409 Conflict
500 Internal Server Error

Code	Message	Description
`99989`	The document is invalid.	L'objet `document` a une structure invalide.
`99988`	The document is empty.	L'objet `document` est absent du corps de la requête.
`20900`	O base64 informado não é válido.	Le paramètre base64 est invalide. Causes possibles : ce n'est pas une image ou il s'agit d'une tentative d'injection.
`20807`	A imagem precisa estar no padrão HD ou possuir uma resolução superior a 640 x 480.	La résolution de l'image téléchargée est trop faible.
`20509`	The subject.name field is invalid.	`subject.name` contient des caractères invalides.
`20508`	The subject.gender field is invalid.	`subject.gender` doit être `M` ou `F`.
`20507`	O parâmetro subject.code é inválido.	Valeur d'identifiant non standard ou inexistante.
`20506`	O base64 informado é muito grande. O tamanho máximo suportado é até 800kb.	La taille de l'image dépasse 800 Ko ; compressez en JPEG92.
`20505`	O base64 informado não é suportado. Os formatos aceitos são png, jpeg e webp.	Le format base64 est invalide ou non pris en charge.
`20068`	The document.documentId or document.files parameter must be present.	Ni `document.documentId` ni `document.files` n'ont été fournis.
`20067`	The document.purpose parameter is invalid.	Valeur non reconnue dans `document.purpose`.
`20066`	The document.authProcessId parameter is invalid.	Valeur invalide dans `document.authProcessId`.
`20062`	The useCase field is invalid.	Valeur non reconnue dans le champ `useCase`.
`20021`	The subject.phone field is invalid.	Le format de `subject.phone` est invalide (IDD + indicatif régional + numéro, 13 caractères).
`20019`	The subject.birthDate field is invalid.	`subject.birthDate` n'est pas au format ISO 8601 (`YYYY-MM-DD`).
`20009`	O parâmetro imagebase64 não foi informado.	Le paramètre d'image du document est manquant.
`20008`	The subject.email field is invalid.	Format d'e-mail invalide dans `subject.email`.
`20005`	O parâmetro subject.code não foi informado.	Le paramètre subject.code est manquant.
`20004`	O parâmetro subject não foi informado.	Le paramètre subject est manquant.
`20003`	The request body is missing or invalid.	Charge utile nulle ou invalide.
`20002`	O parâmetro APIKey não foi informado.	Le paramètre APIKEY est absent de l'en-tête de la requête.
`20001`	O parâmetro authtoken não foi informado.	Le paramètre de jeton d'intégration est absent de l'en-tête de la requête.
`10508`	The JWT with the captured face has already been used.	Le JWT ne peut être utilisé qu'une seule fois.
`10507`	The JWT with the captured face is expired.	JWT expiré ; doit être envoyé dans les 10 minutes.
`10506`	The imageBase64 field is not a valid JWT from SDK.	Le champ `imageBase64` n'est pas un JWT valide généré par le SDK.

Code	Message	Description
`30017`	User does not have permission to perform this action.	JWT malformé ou utilisateur sans permission pour effectuer cette opération.
`10502`	O token informado está expirado.	Le jeton d'accès a expiré.
`10501`	O token informado é inválido.	Le jeton d'authentification est invalide.
`10201`	O AppKey informado é inválido.	L'APIKEY est invalide ou n'existe pas.

Code	Message	Description
`20073`	The processID already exists.	Le `processId` fourni existe déjà pour ce locataire.

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

Étapes suivantes

Pour vérifier si un document est déjà disponible avant cet appel, voir Récupérer les documents réutilisables.
Pour la création d'un processus biométrique (requis pour document.authProcessId), voir Créer un processus.

Point de terminaison​

Requête​

Exemple​

Réponses​

Codes d'erreur​

Étapes suivantes​