Establecer documento del proceso

Establece el documento de identificación (CPF, CURP, SSN u otro duiType) en un proceso que fue creado sin uno. Una vez establecido, el documento es inmutable.

Solo disponible para procesos cuyo flujo personalizado permite la creación sin documento, es decir, procesos en el estado AWAITING_FOR_DOCUMENT.

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

Encabezados

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

Parámetros de ruta

Campo	Tipo	Requerido	Descripción
processId	string	sí	ID del proceso devuelto en process.id en la creación.

Parámetros del cuerpo

Campo	Tipo	Requerido	Descripción
duiType	enum	sí	Tipo de documento. Valores: DUI_TYPE_BR_CPF, DUI_TYPE_MX_CURP, DUI_TYPE_US_SSN. Este endpoint soporta un subconjunto de los tipos de documento aceptados por Crear proceso: los flujos personalizados que permiten creación de documento opcional se validan actualmente contra esta lista más reducida.
duiValue	string	sí	Número de documento, sin formato. Máximo 320 caracteres (admite identificadores codificados o compuestos; los números de documento estándar como CPF o CURP son significativamente más cortos).

Ejemplo

cURL

curl -X POST https://api.idcloud.unico.app/client/v1/process/abc-123/document \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "duiType": "DUI_TYPE_BR_CPF",
    "duiValue": "12345678901"
  }'

Node.js

import fetch from 'node-fetch';

const res = await fetch(
  'https://api.idcloud.unico.app/client/v1/process/abc-123/document',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      duiType: 'DUI_TYPE_BR_CPF',
      duiValue: '12345678901',
    }),
  }
);

const { process: proc } = await res.json();
// proc.id, proc.person.duiType, proc.person.duiValue

Respuestas

200 OK

{
  "process": {
    "id": "abc-123",
    "person": {
      "duiType": "DUI_TYPE_BR_CPF",
      "duiValue": "12345678901"
    }
  }
}

Campo	Tipo	Descripción
process.id	string	Identificador del proceso.
process.person.duiType	string	Tipo de documento establecido en el proceso.
process.person.duiValue	string	Valor del documento establecido en el proceso.

400 Bad Request

Se devuelve cuando el payload de la solicitud está malformado, faltan campos requeridos o el estado del proceso no permite la operación.

401 Unauthorized

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

404 Not Found

Proceso no encontrado.

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	process id is invalid	Cuando el ID del proceso es inválido.
3	dui_type is required	Cuando no se proporciona el tipo de documento.
3	dui_value is required	Cuando no se proporciona el número de documento.
3	dui_value exceeds maximum length	Cuando el número de documento excede el límite máximo de caracteres.
9	process is not awaiting for document	Cuando el proceso especificado no acepta envío de documento.
9	process expired	Cuando el proceso especificado ha expirado.
9	document already set, cannot be modified	Cuando el proceso ya tiene un documento vinculado.
9	process already finished	Cuando el proceso ya ha sido finalizado.
9	flow does not allow optional document	Cuando el documento es obligatorio para el flujo ejecutado por el proceso.

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.

404 Not Found

Código	Mensaje	Descripción
5	error getting process: rpc error: code = NotFound desc = process not found	Cuando no se encontró el ID del proceso.

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 ocurre un error interno.

Qué sigue

• Después de establecer el documento, el proceso continúa su pipeline. Llame a Obtener proceso para obtener el resultado, o espere el webhook.