Crear Proceso de Documento

MarkdownChatGPTClaude

Este endpoint gestiona dos flujos de documentos que comparten la misma ruta pero difieren en los parámetros del cuerpo:

• Nueva captura — envía imagen(es) del documento en base64 para su procesamiento (se requiere document.files).
• Reutilización — omite la captura referenciando un documento capturado previamente (se requiere document.documentId).

El flujo activo se determina según si se proporciona document.documentId en el cuerpo de la solicitud.

Antes de crear un proceso de documento, usa Obtener Documentos Reutilizables para verificar si el usuario ya tiene un documento disponible para reutilización.

Para el flujo de integración completo, consulta Descripción General de la API.

Endpoint

Entorno	URL
Producción	POST https://api.id.unico.app/processes/v1
Sandbox	POST https://api.id.uat.unico.app/processes/v1

Solicitud

Headers

Header	Valor
Authorization	Bearer <access_token> (ver Autenticación)
APIKEY	Clave de API aprovisionada con Captura y Reutilización de Documentos habilitada.
Content-Type	application/json

Body parameters

Nueva captura

Campo	Tipo	Obligatorio	Descripción
subject.duiType	integer	sí	Identificador del tipo de documento. Consulte valores de duiType a continuación.
subject.code	string	sí	Valor del identificador del usuario según subject.duiType. Sin puntos ni guiones.
subject.name	string	no	Nombre completo.
subject.gender	string	no	M o F.
subject.birthDate	string (ISO 8601)	no	Fecha de nacimiento (YYYY-MM-DD).
subject.email	string	no	Dirección de correo electrónico.
subject.phone	string	no	Número de teléfono en formato E.164.
document.purpose	string	sí	Propósito del negocio. Valores: creditprocess, carpurchase, paybypaycheck, onboarding, fgts.
document.authProcessId	string	sí	ID del proceso biométrico vinculado a esta captura de documento.
document.files	array	sí	Imágenes del documento en base64 (frente y/o dorso).
document.files[].data	string	sí	Imagen del documento en base64 (PNG, JPEG o WebP, máx. 800 KB).
subsidiaryId	string	no	ID de sucursal — requerido solo si existen múltiples sucursales.

Reutilización

Campo	Tipo	Obligatorio	Descripción
subject.duiType	integer	sí	Identificador del tipo de documento. Consulte valores de duiType a continuación.
subject.code	string	sí	Valor del identificador del usuario según subject.duiType. Sin puntos ni guiones.
subject.name	string	no	Nombre completo.
subject.gender	string	no	M o F.
subject.birthDate	string (ISO 8601)	no	Fecha de nacimiento (YYYY-MM-DD).
subject.email	string	no	Dirección de correo electrónico.
subject.phone	string	no	Número de teléfono en formato E.164.
document.purpose	string	sí	Propósito del negocio. Valores: creditprocess, carpurchase, paybypaycheck, onboarding, fgts.
document.authProcessId	string	sí	ID del proceso biométrico vinculado a este documento.
document.documentId	string	sí	ID de un documento capturado previamente (obtenido de Obtener Documentos Reutilizables). Cuando se proporciona, document.files puede omitirse.
subsidiaryId	string	no	ID de sucursal — requerido solo si existen múltiples sucursales.

Valores de duiType

País	Código	Descripción
AR	6	Pasaporte argentino
AR	7	DNI argentino
AR	49	Licencia de conducir argentina (Licencia Nacional de Conducir)
AT	34	Número de impuesto austríaco (STNR)
BE	36	Número Nacional belga (NN)
BR	1	CPF brasileño
BR	5	Pasaporte brasileño
BR	14	CNPJ brasileño
CA	28	SIN canadiense
CH	33	Número AHV/AVS suizo
CL	9	RUN chileno
CL	52	Pasaporte chileno
CL	57	Licencia de conducir chilena (Licencia de Conducir)
CO	26	NIT colombiano
CO	53	Pasaporte colombiano
CO	55	Licencia de conducir colombiana (Licencia de Conducción)
CO	56	Cédula de Ciudadanía colombiana (Cédula de Ciudadanía)
DE	41	Número de Identificación Fiscal alemán (IdNr)
DK	29	CPR danés
EC	10	NI ecuatoriano
ES	50	Número de Identidad de Extranjero español (NIE)
ES	51	Documento Nacional de Identidad español (DNI)
FI	35	Código de identidad personal finlandés (HETU)
FR	46	Número de Referencia Fiscal francés (SPI)
GB	30	Número de Seguro Nacional británico (NINO)
GT	12	CUI guatemalteco
ID	16	NIK indonesio
IE	47	Número de Seguro Social Personal irlandés (PPSN)
IT	37	Código Fiscal italiano (CF)
LU	48	Número de Identificación Nacional de Luxemburgo (Matricule)
MX	2	CURP mexicano
MX	25	RFC mexicano (Persona Física)
MX	58	Licencia de conducir mexicana (Licencia de Conducir)
NG	8	NIN nigeriano
NG	20	Número de Verificación Bancaria nigeriano (BVN)
NG	43	Token BVN nigeriano (hash)
NG	44	Token NIN nigeriano (hash)
NL	42	Número de Servicio al Ciudadano holandés (BSN)
NO	39	Número de Identidad Nacional noruego (Fødselsnummer)
PE	27	RUC peruano
PE	40	DNI peruano
PE	54	Pasaporte peruano
PL	31	PESEL polaco
PT	45	Número de Identificación Fiscal portugués (NIF)
SE	32	Número personal sueco (PNR)
SE	38	Número de Coordinación sueco (Samordningsnummer)
TR	24	Número de Identificación turco (TCKN)
US	4	SSN de Estados Unidos
US	11	Pasaporte de Estados Unidos
US	18	Licencia de conducir de Estados Unidos
US	21	Tarjeta de pasaporte de Estados Unidos
US	22	Pasaporte de policarbonato de Estados Unidos
US	23	Tarjeta de identificación de Estados Unidos
UY	13	CI uruguayo
ZZ	15	Dirección de correo electrónico
ZZ	17	Número de teléfono
—	0	No especificado
—	3	Identificador interno de Unico

Ejemplo

Nueva captura — 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..." }
      ]
    }
  }'

Nueva captura — 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();

Reutilización — 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"
    }
  }'

Reutilización — 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();

Respuestas

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"
    ]
  }
}

Campo	Tipo	Descripción
id	string (UUID)	Identificador del proceso.
status	integer	3 (finalizado con éxito), 5 (finalizado con falla).
document.id	string	Identificador del documento capturado. Usa este valor en futuros pedidos document.documentId para reutilización.
document.type	string	Tipo de documento identificado, como un nombre de diccionario completamente cualificado. Consulta los valores de document.type a continuación.
document.cpfMatch	boolean	true si el identificador extraído del documento coincide con subject.code.
document.faceMatch	boolean	true si el rostro del documento coincide con el selfie biométrico de document.authProcessId.
document.content	object	Campos extraídos por OCR. La estructura varía según el tipo de documento — haz clic aquí para ver los detalles de los campos.
document.fileUrls	array	URLs temporales (validez de 10 minutos) para descargar las imágenes del documento.

Solo los campos extraídos exitosamente están presentes en document.content; todo lo que el OCR no pudo leer se omite en lugar de devolverse vacío.

Valores de document.type

Esquema unificado

Todos los tipos de documento que usan el esquema unificado — unified_schema en la referencia de campos — se reportan en document.type como unico.moja.dictionary.<country>.generic.v1.<DocumentType>, donde <country> es el código ISO 3166-1 alpha-2 en minúsculas y <DocumentType> el tipo identificado. Por ejemplo:

• unico.moja.dictionary.ar.generic.v1.IdCard: Documento de identidad argentino
• unico.moja.dictionary.us.generic.v1.PolycarbonatePassport: Pasaporte de policarbonato de EE. UU.

Esquemas específicos

Los tipos de documento que usan su propio esquema de campos — listados en specific_document_schemas en la referencia de campos — se muestran en la tabla siguiente:

País	Valor	Documento
BR	unico.moja.dictionary.br.rg.v2.Rg	RG
BR	unico.moja.dictionary.br.cnh.v2.Cnh	CNH (licencia de conducir)
BR	unico.moja.dictionary.br.cin.v1.Cin	CIN
BR	unico.moja.dictionary.br.passaporte.v1.Passaporte	Pasaporte
MX	unico.moja.dictionary.mx.ine.v1.Ine	Credencial para votar del INE
MX	unico.moja.dictionary.mx.lpc.v1.Lpc	Licencia para conducir
MX	unico.moja.dictionary.mx.pasaporte.v1.Pasaporte	Pasaporte
—	unico.moja.dictionary.other.unknown.v1.Unknown	No se pudo identificar el tipo — document.content está vacío

No se realiza ninguna extracción de OCR y no se reporta ningún campo cuando document.type es unico.moja.dictionary.other.unknown.v1.Unknown.

Códigos de Error

400 Bad Request

Código	Mensaje	Descripción
99989	The document is invalid.	El objeto document tiene una estructura inválida.
99988	The document is empty.	El objeto document no está presente en el cuerpo de la solicitud.
20900	O base64 informado não é válido.	El parámetro base64 es inválido. Causas posibles: no es una imagen o es un intento de inyección.
20807	A imagem precisa estar no padrão HD ou possuir uma resolução superior a 640 x 480.	La resolución de la imagen cargada es demasiado baja.
20509	The subject.name field is invalid.	subject.name contiene caracteres inválidos.
20508	The subject.gender field is invalid.	subject.gender debe ser M o F.
20507	O parâmetro subject.code é inválido.	Valor de identificador no estándar o inexistente.
20506	O base64 informado é muito grande. O tamanho máximo suportado é até 800kb.	El tamaño de la imagen supera los 800 KB; comprimir a JPEG92.
20505	O base64 informado não é suportado. Os formatos aceitos são png, jpeg e webp.	El formato base64 es inválido o no soportado.
20068	The document.documentId or document.files parameter must be present.	No se proporcionaron ni document.documentId ni document.files.
20067	The document.purpose parameter is invalid.	Valor no reconocido en document.purpose.
20066	The document.authProcessId parameter is invalid.	Valor inválido en document.authProcessId.
20062	The useCase field is invalid.	Valor no reconocido en el campo useCase.
20021	The subject.phone field is invalid.	El formato de subject.phone es inválido (DDI + código de área + número, 13 caracteres).
20019	The subject.birthDate field is invalid.	subject.birthDate está fuera del formato ISO 8601 (YYYY-MM-DD).
20009	O parâmetro imagebase64 não foi informado.	Falta el parámetro de imagen del documento.
20008	The subject.email field is invalid.	Formato de correo electrónico inválido en subject.email.
20005	O parâmetro subject.code não foi informado.	Falta el parámetro subject.code.
20004	O parâmetro subject não foi informado.	Falta el parámetro subject.
20003	The request body is missing or invalid.	Payload nulo o inválido.
20002	O parâmetro APIKey não foi informado.	El parámetro APIKEY no está presente en el encabezado de la solicitud.
20001	O parâmetro authtoken não foi informado.	El parámetro de token de integración no está presente en el encabezado de la solicitud.
10508	The JWT with the captured face has already been used.	El JWT solo puede usarse una vez.
10507	The JWT with the captured face is expired.	JWT expirado; debe enviarse dentro de los 10 minutos.
10506	The imageBase64 field is not a valid JWT from SDK.	El campo imageBase64 no es un JWT válido generado por el SDK.

403 Forbidden

Token Bearer o APIKEY ausente, expirado o inválido. Ver Autenticación.

Código	Mensaje	Descripción
30017	User does not have permission to perform this action.	JWT malformado o usuario sin permiso para realizar esta operación.
10502	O token informado está expirado.	El access-token ha expirado.
10501	O token informado é inválido.	El token de autenticación es inválido.
10201	O AppKey informado é inválido.	La APIKEY es inválida o no existe.

409 Conflict

Código	Mensaje	Descripción
20073	The processID already exists.	El processId proporcionado ya existe para este tenant.

500 Internal Server Error

Código	Mensaje	Descripción
99999	Internal failure! Try again later	Cuando ocurre un error interno.

Qué sigue

• Para verificar si un documento ya está disponible antes de esta llamada, consulta Obtener Documentos Reutilizables.
• Para la creación del proceso biométrico (requerido para document.authProcessId), consulta Crear Proceso.