Crear proceso

Este endpoint maneja dos casos de uso que comparten la misma ruta pero difieren en parámetros del cuerpo, capacidades y campos de respuesta:

Registro - valida quién es el usuario comparando su rostro con la base de identidad de Unico (subject.duiType + subject.code requerido).
Transaccional - verifica que es la misma persona de un proceso anterior comparando rostro con rostro (referenceProcessId O array references con selfie / ID de proceso requerido).

El caso de uso activo se determina por la APIKEY enviada en el encabezado de la solicitud.

Para el flujo de integración completo, consulte 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

Encabezados

Encabezado	Valor
`Authorization`	`Bearer <access_token>` (consulte Autenticación)
`APIKEY`	Clave API provisionada: define el caso de uso activo y las capacidades habilitadas.
`Content-Type`	`application/json`

Parámetros del cuerpo

Registro
Transaccional

Campo	Tipo	Requerido	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 según lo definido por `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 E.164.
`useCase`	string	no	Contexto de la operación, por ejemplo, `Onboarding`.
`subsidiaryId`	string	no	ID de sucursal — requerido solo si existen múltiples sucursales.
`imageBase64`	string	sí	Selfie capturado por su front-end, en base64.

Campo	Tipo	Requerido	Descripción
`references`	array	condicional	Entradas de referencia para flujos de Validación 1:1. Cada elemento contiene `referenceType` (`REFERENCE_TYPE_IMAGE_BASE64` o `REFERENCE_TYPE_PROCESS_ID`) y `referenceContent` (imagen codificada en base64 o UUID del proceso).
`referenceProcessId`	string	condicional	Obsoleto. Use `references` en su lugar. ID del proceso de Registro de referencia para comparar. Si la referencia es un proceso by-Unico, use `authenticationInfo.authenticationId`.
`imageBase64`	string	sí	Selfie capturado por su front-end, en base64.
`subject`	object	no	Contenedor de información del usuario.
`subject.duiType`	string	no	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	no	Valor del identificador según lo definido por `subject.duiType`. Sin puntos ni guiones.
`subject.name`	string	no	Nombre completo del usuario.
`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 E.164.
`useCase`	string	no	Contexto de la operación, por ejemplo, `Transactional`.
`subsidiaryId`	string	no	ID de sucursal: requerido solo si existen múltiples sucursales.

información

Para este caso de uso, no es posible orquestar con Score de Riesgo. El resultado siempre se devuelve sincrónicamente en la respuesta POST.

Valores de duiType

País	Código	Descripción
BR	1	CPF brasileño
BR	5	Pasaporte brasileño
MX	2	CURP mexicano
AR	6	Pasaporte argentino
AR	7	DNI argentino
US	4	SSN de Estados Unidos
US	11	Pasaporte de Estados Unidos
US	18	Licencia de conducir de Estados Unidos
ID	16	NIK indonesio
NG	8	NIN nigeriano
CL	9	RUN chileno
EC	10	NI ecuatoriano
GT	12	CUI guatemalteco
UY	13	CI uruguayo
ZZ	15	Dirección de correo electrónico
ZZ	17	Número de teléfono
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)
AT	34	Número de impuesto austríaco (STNR)
FI	35	Código de identidad personal finlandés (HETU)
—	0	No especificado
—	3	Identificador interno de Unico

Requisitos de imagen

Resolución mínima: 640 x 480 (estándar HD)
Tamaño máximo de archivo: 800 KB (se recomienda compresión JPEG92)
Formatos aceptados: PNG, JPEG, WebP
Los tokens JWT del SDK expiran después de 10 minutos y solo pueden usarse una vez

Ejemplo

Registro - cURL
Registro - Node.js
Transaccional - cURL
Transaccional - 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",
      "gender": "M",
      "birthDate": "2000-05-20",
      "email": "[email protected]",
      "phone": "5519725570707"
    },
    "useCase": "Onboarding",
    "imageBase64": "/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',
      gender: 'M',
      birthDate: '2000-05-20',
      email: '[email protected]',
      phone: '5519725570707'
    },
    useCase: 'Onboarding',
    imageBase64: capturedImage
  })
});

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 '{
    "references": [
      {
        "referenceType": "REFERENCE_TYPE_PROCESS_ID",
        "referenceContent": "4f00b35f-69d4-415a-a843-d975cefcb169"
      }
    ],
    "useCase": "Transactional",
    "imageBase64": "/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({
    references: [
      {
        referenceType: 'REFERENCE_TYPE_PROCESS_ID',
        referenceContent: '4f00b35f-69d4-415a-a843-d975cefcb169'
      }
    ],
    useCase: 'Transactional',
    imageBase64: capturedImage
  })
});

const result = await res.json();

Respuestas

Registro
Transaccional

200 OK

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "unicoId": {
    "result": "yes"
  },
  "riskLevel": {
    "result": "inconclusive"
  },
  "idFace": {
    "personId": "a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890",
    "result": "FOUND"
  },
  "government": {
    "serpro": 87
  },
  "liveness": 1
}

Los campos de respuesta dependen de tu APIKey

El ejemplo anterior muestra todos los campos de capacidad posibles. Tu respuesta real solo incluirá los campos correspondientes a las capacidades habilitadas en la configuración de tu APIKey — los campos de capacidades deshabilitadas se omiten por completo. Contacta a tu gestor de proyecto de Unico para habilitar o ajustar las capacidades.

Campo	Tipo	Descripción
`id`	string (UUID)	Identificador del proceso. Use con Obtener proceso para re-consultas.
`status`	integer	`1` (procesando), `3` (finalizado con éxito), `5` (error).
`unicoId.result`	string	`yes`, `no`, `inconclusive` - consulte Verificación de Identidad.
`riskLevel.result`	string	`approved`, `reproved`, `risk-critical`, `risk-high`, `inconclusive` — consulte los valores posibles a continuación o Clasificación de Riesgo de Fraude.
`idFace.result`	string	`FOUND`, `NOT_FOUND` — consulte Identificador Facial.
`idFace.personId`	string	Identificador opaco estable para el rostro. Presente solo cuando `idFace.result = FOUND`.
`identityFraudsters.result`	string	Obsoleto. Use `riskLevel` en su lugar. Los clientes con integraciones en curso pueden seguir usándolo mientras coordinan la migración con el equipo responsable del proyecto.
`government.serpro`	integer	Puntuación de similitud Serpro (0-100, -1, -2). Disponible solo en Brasil. Consulte Retorno de Similitud Serpro.
`liveness`	integer	`1` (aprobado), `2` (fallido) - consulte Detección de Vida.

riskLevel.result — valores posibles

Valor	Significado
`approved`	Es el rostro del titular del ID y no se encontró ninguna evidencia relacionada con fraude.
`reproved`	Se recomienda el rechazo, ya que se detectaron múltiples indicadores de fraude.
`risk-critical`	Se recomienda el rechazo, pero la decisión final queda a su criterio. El riesgo crítico indica que se encontraron al menos 2 evidencias sólidas de fraude.
`risk-high`	También se recomienda el rechazo, pero la decisión es suya. El riesgo alto indica que se encontró al menos una evidencia sólida de fraude.
`inconclusive`	No se encontraron evidencias sólidas de fraude. Por lo tanto, no es posible concluir si existe un riesgo relevante o no.

información

Cuando unicoId.result = inconclusive y la orquestación de Score de Riesgo está activa, el proceso puede devolver status: 1 (procesando). Consulte Obtener proceso o use webhooks para recuperar el resultado final.

200 OK

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "biometryToken": {
    "result": true
  },
  "liveness": 1
}

Campo	Tipo	Descripción
`id`	string (UUID)	Identificador del proceso.
`status`	integer	`3` (finalizado con éxito), `5` (error). Para todos los valores posibles, consulte Obtener proceso.
`biometryToken.result`	boolean	`true` si el rostro enviado coincide con el proceso de referencia; `false` en caso contrario.
`liveness`	integer	`1` (aprobado), `2` (fallido) - consulte Detección de Vida.

400 Bad Request

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

403 Forbidden

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

409 Conflict

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

429 Too Many Requests

Límite de tasa alcanzado. Cuando su sistema recibe un error HTTP 429, debe implementar mecanismos para prevenir fallos en cascada y evitar empeorar la restricción.

Mejores prácticas:

Período de espera (backoff): Detenga o limite inmediatamente las solicitudes subsecuentes de su sistema. No reintente continuamente solicitudes fallidas en un bucle cerrado.
Cola y limitación: Almacene en buffer o encole las solicitudes salientes de su lado para controlar el flujo de tráfico antes de reenviarlas.
Backoff exponencial con jitter: Al reintentar, aumente el tiempo de espera exponencialmente entre intentos (por ejemplo, 1 s, 2 s, 4 s, 8 s) y agregue un pequeño retraso aleatorio ("jitter") para prevenir un efecto manada donde todas las solicitudes en cola reintentan en el mismo milisegundo.

advertencia

Golpear continuamente un endpoint con límite de tasa sin aplicar backoff puede prolongar el período de restricción e impactar severamente el rendimiento operativo de su sistema. Limitar adecuadamente las solicitudes de su lado asegura una integración más fluida y resiliente.

Para límites predeterminados, solicitudes de aumento y detalles adicionales, consulte Límites de tasa.

Códigos de error

400 Bad Request
403 Forbidden
409 Conflict
500 Internal Server Error

Código	Mensaje	Descripción
`20900`	O base64 informado não é válido.	El parámetro base64 es inválido. Posibles causas: 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.
`20513`	The referenced process was not found.	El `referenceProcessId` apunta a un proceso que no existe o ya no es accesible.
`20512`	The referenced process is not available for reuse.	El proceso referenciado existe pero no está disponible para reutilización.
`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.	CPF no estándar o inexistente.
`20506`	O base64 informado é muito grande. O tamanho máximo suportado é até 800kb.	El tamaño de la imagen excede 800 KB; comprima 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 compatible.
`20065`	The referenceProcessId field is invalid.	El `referenceProcessId` no es un UUID válido.
`20062`	The useCase field is invalid.	Valor no reconocido en el campo `useCase`.
`20024`	The referenceProcessId field is missing.	No se proporcionó el parámetro `referenceProcessId` y no se envió `references` como alternativa.
`20021`	The subject.phone field is invalid.	Formato de `subject.phone` inválido (IDD + 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 selfie.
`20008`	The subject.email field is invalid.	Formato de correo electrónico inválido en `subject.email`.
`20006`	O parâmetro subject.name não foi informado.	Falta el parámetro subject.name.
`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.	Falta el parámetro APIKEY en el encabezado de la solicitud.
`20001`	O parâmetro authtoken não foi informado.	Falta el parámetro del token de integración 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 10 minutos.
`10506`	The imageBase64 field is not a valid JWT from SDK.	El `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 token de acceso 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 hay un error interno.

Qué sigue

Para consultar el resultado de un proceso de Registro, consulte Obtener proceso.
Para operaciones de Documento y Verificación de Edad, consulte las páginas respectivas en esta sección.

Endpoint​

Solicitud​

Ejemplo​

Respuestas​

Códigos de error​

Qué sigue​