Definir Documento del ProcesoPOST

Crea un proceso sin documento, deja que el usuario complete la captura y luego envía el documento desde tu back-end. El proceso finaliza después de eso.

MarkdownChatGPTClaude

Ciclo de vida

1. Tu back-end crea el proceso con Crear Proceso, sin person.duiType ni person.duiValue. El flow debe permitir un documento opcional. El proceso comienza como PROCESS_STATE_CREATED.
2. El usuario recorre el flujo y realiza la captura.
3. La Unico API mueve el proceso a AWAITING_FOR_DOCUMENT, el estado que Obtener Proceso devuelve mientras el proceso espera el documento. Ya puedes leer los resultados parciales de las capacidades que no dependen de duiValue.
4. Tu back-end llama a este endpoint con el ID del proceso en la URL y el documento en el cuerpo. La Unico API entonces finaliza el proceso, que pasa a PROCESS_STATE_FINISHED.

La respuesta no incluye el resultado final

Lee el estado y el resultado finales con Obtener Proceso, o espera el webhook.

Endpoint

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

Solicitud

Headers

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

Las credenciales necesitan el mismo permiso usado para llamar a Crear Proceso.

Parámetros de ruta

Parámetro	Tipo	Obligatorio	Descripción
processId	string (UUID)	sí	Identificador del proceso devuelto por Crear Proceso.

Parámetros del cuerpo

Campo	Tipo	Obligatorio	Descripción
duiType	enum	sí	Tipo de documento. DUI_TYPE_UNSPECIFIED se rechaza. Ver valores de duiType a continuación.
duiValue	string	sí	Número del documento, sin formato. Hasta 320 caracteres.

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

Cuándo se acepta la llamada

• El proceso está en AWAITING_FOR_DOCUMENT: el usuario ya completó la captura.
• El proceso no ha expirado.
• El flow permite un documento opcional.

El documento es inmutable. Una segunda llamada falla, porque el proceso ya no está esperando un documento.

Ejemplo

cURL

curl -X POST https://api.idcloud.unico.app/client/v1/process/$PROCESS_ID/document \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "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/${processId}/document`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      duiType: 'DUI_TYPE_BR_CPF',
      duiValue: '12345678909',
    }),
  }
);
const { processId: id, duiType, duiValue } = await res.json();

Respuestas

200 OK

{
  "processId": "3116552c-6a3e-4c1f-9d2b-8f0e7a5b4c21",
  "duiType": "DUI_TYPE_BR_CPF",
  "duiValue": "12345678909"
}

Campo	Tipo	Descripción
processId	string (UUID)	Identificador del proceso.
duiType	enum	Tipo de documento registrado para el proceso.
duiValue	string	Número del documento registrado para el proceso.

Los valores del ejemplo son ilustrativos.

Códigos de Error

400 Bad Request

Código	Descripción
3	processId falta o no es válido, duiType no está especificado, o duiValue está vacío o tiene más de 320 caracteres.
9	El proceso no está esperando un documento (esto incluye un documento ya definido), ha expirado o finalizado, o el flow no permite un documento opcional.

401 Unauthorized

Código	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	Descripción
7	Las credenciales no tienen el permiso requerido por Crear Proceso.

404 Not Found

Código	Descripción
5	El proceso no existe o no pertenece a tu empresa.

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	Descripción
13	No se pudo guardar el documento.

nota

El documento se registra en el servicio de identidad antes de almacenarse. Si ese registro falla, la llamada devuelve el estado de esa falla.

Qué sigue

• Para leer el estado y el resultado finales, ver Obtener Proceso.
• Para recibir una notificación cuando el proceso finalice, ver Webhooks and Events.