Definir Documento do ProcessoPOST

Crie um processo sem documento, deixe o usuário concluir a captura e então envie o documento a partir do seu back-end. O processo é finalizado depois disso.

MarkdownChatGPTClaude

Ciclo de vida

1. Seu back-end cria o processo com Criar Processo, sem person.duiType e person.duiValue. O fluxo precisa permitir documento opcional. O processo começa como PROCESS_STATE_CREATED.
2. O usuário executa a jornada e realiza a captura.
3. A Unico API move o processo para AWAITING_FOR_DOCUMENT, o estado que Obter Processo retorna enquanto o processo aguarda o documento. Você já pode ler os resultados parciais das capacidades que não dependem de duiValue.
4. Seu back-end chama este endpoint com o ID do processo na URL e o documento no body. A Unico API então finaliza o processo, que passa para PROCESS_STATE_FINISHED.

A resposta não traz o resultado final

Leia o estado e o resultado finais com Obter Processo ou aguarde o webhook.

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

As credenciais precisam da mesma permissão usada para chamar Criar Processo.

Parâmetros de path

Parâmetro	Tipo	Obrigatório	Descrição
processId	string (UUID)	sim	Identificador do processo retornado por Criar Processo.

Parâmetros do body

Campo	Tipo	Obrigatório	Descrição
duiType	enum	sim	Tipo do documento. DUI_TYPE_UNSPECIFIED é rejeitado. Veja valores de duiType abaixo.
duiValue	string	sim	Número do documento, sem formatação. Até 320 caracteres.

Valores de duiType

País	Valor	Descrição
AR	DUI_TYPE_AR_PASSPORT	Passaporte Argentino
AR	DUI_TYPE_AR_DNI	DNI Argentino
AR	DUI_TYPE_AR_LNC	Carteira de motorista Argentina (Licencia Nacional de Conducir)
AT	DUI_TYPE_AT_STNR	Número de Contribuinte Austríaco (STNR)
BE	DUI_TYPE_BE_NN	Número Nacional Belga (NN)
BR	DUI_TYPE_BR_CPF	CPF Brasileiro
BR	DUI_TYPE_BR_PASSPORT	Passaporte Brasileiro
BR	DUI_TYPE_BR_CNPJ	CNPJ Brasileiro
CA	DUI_TYPE_CA_SIN	SIN Canadense
CH	DUI_TYPE_CH_AHV	Número AHV/AVS Suíço
CL	DUI_TYPE_CL_RUN	RUN Chileno
CL	DUI_TYPE_CL_PASSPORT	Passaporte Chileno
CL	DUI_TYPE_CL_LICENCIA_CONDUCIR	Carteira de motorista Chilena (Licencia de Conducir)
CO	DUI_TYPE_CO_NIT	NIT Colombiano
CO	DUI_TYPE_CO_PASSPORT	Passaporte Colombiano
CO	DUI_TYPE_CO_LICENCIA_CONDUCCION	Carteira de motorista Colombiana (Licencia de Conducción)
CO	DUI_TYPE_CO_CC	Cédula de Cidadania Colombiana (Cédula de Ciudadanía)
DE	DUI_TYPE_DE_IDNR	Número de Identificação Fiscal Alemão (IdNr)
DK	DUI_TYPE_DK_CPR	CPR Dinamarquês
EC	DUI_TYPE_EC_NI	NI Equatoriano
ES	DUI_TYPE_ES_NIE	Número de Identidade de Estrangeiro Espanhol (NIE)
ES	DUI_TYPE_ES_DNI	Documento Nacional de Identidade Espanhol (DNI)
FI	DUI_TYPE_FI_HETU	Código de Identidade Pessoal Finlandês (HETU)
FR	DUI_TYPE_FR_SPI	Número de Referência 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 Indonésio
IE	DUI_TYPE_IE_PPSN	Número de Serviço Público Pessoal Irlandês (PPSN)
IT	DUI_TYPE_IT_CF	Codice Fiscale Italiano (CF)
LK	DUI_TYPE_LK_NIC	NIC do Sri Lanka
LU	DUI_TYPE_LU_MATRICULE	Número de Identificação Nacional de Luxemburgo (Matricule)
MX	DUI_TYPE_MX_CURP	CURP Mexicano
MX	DUI_TYPE_MX_RFC_PERSONA_FISICA	RFC Mexicano (Pessoa Física)
MX	DUI_TYPE_MX_LICENCIA_CONDUCIR	Carteira de motorista Mexicana (Licencia de Conducir)
NG	DUI_TYPE_NG_NIN	NIN Nigeriano
NG	DUI_TYPE_NG_BVN	Número de Verificação Bancária Nigeriano (BVN)
NG	DUI_TYPE_NG_BVN_TOKEN	Token de BVN Nigeriano (hash)
NG	DUI_TYPE_NG_NIN_TOKEN	Token de NIN Nigeriano (hash)
NL	DUI_TYPE_NL_BSN	Número de Serviço ao Cidadão Holandês (BSN)
NO	DUI_TYPE_NO_FNR	Número de Identidade Nacional Norueguês (Fødselsnummer)
PE	DUI_TYPE_PE_RUC	RUC Peruano
PE	DUI_TYPE_PE_DNI	DNI Peruano
PE	DUI_TYPE_PE_PASSPORT	Passaporte Peruano
PL	DUI_TYPE_PL_PESEL	PESEL Polonês
PT	DUI_TYPE_PT_NIF	Número de Identificação Fiscal Português (NIF)
SE	DUI_TYPE_SE_PNR	Número Pessoal Sueco (PNR)
SE	DUI_TYPE_SE_SAMORDNINGSNUMMER	Número de Coordenação Sueco (Samordningsnummer)
TR	DUI_TYPE_TR_TCKN	Número de Identificação Turco (TCKN)
US	DUI_TYPE_US_SSN	SSN dos Estados Unidos
US	DUI_TYPE_US_PASSPORT	Passaporte dos Estados Unidos
US	DUI_TYPE_US_DRIVER_LICENSE	Carteira de motorista dos Estados Unidos
US	DUI_TYPE_US_PASSPORT_CARD	Cartão de Passaporte dos Estados Unidos
US	DUI_TYPE_US_POLYCARBONATE_PASSPORT	Passaporte de Policarbonato dos Estados Unidos
US	DUI_TYPE_US_ID_CARD	Carteira de Identidade dos Estados Unidos
UY	DUI_TYPE_UY_CI	CI Uruguaia
ZZ	DUI_TYPE_ZZ_EMAIL	Endereço de e-mail
ZZ	DUI_TYPE_ZZ_PHONE_NUMBER	Número de telefone

Quando a chamada é aceita

• O processo está em AWAITING_FOR_DOCUMENT: o usuário já concluiu a captura.
• O processo não expirou.
• O fluxo permite documento opcional.

O documento é imutável. Uma segunda chamada falha, porque o processo não está mais aguardando um documento.

Exemplo

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();

Respostas

200 OK

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

Campo	Tipo	Descrição
processId	string (UUID)	Identificador do processo.
duiType	enum	Tipo de documento registrado para o processo.
duiValue	string	Número do documento registrado para o processo.

Os valores do exemplo são fictícios.

Códigos de Erro

400 Bad Request

Código	Descrição
3	processId está ausente ou é inválido, duiType não foi especificado, ou duiValue está vazio ou tem mais de 320 caracteres.
9	O processo não está aguardando um documento (o que inclui um documento já definido), expirou ou foi finalizado, ou o fluxo não permite documento opcional.

401 Unauthorized

Código	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.

403 Forbidden

Código	Descrição
7	As credenciais não têm a permissão exigida por Criar Processo.

404 Not Found

Código	Descrição
5	O processo não existe ou não pertence à sua empresa.

429 Too Many Requests

Limite de taxa atingido. Quando seu sistema recebe um erro HTTP 429, você deve implementar mecanismos para prevenir falhas em cascata e evitar o agravamento da restrição.

Boas práticas:

• Período de resfriamento (backoff): Interrompa ou reduza imediatamente as requisições subsequentes do seu sistema. Não reenvie continuamente requisições com falha em um loop curto.
• Filas e limitação (Queueing & throttling): Armazene em buffer 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 retentar, aumente o tempo de espera exponencialmente entre as tentativas (por exemplo, 1 s, 2 s, 4 s, 8 s) e adicione um pequeno atraso aleatório ("jitter") para evitar um efeito de manada onde todas as requisições enfileiradas retentam exatamente no mesmo milissegundo.

aviso

Enviar requisições continuamente a um endpoint com limite de taxa sem aplicar backoff pode prolongar o período de restrição e impactar severamente a capacidade operacional do seu sistema. Limitar 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, consulte Limites de taxa.

500 Internal Server Error

Código	Descrição
13	Não foi possível salvar o documento.

observação

O documento é registrado no serviço de identidade antes de ser armazenado. Se esse registro falhar, a chamada retorna o status dessa falha.

Próximos passos

• Para ler o estado e o resultado finais, veja Obter Processo.
• Para ser notificado quando o processo for finalizado, veja Webhooks e Eventos.