获取可重用证件

在开始新的 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>`（参见身份验证)
`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）。

示例

cURL
Node.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 Request
403 Forbidden
404 Not Found
429 Too Many Requests
500 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.	未找到符合所提供参数的证件。

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

端点​

请求​

示例​

响应​

使用 documentId 进行重用​

错误代码​

端点

请求

示例

响应

使用 documentId 进行重用

错误代码