获取可复用文档

使用此端点可在开始新的文档采集流程之前，检查用户是否已有可复用的文档。若找到文档，可将其 documentId 直接传入 POST /processes/v1（文档类型）以跳过采集步骤。

端点

环境	URL
生产环境	`GET https://api.id.unico.app/documents/v1`
沙盒环境	`GET https://api.id.uat.unico.app/documents/v1`

请求

请求头

请求头	值
`Authorization`	`Bearer <access_token>`（参见身份验证）
`APIKEY`	已开通文档采集与复用功能的 API 密钥。

查询参数

参数	类型	必填	描述
`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）。

示例

cURL
Node.js

curl -X GET "https://api.id.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.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

响应

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` 中传入此值以复用文档。

403 Forbidden

Bearer 令牌或 APIKEY 缺失、已过期或无效。

429 Too Many Requests

已达到速率限制。请在 Retry-After 响应标头中指示的时间间隔后重试。请参阅速率限制。

使用 documentId 进行文档复用

获取到 documentId 后，在文档流程请求中传入该值以跳过采集步骤：

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

字段	描述
`document.purpose`	此文档流程的业务目的。可接受的值：`creditprocess`、`carpurchase`、`paybypaycheck`、`onboarding`、`fgts`。这些值专用于文档 API，与生物特征 SDK 的 `purpose` 枚举不同。
`document.authProcessId`	先前为该用户创建的生物特征流程 ID（来自 `POST /processes/v1`）。
`document.documentId`	从此端点响应中获取的文档 ID。提供此值后，`document.files` 可省略——平台将自动检索先前采集的文档。

有关完整的文档流程请求 Schema，请参见创建文档流程。

错误代码

400 Bad Request
403 Forbidden
404 Not Found
500 Internal Server Error

代码	消息	描述
`20507`	O parâmetro subject.code é inválido.	标识符值（CPF 或 CURP）格式错误或不存在。
`20002`	O parâmetro APIKey não foi informado.	缺少 APIKEY 请求头。
`20001`	O parâmetro authtoken não foi informado.	缺少身份验证令牌请求头。

代码	消息	描述
`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.	access-token 已过期。
`10501`	O token informado é inválido.	身份验证令牌无效。
`10201`	O AppKey informado é inválido.	APIKEY 缺失或不存在。

代码	消息	描述
`99987`	Attachment not found.	与文档关联的附件未找到。
`50001`	The process is not found.	未找到符合所提供参数的文档。

代码	消息	描述
`99999`	Internal failure! Try again later.	服务器端处理错误。

端点​

请求​

示例​

响应​

使用 documentId 进行文档复用​

错误代码​

端点

请求

示例

响应

使用 documentId 进行文档复用

错误代码