---
title: Obter Documentos Reutilizáveis
description: Verifique se um usuário já possui um documento reutilizável em arquivo antes de iniciar um novo fluxo de captura.
canonical: https://developer.unico.io/pt-BR/dual-api/developers/api-reference/api/get-document
locale: pt-BR
generated_by: markdown-export
---

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](../authentication))|
| `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`. |

:::note
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

```bash
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

```javascript
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

```json
{
  "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. |

### Usando o documentId para reutilização

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

```json
{
  "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](./post-processes-document).

### 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

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

| 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. |

### 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.

:::warning
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](../rate-limits).

### 500 Internal Server Error

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