Crear proceso

Este endpoint maneja dos casos de uso que comparten el mismo path pero difieren en los parámetros del cuerpo, las capacidades y los campos de respuesta:

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

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

Para ver 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>` (consulta Autenticación)
`APIKEY`	Clave de API aprovisionada — define el caso de uso activo y las capacidades habilitadas.
`Content-Type`	`application/json`

Parámetros del cuerpo

Onboarding
Transactional

Campo	Tipo	Requerido	Descripción
`subject.code`	string	sí	CPF (BR) o CURP (MX).
`subject.name`	string	sí	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.
`useCase`	string	no	Contexto de la operación, p. ej. `Onboarding`.
`imageBase64`	string	sí	Selfie capturada por tu 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 de proceso).
`referenceProcessId`	string	condicional	Obsoleto. Usa `references` en su lugar. ID del proceso de Onboarding de referencia con el que comparar. Si la referencia es un proceso by-Unico, usar `authenticationInfo.authenticationId`.
`imageBase64`	string	sí	Selfie capturada por tu front-end, en base64.
`subject`	object	no	Contenedor de información del usuario.
`subject.code`	string	no	CPF (BR) o CURP (MX).
`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 en formato E.164.
`useCase`	string	no	Contexto de la operación, p. ej. `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 la Clasificación de riesgo de fraude. El resultado siempre se devuelve de forma sincrónica en la respuesta del POST.

Requisitos de imagen

Resolución mínima: 640 × 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

Onboarding — cURL
Onboarding — Node.js
Transactional — cURL
Transactional — 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": {
      "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: {
      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 '{
    "referenceProcessId": "80371b2a-3ac7-432e-866d-57fe37896ac6",
    "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({
    referenceProcessId: referenceProcessId,
    useCase: 'Transactional',
    imageBase64: capturedImage
  })
});

const result = await res.json();

Respuestas

Onboarding
Transactional

200 OK

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

Campo	Tipo	Descripción
`id`	string (UUID)	Identificador del proceso. Úsalo con Obtener proceso para reconsultas.
`status`	integer	`1` (procesando), `3` (finalizado con éxito), `5` (error). Para todos los valores posibles, consulta Obtener proceso.
`unicoId.result`	string	`yes`, `no`, `inconclusive` — consulta Verificación de Identidad.
`identityFraudsters.result`	string	`yes`, `inconclusive` — consulta Clasificación de riesgo de fraude.
`government.serpro`	integer	Puntuación de similitud Serpro (0–100, -1, -2). Consulta Retorno de Similitud Serpro.
`liveness`	integer	`1` (aprobado), `2` (fallido) — consulta Detección de Vida.

información

Cuando unicoId.result = inconclusive y la orquestación de Clasificación de riesgo de fraude está activa, el proceso puede devolver status: 1 (procesando). Consulta Obtener proceso mediante polling o usa webhooks para obtener 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, consulta 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) — consulta Detección de Vida.

400 Bad Request

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

403 Forbidden

Token Bearer o APIKEY ausente, vencido o inválido. Consulta Autenticación.

409 Conflict

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

429 Too Many Requests

Límite de tasa alcanzado. Reintenta después del intervalo indicado en el header de respuesta Retry-After. Consulta 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 supera 800 KB; comprime 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.
`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.	El parámetro `referenceProcessId` no fue proporcionado y `references` no se envió como alternativa.
`20021`	The subject.phone field is invalid.	El formato de `subject.phone` es 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 de 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 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 hay un error interno.

Próximos pasos

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

Endpoint​

Solicitud​

Ejemplo​

Respuestas​

Códigos de error​

Próximos pasos​