Definir Documento do Processo

Define o documento de identificação (CPF, CURP, SSN ou outro duiType) em um processo que foi criado sem um. Uma vez definido, o documento é imutável.

Disponível apenas para processos cujo Fluxo Personalizado permite criação sem documento — ou seja, processos no estado AWAITING_FOR_DOCUMENT.

Endpoint

Ambiente	URL
Produção	POST https://api.idcloud.unico.app/client/v1/process/{processId}/document
Sandbox	POST https://api.idcloud.uat.unico.app/client/v1/process/{processId}/document

Requisição

Headers

Header	Valor
Authorization	Bearer <access_token> (veja Autenticação)
Content-Type	application/json

Parâmetros de caminho

Campo	Tipo	Obrigatório	Descrição
processId	string	sim	ID do processo retornado em process.id na criação.

Parâmetros do corpo

Campo	Tipo	Obrigatório	Descrição
duiType	enum	sim	Tipo de documento. Valores: DUI_TYPE_BR_CPF, DUI_TYPE_MX_CURP, DUI_TYPE_US_SSN. Este endpoint suporta um subconjunto dos tipos de documento aceitos por Criar Processo — Fluxos Personalizados que permitem criação de documento opcional são atualmente validados contra esta lista mais restrita.
duiValue	string	sim	Número do documento, sem formatação. Máximo de 320 caracteres (acomoda identificadores codificados ou compostos; números de documento padrão como CPF ou CURP são significativamente menores).

Exemplo

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

Respostas

200 OK

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

Campo	Tipo	Descrição
process.id	string	Identificador do processo.
process.person.duiType	string	Tipo de documento definido no processo.
process.person.duiValue	string	Valor do documento definido no processo.

400 Bad Request

Retornado quando o payload da requisição está malformado, campos obrigatórios estão ausentes ou o estado do processo não permite a operação.

401 Unauthorized

Bearer token ausente, expirado ou inválido. Veja Autenticação.

404 Not Found

Processo não encontrado.

429 Too Many Requests

Limite de requisições atingido. Quando seu sistema recebe um erro HTTP 429, você deve implementar mecanismos para prevenir falhas em cascata e evitar agravar a restrição.

Boas práticas:

• Período de espera (backoff): Interrompa ou limite imediatamente as requisições subsequentes do seu sistema. Não tente reenviar requisições falhas continuamente em um loop apertado.
• Enfileiramento e controle de fluxo: Armazene ou enfileire as requisições de saída do seu lado para controlar o fluxo de tráfego antes de reenviá-las.
• Backoff exponencial com jitter: Ao tentar novamente, aumente o tempo de espera exponencialmente entre as tentativas (ex.: 1 s, 2 s, 4 s, 8 s) e adicione um pequeno atraso aleatório ("jitter") para evitar um efeito manada onde todas as requisições enfileiradas tentam novamente no exato mesmo milissegundo.

aviso

Continuar acessando um endpoint com limite de taxa sem aplicar backoff pode prolongar o período de restrição e impactar severamente a taxa de transferência operacional do seu sistema. Controlar adequadamente as requisições do seu lado garante uma integração mais suave e resiliente.

Para limites padrão, aumento de requisições e detalhes adicionais, veja Limites de Taxa.

Códigos de Erro

400 Bad Request

Código	Mensagem	Descrição
3	process id is invalid	Quando o ID do processo é inválido.
3	dui_type is required	Quando o tipo de documento não é fornecido.
3	dui_value is required	Quando o número do documento não é fornecido.
3	dui_value exceeds maximum length	Quando o número do documento excede o limite máximo de caracteres.
9	process is not awaiting for document	Quando o processo especificado não aceita envio de documento.
9	process expired	Quando o processo especificado expirou.
9	document already set, cannot be modified	Quando o processo já possui um documento vinculado.
9	process already finished	Quando o processo já foi finalizado.
9	flow does not allow optional document	Quando o documento é obrigatório para o fluxo executado pelo processo.

401 Unauthorized

Mensagem	Descrição
Jwt header is an invalid JSON	Quando o access token utilizado contém caracteres incorretos.
Jwt is expired	Quando o access token utilizado expirou.

404 Not Found

Código	Mensagem	Descrição
5	error getting process: rpc error: code = NotFound desc = process not found	Quando o ID do processo não foi encontrado.

429 Too Many Requests

Nenhum código de erro detalhado é fornecido para este status — apenas o status HTTP. Consulte a seção 429 Too Many Requests acima para boas práticas.

500 Internal Server Error

Código	Mensagem	Descrição
99999	Internal failure! Try again later	Quando ocorre um erro interno.

Próximos passos

• Após definir o documento, o processo continua seu pipeline. Chame Obter Processo para buscar o resultado, ou aguarde o webhook.