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`	string	sí	Tipo de identificador. Valores posibles: `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	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`	string	sí	Tipo de identificador. Valores posibles: `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	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.

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": "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();

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. Valores posibles: `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 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 — ver a continuación.
`document.fileUrls`	array	URLs temporales (validez de 10 minutos) para descargar las imágenes del documento.

400 Bad Request

El payload está malformado, la imagen es inválida o faltan campos requeridos. Ver Códigos de Error a continuación.

403 Forbidden

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

409 Conflict

El processId proporcionado ya existe para este tenant. Ver Códigos de Error a continuación.

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.

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​