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

Champ	Type	Requis	Description
subject.duiType	integer	oui	Identifiant du type de document. Voir valeurs de duiType ci-dessous.
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.

Réutilisation

Champ	Type	Requis	Description
subject.duiType	integer	oui	Identifiant du type de document. Voir valeurs de duiType ci-dessous.
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.

Valeurs de duiType

Pays	Code	Description
BR	1	CPF brésilien
MX	2	CURP mexicain
US	4	SSN américain
BR	5	Passeport brésilien
AR	6	Passeport argentin
AR	7	DNI argentin
NG	8	NIN nigérian
CL	9	RUN chilien
EC	10	NI équatorien
US	11	Passeport américain
GT	12	CUI guatémaltèque
UY	13	CI uruguayen
BR	14	CNPJ brésilien
ZZ	15	Adresse e-mail
ID	16	NIK indonésien
ZZ	17	Numéro de téléphone
US	18	Permis de conduire américain
NG	20	Numéro de vérification bancaire nigérian (BVN)
US	21	Carte de passeport américaine
US	22	Passeport américain en polycarbonate
US	23	Carte d'identité américaine
TR	24	Numéro d'identification turc (TCKN)
MX	25	RFC mexicain (Personne physique)
CO	26	NIT colombien
PE	27	RUC péruvien
CA	28	Numéro d'assurance sociale canadien (NAS)
DK	29	CPR danois
GB	30	Numéro d'assurance nationale britannique (NINO)
PL	31	PESEL polonais
SE	32	Numéro personnel suédois (PNR)
CH	33	Numéro AVS/AHV suisse
AT	34	Numéro fiscal autrichien (STNR)
FI	35	Code d'identité personnelle finlandais (HETU)
BE	36	Numéro national belge (NN)
IT	37	Codice Fiscale italien (CF)
SE	38	Numéro de coordination suédois (Samordningsnummer)
NO	39	Numéro d'identité national norvégien (Fødselsnummer)
PE	40	DNI péruvien
DE	41	Numéro d'identification fiscale allemand (IdNr)
NL	42	Numéro de service citoyen néerlandais (BSN)
NG	43	Jeton BVN nigérian (haché)
NG	44	Jeton NIN nigérian (haché)
PT	45	Numéro d'identification fiscale portugais (NIF)
FR	46	Numéro de référence fiscale français (SPI)
IE	47	Numéro personnel de service public irlandais (PPSN)
LU	48	Numéro d'identification national luxembourgeois (Matricule)
AR	49	Permis de conduire argentin (Licencia Nacional de Conducir)
ES	50	Numéro d'identité d'étranger espagnol (NIE)
ES	51	Document national d'identité espagnol (DNI)
CL	52	Passeport chilien
CO	53	Passeport colombien
PE	54	Passeport péruvien
CO	55	Permis de conduire colombien (Licencia de Conducción)
CO	56	Carte de citoyenneté colombienne (Cédula de Ciudadanía)
CL	57	Permis de conduire chilien (Licencia de Conducir)
MX	58	Permis de conduire mexicain (Licencia de Conducir)
—	0	Non spécifié
—	3	Identifiant interne Unico

Exemple

Nouvelle capture — cURL

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": 1,
      "code": "12345678909",
      "name": "Luke Skywalker"
    },
    "document": {
      "purpose": "onboarding",
      "authProcessId": "80371b2a-3ac7-432e-866d-57fe37896ac6",
      "files": [
        { "data": "/9j/4AAQSkZJR..." }
      ]
    }
  }'

Nouvelle capture — Node.js

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: 1,
      code: '12345678909',
      name: 'Luke Skywalker'
    },
    document: {
      purpose: 'onboarding',
      authProcessId: '80371b2a-3ac7-432e-866d-57fe37896ac6',
      files: [{ data: documentImageBase64 }]
    }
  })
});

const result = await res.json();

Réutilisation — cURL

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": 1,
      "code": "12345678909"
    },
    "document": {
      "purpose": "onboarding",
      "authProcessId": "80371b2a-3ac7-432e-866d-57fe37896ac6",
      "documentId": "doc-abc-123"
    }
  }'

Réutilisation — Node.js

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: 1,
      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é, sous forme de nom de dictionnaire complet. Voir valeurs de document.type ci-dessous.
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 — cliquez ici pour les détails des champs.
document.fileUrls	array	URLs temporaires (validité de 10 minutes) pour télécharger les images du document.

Seuls les champs extraits avec succès sont présents dans document.content ; tout ce que l'OCR n'a pas pu lire est omis plutôt que retourné vide.

Valeurs de document.type

Schéma unifié

Tous les types de document qui utilisent le schéma unifié — unified_schema dans la référence des champs — sont retournés dans document.type sous la forme unico.moja.dictionary.<country>.generic.v1.<DocumentType>, où <country> est le code ISO 3166-1 alpha-2 en minuscules et <DocumentType> le type identifié. Par exemple :

• unico.moja.dictionary.ar.generic.v1.IdCard: Carte d'identité argentine
• unico.moja.dictionary.us.generic.v1.PolycarbonatePassport: Passeport en polycarbonate des États-Unis

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 :

Pays	Valeur	Document
BR	unico.moja.dictionary.br.rg.v2.Rg	RG
BR	unico.moja.dictionary.br.cnh.v2.Cnh	CNH (permis de conduire)
BR	unico.moja.dictionary.br.cin.v1.Cin	CIN
BR	unico.moja.dictionary.br.passaporte.v1.Passaporte	Passeport
MX	unico.moja.dictionary.mx.ine.v1.Ine	Carte d'électeur INE
MX	unico.moja.dictionary.mx.lpc.v1.Lpc	Licencia para conducir (permis de conduire)
MX	unico.moja.dictionary.mx.pasaporte.v1.Pasaporte	Passeport
—	unico.moja.dictionary.other.unknown.v1.Unknown	Le type n'a pas pu être identifié — document.content est vide

Aucune extraction OCR n'est effectuée et aucun champ n'est renvoyé lorsque document.type est unico.moja.dictionary.other.unknown.v1.Unknown.

Codes d'erreur

400 Bad Request

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.

403 Forbidden

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

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.

409 Conflict

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

500 Internal Server Error

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.