Crear Proceso

MarkdownChatGPTClaude

Este es el punto de entrada de toda integración con la Unico API. Tu backend la llama para crear un proceso; tu frontend usa los tokens devueltos para renderizar el iFrame, redirigir al usuario o inicializar un SDK nativo.

Para conocer el flujo completo de integración, ver Flujos.

Endpoint

Entorno	URL
Producción	POST https://api.idcloud.unico.app/client/v1/process
Sandbox	POST https://api.idcloud.uat.unico.app/client/v1/process

Solicitud

Headers

Header	Valor
Authorization	Bearer <access_token> (ver Autenticación)
Content-Type	application/json

Parámetros del cuerpo

Los requisitos de los campos dependen del flow

Que un campo sea obligatorio, opcional o no aplicable depende del flow que estés integrando — consulta Flujos para la receta específica que estás usando antes de asumir el requisito de un campo solo a partir de esta tabla.

Campo	Tipo	Descripción
callbackUri	string	URL a la que se redirige al usuario después de finalizar el recorrido. Usa / para flows de SDK nativo donde el callback se maneja dentro de la app.
flow	string	Identificador del flow — determina qué capacidades se ejecutan. Ejemplos: idunicodocs, idunicosign, idchecktrust, idtoken, idsmart. Ver Flujos disponibles.
purpose	string	Propósito de negocio. Valores aceptados: creditprocess, biometryonboarding, carpurchase, ageverification.
person.duiType	enum	Tipo de documento. Ver valores de duiType más abajo.
person.duiValue	string	Número del documento, sin formato.
person.friendlyName	string	Nombre visible del usuario mostrado en la UI del recorrido. Máximo 50 caracteres.
person.phone	string	Número de teléfono en formato DDI + DDD + número, sin separadores. Obligatorio al enviar notificaciones por SMS o WhatsApp.
person.email	string	Dirección de correo electrónico. Obligatorio para flows con Firma Electrónica.
person.​notifications	array	Canales de notificación para enviar el enlace del recorrido. Cada elemento tiene notificationChannel: NOTIFICATION_CHANNEL_WHATSAPP, NOTIFICATION_CHANNEL_SMS o NOTIFICATION_CHANNEL_EMAIL.
references	array	Entradas de referencia para flows de Validación 1:1 y Revalidación Inteligente. Cada elemento contiene referenceType (REFERENCE_TYPE_IMAGE_BASE64 o REFERENCE_TYPE_PROCESS_ID) y referenceContent (imagen codificada en base64 o UUID del proceso). Envía como máximo un elemento — un arreglo más largo se rechaza con 400, y referenceContent no debe estar vacío.
useCase	string	Escenario de Revalidación Inteligente. Obligatorio para 🇧🇷 idsmart, idsmart_r2, idsmart_tp1. Ejemplos: USE_CASE_LOGIN, USE_CASE_FIN_TRANSACTIONS.
clientReference	string	Identificador único del usuario en tu sistema. Obligatorio para la capacidad Multi Cuentas. Único en tu base, máximo 256 caracteres, sin espacios.
companyBranchId	string (UUID)	ID de la sucursal. Obligatorio solo si la cuenta de servicio tiene más de una sucursal asociada.
expiresIn	string	Ventana de validez del proceso desde su creación. Formato: "3600s". Por defecto, 7 días si se omite.
flowConfig	object	Anulaciones de configuración por flow.
flowConfig.​biometryCapture.​enabledBackCamera	boolean	Usa la cámara trasera del dispositivo. No es compatible con flows de captura de documento o Firma Electrónica.
contextualization	object	Contexto de la transacción mostrado al usuario durante el recorrido para explicar la captura. Disponible para clientes de cualquier región — no está limitado a un país específico.
contextualization.​company_name	string	Nombre de la empresa mostrado durante el recorrido. Máximo 20 caracteres.
contextualization.​currency	string	Código de moneda mostrado al usuario. Valores aceptados: BRL, MXN, USD.
contextualization.​price	number	Monto de la transacción mostrado al usuario.
contextualization.​locale	object	Texto localizado mostrado durante el recorrido. Claves: ptBr, enUs, esMx — estos son los únicos idiomas admitidos para el texto, independientemente de la región del cliente.
contextualization.locale.{ptBr|enUs|esMx}.reason	string	Motivo breve de la captura, mostrado durante el recorrido. Máximo 50 caracteres.
contextualization.locale.{ptBr|enUs|esMx}.title	string	Título del aviso al cliente mostrado durante el recorrido. Máximo 100 caracteres. Debe proporcionarse junto con text. Las etiquetas HTML se eliminan.
contextualization.locale.{ptBr|enUs|esMx}.text	string	Cuerpo del aviso al cliente mostrado durante el recorrido. Máximo 210 caracteres. Debe proporcionarse junto con title. Las etiquetas HTML se eliminan.
imageBase64	string	La selfie, enviada directamente. Acepta el JWT de captura del SDK.
document.purpose	enum	Para qué se usa el documento. Vocabulario fijo: DOCUMENT_PURPOSE_ONBOARDING, DOCUMENT_PURPOSE_CREDIT_PROCESS, DOCUMENT_PURPOSE_CAR_PURCHASE, DOCUMENT_PURPOSE_PAY_BY_PAYCHECK, DOCUMENT_PURPOSE_FGTS. Solo se usa con flows de Face Document Match.
document.​files[].​data	bytes	Nueva captura de documento, codificada en base64. Disponible a nivel global, no limitado a Brasil. Mutuamente excluyente con document.documentId.
document.documentId	string (UUID)	Reutiliza un documento ya capturado por la misma persona, en lugar de una nueva captura. Mutuamente excluyente con document.files[].
expectedResult	object	Simula el resultado de una capacidad en entornos de prueba/sandbox y marca la respuesta con simulated: true. Ver Simulando resultados (Test Mock).

Valores de duiType

País	Valor	Descripción
AR	DUI_TYPE_AR_PASSPORT	Pasaporte argentino
AR	DUI_TYPE_AR_DNI	DNI argentino
AR	DUI_TYPE_AR_LNC	Licencia de conducir argentina (Licencia Nacional de Conducir)
AT	DUI_TYPE_AT_STNR	Número de impuesto austríaco (STNR)
BE	DUI_TYPE_BE_NN	Número Nacional belga (NN)
BR	DUI_TYPE_BR_CPF	CPF brasileño
BR	DUI_TYPE_BR_PASSPORT	Pasaporte brasileño
BR	DUI_TYPE_BR_CNPJ	CNPJ brasileño
CA	DUI_TYPE_CA_SIN	SIN canadiense
CH	DUI_TYPE_CH_AHV	Número AHV/AVS suizo
CL	DUI_TYPE_CL_RUN	RUN chileno
CL	DUI_TYPE_CL_PASSPORT	Pasaporte chileno
CL	DUI_TYPE_CL_LICENCIA_CONDUCIR	Licencia de conducir chilena (Licencia de Conducir)
CO	DUI_TYPE_CO_NIT	NIT colombiano
CO	DUI_TYPE_CO_PASSPORT	Pasaporte colombiano
CO	DUI_TYPE_CO_LICENCIA_CONDUCCION	Licencia de conducir colombiana (Licencia de Conducción)
CO	DUI_TYPE_CO_CC	Cédula de Ciudadanía colombiana (Cédula de Ciudadanía)
DE	DUI_TYPE_DE_IDNR	Número de Identificación Fiscal alemán (IdNr)
DK	DUI_TYPE_DK_CPR	CPR danés
EC	DUI_TYPE_EC_NI	NI ecuatoriano
ES	DUI_TYPE_ES_NIE	Número de Identidad de Extranjero español (NIE)
ES	DUI_TYPE_ES_DNI	Documento Nacional de Identidad español (DNI)
FI	DUI_TYPE_FI_HETU	Código de identidad personal finlandés (HETU)
FR	DUI_TYPE_FR_SPI	Número de Referencia Fiscal francés (SPI)
GB	DUI_TYPE_GB_NINO	Número de Seguro Nacional británico (NINO)
GT	DUI_TYPE_GT_CUI	CUI guatemalteco
ID	DUI_TYPE_ID_NIK	NIK indonesio
IE	DUI_TYPE_IE_PPSN	Número de Seguro Social Personal irlandés (PPSN)
IT	DUI_TYPE_IT_CF	Código Fiscal italiano (CF)
LK	DUI_TYPE_LK_NIC	NIC de Sri Lanka
LU	DUI_TYPE_LU_MATRICULE	Número de Identificación Nacional de Luxemburgo (Matricule)
MX	DUI_TYPE_MX_CURP	CURP mexicano
MX	DUI_TYPE_MX_RFC_PERSONA_FISICA	RFC mexicano (Persona Física)
MX	DUI_TYPE_MX_LICENCIA_CONDUCIR	Licencia de conducir mexicana (Licencia de Conducir)
NG	DUI_TYPE_NG_NIN	NIN nigeriano
NG	DUI_TYPE_NG_BVN	Número de Verificación Bancaria nigeriano (BVN)
NG	DUI_TYPE_NG_BVN_TOKEN	Token BVN nigeriano (hash)
NG	DUI_TYPE_NG_NIN_TOKEN	Token NIN nigeriano (hash)
NL	DUI_TYPE_NL_BSN	Número de Servicio al Ciudadano holandés (BSN)
NO	DUI_TYPE_NO_FNR	Número de Identidad Nacional noruego (Fødselsnummer)
PE	DUI_TYPE_PE_RUC	RUC peruano
PE	DUI_TYPE_PE_DNI	DNI peruano
PE	DUI_TYPE_PE_PASSPORT	Pasaporte peruano
PL	DUI_TYPE_PL_PESEL	PESEL polaco
PT	DUI_TYPE_PT_NIF	Número de Identificación Fiscal portugués (NIF)
SE	DUI_TYPE_SE_PNR	Número personal sueco (PNR)
SE	DUI_TYPE_SE_SAMORDNINGSNUMMER	Número de Coordinación sueco (Samordningsnummer)
TR	DUI_TYPE_TR_TCKN	Número de Identificación turco (TCKN)
US	DUI_TYPE_US_SSN	SSN de Estados Unidos
US	DUI_TYPE_US_PASSPORT	Pasaporte de Estados Unidos
US	DUI_TYPE_US_DRIVER_LICENSE	Licencia de conducir de Estados Unidos
US	DUI_TYPE_US_PASSPORT_CARD	Tarjeta de pasaporte de Estados Unidos
US	DUI_TYPE_US_POLYCARBONATE_PASSPORT	Pasaporte de policarbonato de Estados Unidos
US	DUI_TYPE_US_ID_CARD	Tarjeta de identificación de Estados Unidos
UY	DUI_TYPE_UY_CI	CI uruguayo
ZZ	DUI_TYPE_ZZ_EMAIL	Dirección de correo electrónico
ZZ	DUI_TYPE_ZZ_PHONE_NUMBER	Número de teléfono

Crear un proceso sin documento

Cuando el flow permite un documento opcional, puedes omitir person.duiType y person.duiValue. Después de la captura, el proceso espera en AWAITING_FOR_DOCUMENT hasta que tu back-end envíe el documento con Definir Documento del Proceso.

Ejemplo

cURL

curl -X POST https://api.idcloud.unico.app/client/v1/process \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "flow": "idunicodocs_r2",
    "purpose": "biometryonboarding",
    "clientReference": "pedido-88216",
    "callbackUri": "https://your-app.example.com/onboarding/callback",
    "person": {
      "duiType": "DUI_TYPE_BR_CPF",
      "duiValue": "12345678909"
    }
  }'

Node.js

import fetch from 'node-fetch';

const res = await fetch('https://api.idcloud.unico.app/client/v1/process', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    flow: 'idunicodocs_r2',
    purpose: 'biometryonboarding',
    clientReference: 'pedido-88216',
    callbackUri: 'https://your-app.example.com/onboarding/callback',
    person: {
      duiType: 'DUI_TYPE_BR_CPF',
      duiValue: '12345678909',
    },
  }),
});

const { process: proc } = await res.json();
// proc.userRedirectUrl, proc.token, proc.webAppToken

Respuestas

200 OK

{
  "process": {
    "id": "b7c1f0a2-63d4-4f3e-9a17-2c8e5d41b0aa",
    "flow": "idunicodocs_r2",
    "state": "PROCESS_STATE_CREATED",
    "result": "PROCESS_RESULT_UNSPECIFIED",
    "purpose": "biometryonboarding",
    "clientReference": "pedido-88216",
    "person": {
      "duiType": "DUI_TYPE_BR_CPF",
      "duiValue": "12345678909"
    },
    "capacities": [
      "PROCESS_CAPACITY_IDLIVE",
      "PROCESS_CAPACITY_IDUNICO",
      "PROCESS_CAPACITY_IDDOCS"
    ],
    "authenticationInfo": {
      "authenticationId": ""
    },
    "companyData": {
      "branchId": "",
      "countryCode": "BRA"
    },
    "callbackUri": "https://your-app.example.com/onboarding/callback",
    "userRedirectUrl": "https://cadastro.unico.app/flow?id=b7c1f0a2-63d4-4f3e-9a17-2c8e5d41b0aa",
    "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…",
    "webAppToken": "eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiZGlyIn0…",
    "simulated": false
  }
}

Campo	Tipo	Descripción
process.id	string (UUID)	Identificador del proceso. Úsalo para obtener el resultado mediante Obtener Proceso.
process.state	enum	PROCESS_STATE_CREATED — proceso creado, recorrido aún no iniciado. PROCESS_STATE_FAILED — falló la creación del proceso.
process.result	enum	Resultado de la verificación. Presente solo cuando state = PROCESS_STATE_FINISHED — ver Flujos para los valores de resultado que puede devolver un flow determinado.
process.flow	string	Identificador del flow enviado en la creación.
process.purpose	string	Propósito de negocio enviado en la creación.
process.callbackUri	string	URI de callback enviada en la creación.
process.​clientReference	string	Tu identificador interno enviado en la creación. Presente solo si se proporcionó en la solicitud.
process.​companyBranchId	string (UUID)	ID de la sucursal. Presente solo si se proporcionó en la solicitud.
process.​userRedirectUrl	string	URL a la que redirigir al usuario (integraciones de Web Redirect e iFrame). No modifiques esta URL.
process.token	string	JWT para inicializar el iFrame del Web SDK.
process.webAppToken	string	JWT para inicializar SDKs nativos (Android, iOS, Flutter).
process.createdAt	string (date-time)	Marca de tiempo de creación del proceso.
process.expiresAt	string (date-time)	Marca de tiempo a partir de la cual el proceso expira y ya no puede completarse.
process.capacities	array	Capacidades configuradas para este proceso.
process.​authenticationInfo	object	Información de autenticación del proceso (vacía en el momento de la creación).
process.person	object	Eco del objeto person enviado en la creación.
process.​companyData.​branchId	string (UUID)	ID de la sucursal asociada al proceso.
process.​companyData.​countryCode	string	Código de país asociado a la sucursal (ej.: BR, MX).

Códigos de Error

400 Bad Request

Código	Mensaje	Descripción
3	invalid flow	Cuando el flow especificado no existe.
3	invalid person: friendly name exceeds 50 characters.	Cuando el nombre visible excede los 50 caracteres.
3	invalid purpose	Cuando el purpose proporcionado no es válido.
3	invalid callbackUri: unable to parse callbackUri: parse "": empty url, invalid callbackUri: url:	Cuando el callbackUri proporcionado no es válido.
3	invalid person: email required for notification channel NOTIFICATION_CHANNEL_EMAIL, invalid email address for notification channel NOTIFICATION_CHANNEL_EMAIL	Cuando el correo proporcionado no es válido y la notificación por correo está configurada.
3	invalid person: phone number required for notification channel NOTIFICATION_CHANNEL_WHATSAPP, phone number does not contain 13 chars for notification channel NOTIFICATION_CHANNEL_WHATSAPP	Cuando el número de teléfono proporcionado no es válido y la notificación por SMS o WhatsApp está configurada.
3	idnsv2/GetPublicID request error: rpc error: code = InvalidArgument desc = invalid dui value	Cuando el identificador proporcionado (duiValue) no es válido.
3	invalid expiresIn argument	Cuando el valor de expiresIn no es válido.
3	invalid company_name argument in process contextualization, max length is 20	Cuando contextualization.​company_name excede los 20 caracteres.
3	title and text must be provided together in process contexts	Cuando solo se proporciona uno de title o text en un locale.
3	invalid title argument in process contexts, max length is 100	Cuando el title de un locale excede los 100 caracteres.
3	invalid text argument in process contexts, max length is 210	Cuando el text de un locale excede los 210 caracteres.
3	invalid reason argument in process contexts, max length is 50	Cuando el reason de un locale excede los 50 caracteres.
3	The references array must contain at most one element.	Cuando se envía más de un elemento en references.
3	The references[].referenceContent field is missing.	Cuando referenceContent está vacío.
3	The references[].referenceType field must be IMAGE_BASE64 or PROCESS_ID.	Cuando referenceType no es uno de los valores admitidos.
3	A reference is required for this flow.	Cuando el flow requiere una referencia y no se envió ninguna. Envía references[0] con referenceType PROCESS_ID o IMAGE_BASE64.
9	The referenceProcessId field is invalid.	Cuando el proceso de referencia no existe o no se puede reutilizar. Nombra el campo que enviaste — bioTokenId si enviaste ese.
3	INVALID_IMAGE	Cuando la imagen no es un base64 válido, o parece un intento de inyección.
3	INVALID_DUI	Cuando el número de documento no es estándar o no existe.
3	IMAGE_TOO_LARGE	Cuando la imagen excede el tamaño máximo de 800 KB.
3	UNSUPPORTED_IMAGE_FORMAT	Cuando el formato de la imagen no es PNG, JPEG o WebP.
3	MISSING_IMAGE	Cuando la imagen es obligatoria para este flow y no se envió.
3	MISSING_NAME	Cuando el nombre es obligatorio para este flow y no se envió.
3	MISSING_DUI	Cuando el número de documento es obligatorio para este flow y no se envió.
3	MISSING_PERSON	Cuando el objeto person es obligatorio para este flow y no se envió.
3	INVALID_REQUEST	Cuando el cuerpo de la solicitud es nulo o no se puede interpretar.
3	TOKEN_ALREADY_USED	Cuando el token de captura ya fue utilizado. Es de un solo uso.
3	TOKEN_EXPIRED	Cuando el token de captura ha expirado. Debe usarse dentro de los 10 minutos.
3	INVALID_BUNDLE	Cuando la solicitud no cumple con los requisitos de seguridad.
3	INVALID_NAME	Cuando el nombre es más largo que el máximo permitido.
3	INVALID_EMAIL	Cuando la dirección de correo está malformada o es demasiado larga.
3	INVALID_PHONE	Cuando el número de teléfono es más largo de 20 caracteres.
3	INVALID_DUI_TYPE	Cuando el tipo de documento no es uno de los valores admitidos.
3	INVALID_CLIENT_REFERENCE	Cuando clientReference es demasiado largo, o contiene un espacio o #.
3	INVALID_CONSENT_TYPE	Cuando consentType no es NONE, DIRECT o INDIRECT.
3	INVALID_USE_CASE	Cuando useCase no se reconoce, o es demasiado largo.
3	INVALID_DEVICE_TRUST_TOKEN	Cuando el token de confianza del dispositivo no es válido o ya fue consumido.
3	TOO_MANY_REFERENCES	Cuando se envía más de un elemento en references.
3	INVALID_REFERENCE_TYPE	Cuando referenceType no es IMAGE_BASE64 o PROCESS_ID.
3	INVALID_REFERENCE_PROCESS	Cuando el ID del proceso de referencia no es un identificador válido.
3	REFERENCE_PROCESS_NOT_FOUND	Cuando el proceso referenciado no existe.
3	REFERENCE_PROCESS_NOT_READY	Cuando el proceso referenciado no tiene un resultado reutilizable, o ya fue consumido.
3	REFERENCE_SELFIE_NOT_FOUND	Cuando el proceso referenciado no contiene ninguna selfie para reutilizar.
3	INVALID_CAPTURE_TOKEN	Cuando la imagen capturada no es un token válido producido por un SDK de captura.
3	INVALID_CAPTURE_SIGNATURE	Cuando la firma del token de captura no se valida.
3	PRIOR_CAPTURE_NOT_FOUND	Cuando no se pudo localizar la captura previa en la que se basa esta solicitud. Reinicia el proceso.
3	PRIOR_CAPTURE_IN_PROGRESS	Cuando la captura previa aún no ha finalizado. Vuelve a intentarlo en breve.
3	PRIOR_CAPTURE_FAILED	Cuando la captura previa no se pudo completar. Reinicia el proceso.
3	INVALID_DOCUMENT	Cuando un archivo de documento no se puede leer, está protegido con contraseña o tiene un formato no admitido.
3	INVALID_AUTH_PROCESS	Cuando document.authProcessId no es válido, ha expirado o pertenece a otra persona.
3	INVALID_DOCUMENT_PURPOSE	Cuando document.purpose no es uno de los valores admitidos.
3	PROCESS_REUSE_NOT_ENABLED	Cuando el flow no permite reutilizar un proceso anterior sin una imagen. Envía una imagen en su lugar.
9	PROCESS_FAILED	Cuando el proceso alcanzó una falla terminal durante su creación.
9	Tenant API key is not configured	Cuando la API Key no está configurada correctamente.

401 Unauthorized

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

Mensaje	Descripción
Jwt header is an invalid JSON	Cuando el access token utilizado contiene caracteres incorrectos.
Jwt is expired	Cuando el access token utilizado ha expirado.

403 Forbidden

Código	Mensaje	Descripción
7	INVALID_API_KEY	Cuando la API key no es válida o falta.
7	INVALID_AUTH_TOKEN	Cuando el token de autenticación no es válido.
7	PERMISSION_DENIED	Cuando las credenciales son válidas pero no tienen permiso para esta acción.
7	TOKEN_TENANT_MISMATCH	Cuando el token de captura fue emitido para otro tenant.
7	MISSING_ACCESS_TOKEN	Cuando falta el header de autorización.

404 Not Found

Código	Mensaje	Descripción
5	NO_RESULTS_FOUND	Cuando no se pudo encontrar un documento referenciado por la solicitud.

429 Too Many Requests

Se alcanzó el límite de tasa. 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 enfriamiento (backoff): Detenga o reduzca inmediatamente las solicitudes posteriores de su sistema. No reintente continuamente las solicitudes fallidas en un bucle cerrado.
• Cola y limitación (Queueing & throttling): Almacene en búfer o ponga en cola 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 evitar un efecto de manada donde todas las solicitudes en cola reintentan en el mismo milisegundo exacto.

advertencia

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

Para conocer los límites predeterminados, aumentar solicitudes y obtener detalles adicionales, consulte Límites de tasa.

500 Internal Server Error

Código	Mensaje	Descripción
13	Internal failure! Try again later	Cuando ocurre un error interno.

Qué sigue

• Después de que el usuario finalice el recorrido, llama a Obtener Proceso para obtener el resultado, o espera el webhook.
• Para ver todas las combinaciones de recetas y sus posibles valores de resultado, ver Flujos.
• Para probar un resultado sin una captura biométrica real, ver Simulando resultados (Test Mock).