---
title: 获取可重用证件
description: 在开始新的采集流程前，检查用户是否已存档可重用的证件。
canonical: https://developer.unico.io/zh-CN/developers/api-reference/get-document
locale: zh-CN
generated_by: markdown-export
---

- [/zh-CN/](/zh-CN/)
- API 参考
- 获取可重用证件

**本页内容# 获取可重用证件

在开始新的 Document 采集流程之前，使用此端点检查用户是否已有可供重用的证件。如果找到证件，可以将其 `documentId` 直接传给 `POST /processes/v1`（Document 类型），从而跳过采集步骤。
### 端点​

环境URL**生产环境**`GET https://api.idcloud.unico.app/documents/v1`**沙箱环境**`GET https://api.idcloud.uat.unico.app/documents/v1`
### 请求​

Headers
Header值`Authorization``Bearer <access_token>`（参见[身份验证](/zh-CN/developers/start/authentication))`APIKEY`已启用文档采集与重用的已配置 API 密钥。
Query parameters
参数类型是否必填描述`code`string是用户标识符（CPF 或 CURP，不带格式）。`type`string是要查询的证件类型。可接受的值：`BR_RG`、`BR_CNH`、`BR_CIN`、`BR_PASSPORT`。
备注上述 `type` 值是此端点专用的。请勿将其与以下内容混淆：
POST 请求中的 `subject.duiType`——使用 `DUI_TYPE_*` 前缀，标识的是人，而不是证件类型（例如 `DUI_TYPE_BR_CPF`）。
响应中的 `documentType`——使用完整的注册表路径（例如 `unico.moja.dictionary.br.cnh.v2.Cnh`）。

### 示例​

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

```
import fetch from 'node-fetch';const params = new URLSearchParams({ code: '12345678909', type: 'BR_CNH' });const res = await fetch(  `https://api.idcloud.unico.app/documents/v1?${params}`,  {    headers: {      Authorization: `Bearer ${accessToken}`,      APIKEY: apiKey    }  });const data = await res.json();// data.items[0].documentId → 传给 POST /processes/v1 以重用该证件
```

### 响应​

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

字段类型描述`items`array为该用户找到的可重用证件列表。如果未针对给定的 `code` 和 `type` 找到可重用证件，则为空数组。`items[].​documentType`string证件类型标识符。可能的值：`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证件标识符。在 `POST /processes/v1` 的 `document.documentId` 中传入此值即可重用该证件。
### 使用 documentId 进行重用​

获得 `documentId` 后，可在 Document 流程请求中传入该值以跳过采集：
```
{  "subject": {    "code": "12345678909",    "name": "Luke Skywalker"  },  "document": {    "purpose": "onboarding",    "authProcessId": "<biometric-process-id>",    "documentId": "doc-abc-123"  }}
```

字段描述`document.purpose`此 Document 流程的业务用途。可接受的值：`creditprocess`、`carpurchase`、`paybypaycheck`、`onboarding`、`fgts`。这些值是 Document API 专用的，与生物识别 SDK 的 `purpose` 枚举不同。`document.​authProcessId`此前为该用户创建的生物识别流程的 ID（来自 `POST /processes/v1`）。`document.documentId`从此端点响应中获得的证件 ID。提供该值时，可省略 `document.files`——平台会自动获取此前采集的证件。
### 错误代码​

400 Bad Request403 Forbidden404 Not Found429 Too Many Requests500 Internal Server Error代码消息描述`20507`O parâmetro subject.code é inválido.标识符值（CPF 或 CURP）格式错误或不存在。`20002`O parâmetro APIKey não foi informado.缺少 APIKEY header。`20001`O parâmetro authtoken não foi informado.缺少身份验证令牌 header。Bearer 令牌或 `APIKEY` 缺失、已过期或无效。代码消息描述`30020`The provided authorization token does not have permission to perform this action.令牌没有访问该证件自拍照的权限。`30017`User does not have permission to perform this action.JWT 格式错误，或用户无权执行此操作。`10502`O token informado está expirado.访问令牌已过期。`10501`O token informado é inválido.身份验证令牌无效。`10201`O AppKey informado é inválido.APIKEY 缺失或不存在。代码消息描述`99987`Attachment not found.未找到与该证件关联的附件。`50001`The process is not found.未找到符合所提供参数的证件。已达到速率限制。当您的系统收到 HTTP 429 错误时，必须实施机制以防止级联故障并避免加重限制。
**最佳实践：**

**冷却期（backoff）：** 立即停止或限制系统的后续请求。不要在紧密循环中持续重试失败的请求。
**排队与限流（Queueing & throttling）：** 在您的一侧缓冲或排队传出请求，以便在重新发送之前控制流量。
**带抖动的指数退避（Exponential backoff with jitter）：** 重试时，在尝试之间以指数方式增加等待时间（例如，1秒、2秒、4秒、8秒），并添加一个小的随机延迟（"抖动"），以防止所 有排队请求在完全相同的毫秒重试的羊群效应。

警告在未应用退避的情况下持续请求受速率限制的端点，可能会**延长限制期**并严重影响系统的运行吞吐量。在您的一侧正确限流请求可确保更顺畅、更具弹性的集成。
有关默认限制、增加请求及其他详细信息，请参阅[速率限制](/zh-CN/developers/start/rate-limits)。代码消息描述`99999`Internal failure! Try again later.服务器端处理错误。最后更新 于 2026年10月8日**