Crear proceso

Este es el punto de entrada de toda integración Web & SDK. Su back-end lo llama para crear un proceso; su front-end usa los tokens devueltos para renderizar el iFrame, redirigir al usuario o inicializar un SDK nativo.

Para el flujo de integración completo, consulte Descripción general de Web & SDK.

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

Encabezados

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

Parámetros del cuerpo

Campo	Tipo	Requerido	Descripción
callbackUri	string	sí	URL a la que se redirige al usuario después de que termina el recorrido. Use / para flujos de SDK nativo donde el callback se maneja dentro de la aplicación.
flow	string	sí	Identificador del flujo: determina qué capacidades se ejecutan. Ejemplos: idunicodocs, idunicosign, idchecktrust, idtoken, idsmart. Consulte Flujos disponibles.
purpose	string	sí	Propósito de negocio. Valores aceptados: creditprocess, biometryonboarding, carpurchase, ageverification.
person.duiType	enum	sí	Tipo de documento. Valores aceptados: DUI_TYPE_BR_CPF, DUI_TYPE_MX_CURP, DUI_TYPE_US_SSN, DUI_TYPE_BR_PASSPORT, DUI_TYPE_AR_PASSPORT, DUI_TYPE_AR_DNI, DUI_TYPE_NG_NIN, DUI_TYPE_CL_RUN, DUI_TYPE_EC_NI, DUI_TYPE_US_PASSPORT, DUI_TYPE_GT_CUI, DUI_TYPE_UY_CI, DUI_TYPE_ZZ_EMAIL, DUI_TYPE_ID_NIK, DUI_TYPE_ZZ_PHONE_NUMBER, DUI_TYPE_US_DRIVER_LICENSE, DUI_TYPE_NG_BVN, DUI_TYPE_MX_RFC_PERSONA_FISICA, DUI_TYPE_CO_NIT, DUI_TYPE_PE_RUC, DUI_TYPE_CA_SIN, DUI_TYPE_DK_CPR, DUI_TYPE_GB_NINO, DUI_TYPE_PL_PESEL, DUI_TYPE_SE_PNR, DUI_TYPE_AT_STNR, DUI_TYPE_FI_HETU.
person.duiValue	string	sí	Número de documento, sin formato.
person.friendlyName	string	no	Nombre para mostrar del usuario en la interfaz del recorrido. Máximo 50 caracteres.
person.phone	string	no	Número de teléfono en formato DDI + DDD + número, sin separadores. Requerido al enviar notificaciones por SMS o WhatsApp.
person.email	string	no	Dirección de correo electrónico. Requerido para flujos con Firma Electrónica.
person.notifications	array	no	Canales de notificación para enviar el enlace del recorrido. Cada elemento tiene notificationChannel: NOTIFICATION_CHANNEL_WHATSAPP, NOTIFICATION_CHANNEL_SMS o NOTIFICATION_CHANNEL_EMAIL.
bioTokenId	string (UUID)	condicional	Obsoleto. Use references en su lugar. ID del proceso biométrico de referencia. Requerido para flujos de Validación 1:1 (idtoken, idtokentrust, idtokensign) y Revalidación Inteligente (idsmart).
references	array	condicional	Entradas de referencia para flujos de Validación 1:1 y Revalidación Inteligente, reemplazando bioTokenId. Cada elemento contiene referenceType (REFERENCE_TYPE_IMAGE_BASE64 o REFERENCE_TYPE_PROCESS_ID) y referenceContent (imagen codificada en base64 o UUID del proceso).
useCase	string	condicional	Caso de uso de Revalidación Inteligente. Requerido para idsmart. Ejemplos: USE_CASE_LOGIN, USE_CASE_IDENTITY_REVALIDATION_7_DAYS, USE_CASE_FIN_TRANSACTIONS.
clientReference	string	no	Su identificador interno para este proceso (clave foránea para referencia cruzada en el portal).
companyBranchId	string (UUID)	no	ID de sucursal. Requerido solo si la cuenta de servicio tiene más de una sucursal asociada.
expiresIn	string	no	Ventana de validez del proceso desde la creación. Formato: "3600s". Por defecto 7 días si se omite.
flow_config	object	no	Anulaciones de configuración por flujo.
flow_config.biometry_capture.enabled_back_camera	boolean	no	Usar la cámara trasera del dispositivo. No compatible con flujos de captura de documento o Firma Electrónica.
contextualization	object	no	Contexto de transacción mostrado al usuario durante el recorrido para explicar la captura.
contextualization.company_name	string	no	Nombre de la empresa mostrado durante el recorrido. Máximo 20 caracteres.
contextualization.currency	string	no	Código de moneda mostrado al usuario. Valores aceptados: BRL, MXN, USD.
contextualization.price	number	no	Monto de la transacción mostrado al usuario.
contextualization.locale	object	no	Texto localizado mostrado durante el recorrido. Claves: ptBr, enUs, esMx.
contextualization.locale.{ptBr|enUs|esMx}.reason	string	no	Motivo breve de la captura, mostrado durante el recorrido. Máximo 50 caracteres.
contextualization.locale.{ptBr|enUs|esMx}.title	string	no	Título del aviso al cliente mostrado durante el recorrido. Máximo 100 caracteres. Debe proporcionarse junto con text. Las etiquetas HTML son eliminadas.
contextualization.locale.{ptBr|enUs|esMx}.text	string	no	Cuerpo del aviso al cliente mostrado durante el recorrido. Máximo 210 caracteres. Debe proporcionarse junto con title. Las etiquetas HTML son eliminadas.

Ejemplo

cURL

curl -X POST https://api.idcloud.unico.app/client/v1/process \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "callbackUri": "https://app.client.com/callback",
    "flow": "idunicodocs",
    "purpose": "biometryonboarding",
    "person": {
      "duiType": "DUI_TYPE_BR_CPF",
      "duiValue": "12345678909",
      "friendlyName": "Luke Skywalker",
      "phone": "5511912345678",
      "email": "[email protected]"
    }
  }'

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({
    callbackUri: 'https://app.client.com/callback',
    flow: 'idunicodocs',
    purpose: 'biometryonboarding',
    person: {
      duiType: 'DUI_TYPE_BR_CPF',
      duiValue: '12345678909',
      friendlyName: 'Luke Skywalker',
      phone: '5511912345678',
      email: '[email protected]'
    }
  })
});

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

Respuestas

200 OK

{
  "process": {
    "id": "53060f52-f146-4c12-a234-5bb5031f6f5b",
    "state": "PROCESS_STATE_CREATED",
    "flow": "idunicosign",
    "purpose": "biometryonboarding",
    "callbackUri": "https://app.client.com/callback",
    "clientReference": "your-internal-id-123",
    "companyBranchId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "userRedirectUrl": "https://cadastro.unico.app/process/53060f52-f146-4c12-a234-5bb5031f6f5b",
    "token": "eyJhbGciOiJSUzI1NiIs...",
    "webAppToken": "eyJhbGciOiJSUzI1NiIs...",
    "createdAt": "2023-10-09T09:15:25.417105Z",
    "expiresAt": "2023-10-09T16:15:25.417105Z",
    "capacities": [],
    "authenticationInfo": {},
    "person": {
      "duiType": "DUI_TYPE_BR_CPF",
      "duiValue": "12345678909",
      "friendlyName": "Luke Skywalker",
      "phone": "5511912345678",
      "email": "[email protected]",
      "notifications": []
    },
    "companyData": {
      "branchId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "countryCode": "BR"
    }
  }
}

Campo	Tipo	Descripción
process.id	string (UUID)	Identificador del proceso. Úselo para obtener el resultado mediante Obtener proceso.
process.state	enum	PROCESS_STATE_CREATED: proceso creado, recorrido aún no iniciado. PROCESS_STATE_FAILED: la creación del proceso falló.
process.flow	string	Identificador del flujo 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	Su identificador interno enviado en la creación. Solo presente si se proporcionó en la solicitud.
process.companyBranchId	string (UUID)	ID de sucursal. Solo presente si se proporcionó en la solicitud.
process.userRedirectUrl	string	URL para redirigir al usuario (integraciones de Web Redirect e iFrame). No modifique 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 cuando se creó el proceso.
process.expiresAt	string (date-time)	Marca de tiempo después 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 sucursal asociada al proceso.
process.companyData.countryCode	string	Código de país asociado a la sucursal (por ejemplo, BR, MX).

400 Bad Request

Se devuelve cuando el payload de la solicitud está malformado, faltan campos requeridos o el valor de flow es desconocido.

401 Unauthorized

Token Bearer ausente, expirado o inválido. Consulte Autenticació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

Código	Mensaje	Descripción
3	invalid flow	Cuando el flujo especificado no existe.
3	invalid person: friendly name exceeds 50 characters.	Cuando el nombre amigable excede los 50 caracteres.
3	invalid purpose	Cuando el propósito proporcionado es inválido.
3	invalid callbackUri: unable to parse callbackUri: parse "": empty url, invalid callbackUri: url:	Cuando la callbackUri proporcionada es inválida.
3	invalid person: email required for notification channel NOTIFICATION_CHANNEL_EMAIL, invalid email address for notification channel NOTIFICATION_CHANNEL_EMAIL	Cuando el correo electrónico proporcionado es invá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 es invá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) es inválido.
3	invalid expiresIn argument	Cuando el valor de expiresIn es inválido.
3	invalid company_name argument in process contextualization, max length is 20	Cuando contextualization.company_name supera los 20 caracteres.
3	title and text must be provided together in process contexts	Cuando solo se proporciona uno de los campos title o text en un locale.
3	invalid title argument in process contexts, max length is 100	Cuando el title de un locale supera los 100 caracteres.
3	invalid text argument in process contexts, max length is 210	Cuando el text de un locale supera los 210 caracteres.
3	invalid reason argument in process contexts, max length is 50	Cuando el reason de un locale supera los 50 caracteres.
9	XX ID Apikeys are not set	Cuando la API Key no está correctamente configurada.

401 Unauthorized

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

429 Too Many Requests

No se proporciona un código de error detallado para este estado — solo el estado HTTP. Consulte la sección 429 Too Many Requests anterior para mejores prácticas.

500 Internal Server Error

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

Qué sigue

• Después de que el usuario finalice el recorrido, llame a Obtener proceso para obtener el resultado, o espere el webhook.