Crear proceso

MarkdownChatGPTClaude

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

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.

Transaccional

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_AR_DNI, DUI_TYPE_BR_CPF, DUI_TYPE_ID_NIK, DUI_TYPE_MX_CURP, DUI_TYPE_NG_NIN, DUI_TYPE_US_SSN.
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.

Cardholder Verification

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

Solicitudes comprimidas

La API admite el envío del cuerpo de la solicitud comprimido, utilizando el encabezado HTTP estándar Content-Encoding. Esto es opcional y totalmente retrocompatible: los clientes que no envíen este encabezado siguen funcionando exactamente igual que antes.

Formatos admitidos

Codificación	Encabezado Content-Encoding	Estado
Gzip	gzip	✅ Recomendado
Deflate	deflate	✅ Admitido
Sin compresión	(encabezado ausente)	✅ Admitido (comportamiento predeterminado)

Recomendación

Use gzip. Tiene el soporte más universal entre lenguajes y bibliotecas HTTP, evitando las ambigüedades de implementación presentes en otros formatos.

Se recomienda la compresión para solicitudes con un cuerpo grande (por ejemplo, payloads JSON extensos, cargas de imágenes codificadas en base64, envíos por lotes). Para solicitudes pequeñas, el overhead de comprimir puede no aportar un beneficio relevante.

Cómo enviar una solicitud comprimida

1. Comprima el cuerpo de la solicitud (por ejemplo, el JSON serializado) utilizando el algoritmo elegido.
2. Envíe el cuerpo comprimido como bytes binarios en la solicitud.
3. Incluya el encabezado Content-Encoding con el valor correspondiente (gzip o deflate).
4. Mantenga Content-Type describiendo el formato de contenido original (por ejemplo, application/json), no la codificación de transporte.

cURL

echo '{"subject":{"code":"12345678909"},"useCase":"Onboarding","imageBase64":"/9j/4AAQSkZJR..."}' | gzip > body.json.gz

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Content-Encoding: gzip" \
  --data-binary @body.json.gz

Python (requests)

import gzip
import json
import requests

payload = {
    "subject": {"code": "12345678909"},
    "useCase": "Onboarding",
    "imageBase64": capturedImage,
}
compressed_body = gzip.compress(json.dumps(payload).encode("utf-8"))

response = requests.post(
    "https://api.id.unico.app/processes/v1",
    data=compressed_body,
    headers={
        "Authorization": f"Bearer {token}",
        "APIKEY": api_key,
        "Content-Type": "application/json",
        "Content-Encoding": "gzip",
    },
)

.NET (C#, HttpClient)

using System.IO.Compression;
using System.Text;
using System.Text.Json;

var json = JsonSerializer.Serialize(payload);
var jsonBytes = Encoding.UTF8.GetBytes(json);

using var outputStream = new MemoryStream();
using (var gzipStream = new GZipStream(outputStream, CompressionMode.Compress, leaveOpen: true))
{
    await gzipStream.WriteAsync(jsonBytes, 0, jsonBytes.Length);
}
outputStream.Position = 0;

var content = new ByteArrayContent(outputStream.ToArray());
content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
content.Headers.ContentEncoding.Add("gzip");

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", $"Bearer {token}");
client.DefaultRequestHeaders.Add("APIKEY", apiKey);

var response = await client.PostAsync("https://api.id.unico.app/processes/v1", content);

consejo

Para el ejemplo en Python, use el parámetro data=, no json=. El parámetro json= serializa el payload automáticamente, pero no lo comprime.

Usando deflate en su lugar: el flujo anterior es idéntico — solo cambian la llamada de compresión y el valor de Content-Encoding.

Idioma	deflate
Bash / cURL	zlib-flate -compress < body.json > body.json.deflate (de qpdf), luego -H "Content-Encoding: deflate"
Python	zlib.compress(data) en lugar de gzip.compress(data)
.NET (C#)	System.IO.Compression.DeflateStream en lugar de GZipStream

deflate es ambiguo en la práctica

La codificación de contenido deflate de HTTP se especifica como un stream zlib (RFC 1950), pero algunos clientes y servidores históricamente emiten o esperan DEFLATE sin procesar (RFC 1951) en su lugar. Esta API espera el stream estándar envuelto en zlib — la misma salida que producen por defecto zlib.compress() (Python) o DeflateStream (.NET). Ante la duda, prefiere gzip, que no tiene esa ambigüedad.

Comportamiento en caso de error

Si se envía Content-Encoding con un valor no admitido, o el cuerpo está corrupto o no es válido para la codificación declarada, la API devuelve 400 Bad Request con un mensaje que indica que no se pudo descomprimir el cuerpo de la solicitud.

Preguntas frecuentes

¿Necesito cambiar algo si no quiero usar compresión? No. El soporte para Content-Encoding es aditivo — las solicitudes sin este encabezado continúan procesándose normalmente.

¿Esto afecta la respuesta de la API? No. Esta funcionalidad solo concierne al cuerpo enviado por el cliente (solicitud). La compresión de la respuesta (lo que la API devuelve) se controla por separado mediante el encabezado Accept-Encoding.

¿Qué formato debería elegir? Use gzip, a menos que alguna restricción específica de su entorno requiera otro formato.

Ejemplo

Registro - cURL

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..."
  }'

Registro - Node.js

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

Transaccional - cURL

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..."
  }'

Transaccional - Node.js

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

Cardholder Verification - cURL

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"
  }'

Cardholder Verification - Node.js

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

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	Significado	Acción recomendada
approved	Persona real e identidad validada.	Continuar con el flujo.
denied	Identidad no validada, falló la verificación de vida o se identificó un riesgo extremo.	Finalizar el flujo o redirigir a un flujo alternativo.
critical-risk	Se identificó un nivel de riesgo crítico.	Finalizar el flujo o enviar a revisión manual.
high-risk	Se identificó un nivel de riesgo alto.	Enviar a revisión manual o a un flujo alternativo.
retry	Captura o score insuficiente para evaluar.	Solicitar al usuario una nueva captura.
inconclusive	Evidencia insuficiente para un veredicto.	Enviar a revisión manual o a un flujo alternativo.

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.

Los clientes en México pueden recibir el bloque de Verificación RENAPO

La respuesta mantiene la misma estructura y agrega el bloque idGov.

Las integraciones en México con Verificación RENAPO habilitada reciben un bloque adicional idGov con el registro que RENAPO tiene para la CURP del usuario. Es una respuesta independiente del resultado de identidad.

{
  "id": "11111111-2222-3333-4444-555555555555",
  "status": 3,
  "idCloud": { "result": "approved" },
  "idGov": {
    "government_valid": true,
    "curp": "PUEA880304MDFRJN04",
    "government_name": "ANA PRUEBA EJEMPLO",
    "date_of_birth": "1988-03-04",
    "age": 38,
    "gender": "F",
    "deceased": false,
    "is_mexican": true,
    "citizenship": "MEXICO",
    "state_of_birth": "Ciudad de México",
    "state_iso": "MX-CMX",
    "issuing_entity_code": "DF",
    "municipality_registration": ""
  }
}

Campo	Tipo	Descripción
idGov	object	Registro de RENAPO para la CURP. Ausente cuando la capacidad no está habilitada. {} cuando RENAPO no respondió. Solo México. Consulte Verificación RENAPO.

Transaccional

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	Significado	Acción recomendada
approved	Persona real e identidad validada.	Continuar con el flujo.
denied	Identidad no validada, falló la verificación de vida o se identificó un riesgo extremo.	Finalizar el flujo o redirigir a un flujo alternativo.
critical-risk	Se identificó un nivel de riesgo crítico.	Finalizar el flujo o enviar a revisión manual.
high-risk	Se identificó un nivel de riesgo alto.	Enviar a revisión manual o a un flujo alternativo.
retry	Captura o score insuficiente para evaluar.	Solicitar al usuario una nueva captura.
inconclusive	Evidencia insuficiente para un veredicto.	Enviar a revisión manual o a un flujo alternativo.

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

Cardholder Verification

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

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.

403 Forbidden

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.

409 Conflict

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

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.

500 Internal Server Error

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.