Crear Proceso de Documento

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

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

Ejemplo

Nueva captura — cURL
Nueva captura — Node.js
Reutilización — cURL
Reutilización — 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": 1,
      "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: 1,
      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": 1,
      "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: 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
403 Forbidden
409 Conflict
500 Internal Server Error

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.

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.

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

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.

Endpoint​

Solicitud​

Ejemplo​

Respuestas​

Códigos de Error​

Qué sigue​