Crear Proceso

Este es el punto de entrada de toda integración Web y SDK. Su back-end lo llama para crear un proceso; su front-end utiliza 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 y 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

Cabeceras

Cabecera	Valor
Authorization	Bearer <access_token> (ver 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 una vez que termina la jornada. 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. Ver 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.
person.duiValue	string	sí	Número de documento, sin formato.
person.friendlyName	string	no	Nombre visible del usuario mostrado en la interfaz de la jornada. Máximo 50 caracteres.
person.phone	string	no	Número de teléfono en formato DDI + DDD + número, sin separadores. Requerido cuando se envían notificaciones por SMS o WhatsApp.
person.email	string	no	Dirección de correo electrónico. Requerida para flujos con Firma Electrónica.
person.notifications	array	no	Canales de notificación para enviar el enlace de la jornada. 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 Smart Revalidation (idsmart).
references	array	condicional	Entradas de referencia para flujos de validación 1:1 y Smart Revalidation, 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 Smart Revalidation. 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 referencias cruzadas 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 su creación. Formato: "3600s". Por defecto es 7 días si se omite.
flow_config	object	no	Configuraciones de sobrescritura por flujo.
flow_config.biometry_capture.enabled_back_camera	boolean	no	Usa la cámara trasera del dispositivo. No compatible con flujos de captura de documentos o Firma Electrónica.
contextualization	object	no	Contexto de transacción mostrado al usuario durante la jornada para explicar la captura.
contextualization.currency	string	no	Código de moneda mostrado al usuario. Valores aceptados: BRL, MXN, USD.
contextualization.price	number	no	Monto de transacción mostrado al usuario.
contextualization.locale	object	no	Texto de motivo localizado. Claves: ptBr, enUs, esMx — cada una con una cadena reason que se muestra durante la jornada.

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, jornada aún no iniciada. PROCESS_STATE_FAILED — falló la creación del proceso.
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 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)	Timestamp de cuándo se creó el proceso.
process.expiresAt	string (date-time)	Timestamp a partir del 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	Reflejo del objeto person enviado en la creación.
process.companyData.branchId	string (UUID)	ID de sucursal asociado 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á mal formado, faltan campos requeridos o el valor de flow es desconocido.

401 Unauthorized

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

429 Too Many Requests

Límite de tasa alcanzado. Reintente después del intervalo indicado en los encabezados de respuesta.

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 visible supera 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 el callbackUri proporcionado es inválido.
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 electrónico 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.
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.

500 Internal Server Error

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

Próximos pasos

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