Obter Documentos Reutilizáveis

Use este endpoint para verificar se um usuário já possui um documento disponível para reutilização antes de iniciar um novo fluxo de captura de Documento. Se um documento for encontrado, seu documentId pode ser passado diretamente para POST /processes/v1 (tipo Documento) para pular a etapa de captura.

Endpoint

Ambiente	URL
Produção	GET https://api.id.unico.app/documents/v1
Sandbox	GET https://api.id.uat.unico.app/documents/v1

Requisição

Headers

Header	Valor
Authorization	Bearer <access_token> (veja Autenticação)
APIKEY	Chave de API provisionada com Captura de Documentos e Reutilização habilitada.

Parâmetros de consulta

Parâmetro	Tipo	Obrigatório	Descrição
code	string	sim	Identificador do usuário (CPF ou CURP, sem formatação).
type	string	sim	Tipo de documento a consultar. Valores aceitos: BR_RG, BR_CNH, BR_CIN, BR_PASSPORT.

observação

Os valores de type acima são específicos deste endpoint. Não os confunda com:

• subject.duiType em requisições POST — usa o prefixo DUI_TYPE_* e identifica a pessoa, não o tipo de documento (ex.: DUI_TYPE_BR_CPF).
• documentType na resposta — usa o caminho completo do registro (ex.: unico.moja.dictionary.br.cnh.v2.Cnh).

Exemplo

cURL

curl -X GET "https://api.id.unico.app/documents/v1?code=12345678909&type=BR_CNH" \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY"

Node.js

import fetch from 'node-fetch';

const params = new URLSearchParams({ code: '12345678909', type: 'BR_CNH' });
const res = await fetch(
  `https://api.id.unico.app/documents/v1?${params}`,
  {
    headers: {
      Authorization: `Bearer ${accessToken}`,
      APIKEY: apiKey
    }
  }
);
const data = await res.json();
// data.items[0].documentId → pass to POST /processes/v1 for reuse

Respostas

200 OK

{
  "items": [
    {
      "documentType": "unico.moja.dictionary.br.cnh.v2.Cnh",
      "documentId": "doc-abc-123"
    }
  ]
}

Campo	Tipo	Descrição
items	array	Lista de documentos reutilizáveis encontrados para o usuário. Array vazio se nenhum documento reutilizável foi encontrado para o code e type fornecidos.
items[].documentType	string	Identificador do tipo de documento. Valores possíveis: unico.moja.dictionary.br.rg.v2.Rg, unico.moja.dictionary.br.cnh.v2.Cnh, unico.moja.dictionary.br.cin.v1.Cin, unico.moja.dictionary.br.passaporte.v1.Passaporte.
items[].documentId	string	Identificador do documento. Passe este valor em document.documentId no POST /processes/v1 para reutilizar o documento.

403 Forbidden

Bearer token ou APIKEY ausente, expirado ou inválido.

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.

Usando o documentId para reutilização

Após obter um documentId, passe-o na requisição de processo de Documento para pular a captura:

{
  "subject": {
    "code": "12345678909",
    "name": "Luke Skywalker"
  },
  "document": {
    "purpose": "onboarding",
    "authProcessId": "<biometric-process-id>",
    "documentId": "doc-abc-123"
  }
}

Campo	Descrição
document.purpose	Finalidade de negócio para este processo de documento. Valores aceitos: creditprocess, carpurchase, paybypaycheck, onboarding, fgts. Estes valores são específicos da API de Documentos e diferem do enum purpose do SDK biométrico.
document.authProcessId	ID do processo biométrico criado anteriormente para este usuário (de POST /processes/v1).
document.documentId	ID do documento obtido na resposta deste endpoint. Quando fornecido, document.files pode ser omitido — a plataforma recupera o documento capturado anteriormente automaticamente.

Para o schema completo da requisição de processo de Documento, veja Criar Processo de Documento.

Códigos de Erro

400 Bad Request

Código	Mensagem	Descrição
20507	O parâmetro subject.code é inválido.	Valor de identificador malformado ou inexistente (CPF ou CURP).
20002	O parâmetro APIKey não foi informado.	Header APIKEY ausente.
20001	O parâmetro authtoken não foi informado.	Header de token de autenticação ausente.

403 Forbidden

Código	Mensagem	Descrição
30020	The provided authorization token does not have permission to perform this action.	Token não possui permissão para acessar a selfie do documento.
30017	User does not have permission to perform this action.	JWT malformado ou usuário sem permissão para executar esta operação.
10502	O token informado está expirado.	Access-token expirado.
10501	O token informado é inválido.	Token de autenticação inválido.
10201	O AppKey informado é inválido.	APIKEY ausente ou inexistente.

404 Not Found

Código	Mensagem	Descrição
99987	Attachment not found.	Anexo associado ao documento não foi encontrado.
50001	The process is not found.	Nenhum documento encontrado para os parâmetros fornecidos.

500 Internal Server Error

Código	Mensagem	Descrição
99999	Internal failure! Try again later.	Erro de processamento no servidor.