Crear proceso

Este endpoint maneja tres productos 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).
Cardholder Verification - confirma que una tarjeta pertenece a su titular declarado, sin ninguna captura de selfie (subject.code + card requerido). Opcionalmente reutiliza un proceso previamente validado mediante referenceProcessId para activar la validación de reutilización; sin él, la respuesta usa por defecto el resultado unsure. Consulte la capacidad Cardholder Verification.

El producto 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 producto activo y las capacidades habilitadas.
`Content-Type`	`application/json`

Parámetros del cuerpo

Registro
Transaccional
Cardholder Verification

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.
`subject.clientReference`	string	condicional	Identificador único del usuario en su sistema. Obligatorio para la capacidad Multi Cuentas. Único en su base, máximo de 256 caracteres, sin espacios.
`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 producto, no es posible orquestar con Score de Riesgo. El resultado siempre se devuelve sincrónicamente en la respuesta POST.

Campo	Tipo	Requerido	Descripción
`subject.duiType`	integer	sí	Identificador del tipo de documento. Consulte valores de `duiType` a continuación. Actualmente solo `DUI_TYPE_BR_CPF`.
`subject.code`	string	sí	CPF del titular de la tarjeta que se está verificando. Sin puntos ni guiones.
`card.bin`	string	condicional	Primeros 6 u 8 dígitos de la tarjeta (BIN). Requerido junto con `card.last4`.
`card.last4`	string	condicional	Últimos 4 dígitos de la tarjeta. Requerido junto con `card.bin`.
`card.name`	string	no	Nombre del titular de la tarjeta tal como aparece impreso en ella.
`referenceProcessId`	string (UUID)	no	ID de un proceso previamente validado para reutilizar — uno con un resultado aprobado de Verificación de Identidad o Detección de Vida para el mismo CPF. La versión actual de esta capacidad se basa en la reutilización: sin este campo, la validación nunca se activa y la respuesta usa por defecto el resultado estándar `unsure` — la solicitud en sí nunca falla.
`useCase`	string	no	Contexto de la operación, por ejemplo, `CardholderVerification`.
`subsidiaryId`	string	no	ID de sucursal — requerido solo si existen múltiples sucursales.

información

No se envía imageBase64 para este producto — Cardholder Verification se ejecuta completamente en el back-end, sin ningún paso de captura de selfie.

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

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

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

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"
    },
    "card": {
      "bin": "12345678",
      "last4": "4321",
      "name": "Luke Skywalker"
    },
    "referenceProcessId": "4f00b35f-69d4-415a-a843-d975cefcb169",
    "useCase": "CardholderVerification"
  }'

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'
    },
    card: {
      bin: '12345678',
      last4: '4321',
      name: 'Luke Skywalker'
    },
    referenceProcessId: '4f00b35f-69d4-415a-a843-d975cefcb169',
    useCase: 'CardholderVerification'
  })
});

const result = await res.json();

Respuestas

Registro
Transaccional
Cardholder Verification

200 OK

El contrato es único — el campo idCloud.result contiene el veredicto consolidado de las capacidades utilizadas.

Unico consolida los resultados de las capacidades ejecutadas en un único idCloud.result, listo para decidir el siguiente paso de su flujo — sin necesidad de orquestar resultados individuales.

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "idCloud": {
    "result": "approved"
  }
}

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

Valores de resultado posibles

idCloud.result	Meaning	Recommended action
approved	Real person and validated identity.	Proceed with the flow.
denied	Identity not validated, liveness check failed, or extreme risk identified.	End the flow or redirect to an alternative flow.
critical-risk	Critical risk level identified.	End the flow or route to manual review.
high-risk	High risk level identified.	Route to manual review or an alternative flow.
retry	Insufficient capture or score to evaluate.	Ask the user for a new capture.
inconclusive	Not enough evidence for a verdict.	Route to manual review or an alternative flow.

Los valores devueltos dependen de la receta configurada en su APIKey. Consulte Flujos para conocer los valores de resultado que puede devolver cada receta.

Los clientes en Brasil pueden recibir la respuesta por capacidad

La estructura general de la respuesta se mantiene igual — el resultado único es el valor predeterminado.

Las integraciones en Brasil pueden recibir los resultados abiertos por capacidad. Cada capacidad habilitada en la APIKey agrega su propio bloque a la respuesta — los campos de las capacidades deshabilitadas se omiten.

{
  "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
`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` — consulte Identificador Facial.
`idFace.personId`	string	Identificador opaco estable para el rostro, devuelto junto con `idFace.result = FOUND`. Cuando no se puede identificar ningún rostro en la imagen, la solicitud falla con el error `20532` en lugar de devolver un bloque `idFace`.
`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

El contrato es único — el campo idCloud.result contiene el veredicto consolidado de las capacidades utilizadas.

Unico consolida los resultados de las capacidades ejecutadas en un único idCloud.result, listo para decidir el siguiente paso de su flujo — sin necesidad de orquestar resultados individuales.

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "idCloud": {
    "result": "approved"
  }
}

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.

Valores de resultado posibles

idCloud.result	Meaning	Recommended action
approved	Real person and validated identity.	Proceed with the flow.
denied	Identity not validated, liveness check failed, or extreme risk identified.	End the flow or redirect to an alternative flow.
critical-risk	Critical risk level identified.	End the flow or route to manual review.
high-risk	High risk level identified.	Route to manual review or an alternative flow.
retry	Insufficient capture or score to evaluate.	Ask the user for a new capture.
inconclusive	Not enough evidence for a verdict.	Route to manual review or an alternative flow.

Los valores devueltos dependen de la receta configurada en su APIKey. Consulte Flujos para conocer los valores de resultado que puede devolver cada receta.

Los clientes en Brasil pueden recibir la respuesta por capacidad

La estructura general de la respuesta se mantiene igual — el resultado único es el valor predeterminado.

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

Campo	Tipo	Descripción
`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.

200 OK

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "cardholderVerification": {
    "result": "approved"
  }
}

Campo	Tipo	Descripción
`id`	string (UUID)	Identificador del proceso.
`status`	integer	`1` (procesando), `3` (finalizado con éxito), `5` (error). Para todos los valores, consulte Obtener proceso.
`cardholderVerification.result`	string	`approved` — el CPF y la tarjeta pertenecen a la misma persona. `unsure` — ya sea que la condición de reutilización no se haya cumplido, o que la propia verificación haya sido inconclusa. Ausente mientras `status` aún no sea `3`. Consulte Cardholder Verification.

Códigos de error

400 Bad Request
403 Forbidden
409 Conflict
429 Too Many Requests
500 Internal Server Error

Código	Mensaje	Descripción
`40221`	This flow does not support reusing a prior process (referenceProcessId or bioTokenId) without an image; send an image (imageBase64, or references[0] with type IMAGE_BASE64) instead.	El flujo de reutilización (`referenceProcessId`/`bioTokenId`, sin imagen) fue rechazado porque la reutilización de procesos no está habilitada para esta API key.
`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.
`20532`	No face detected in image.	No se pudo detectar ningún rostro en la imagen enviada.
`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. No aplica a Cardholder Verification — su `referenceProcessId` nunca se valida como obligatorio; una condición de reutilización no satisfecha responde `unsure` en su lugar.
`20533`	The card field is missing.	Cardholder Verification: no se proporcionó el objeto `card`.
`20534`	The card.bin field is missing.	Cardholder Verification: no se proporcionó `card.bin`.
`20535`	The card.last4 field is missing.	Cardholder Verification: no se proporcionó `card.last4`.
`20536`	The card data is invalid.	Cardholder Verification: los datos de la tarjeta fueron rechazados como inválidos.
`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.

Token Bearer o APIKEY ausente, expirado o inválido. Consulte 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 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 ver todas las combinaciones de recetas y sus valores de resultado posibles, consulte Flujos.
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​

Endpoint

Solicitud

Ejemplo

Respuestas

Códigos de error

Qué sigue