跳转到主要内容

获取可重用文档

使用此端点检查用户是否已有可重用的文档，然后再启动新的文档采集流程。如果找到文档，可以将其 documentId 直接传递给 POST /processes/v1（Document 类型）以跳过采集步骤。

端点​

环境URL
ProductionGET https://api.id.unico.app/documents/v1
SandboxGET https://api.id.uat.unico.app/documents/v1

请求​

请求头
请求头值
AuthorizationBearer <access_token>（参见身份验证）
APIKEY已启用文档采集与重用功能的已配置 API 密钥。
查询参数
参数类型必填描述
codestring是用户标识符（CPF 或 CURP，不含格式化字符）。
typestring是要查询的文档类型。可接受的值：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 -X GET "https://api.id.unico.app/documents/v1?code=12345678909&type=BR_CNH" \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY"

响应​

200 OK
{
  "items": [
    {
      "documentType": "unico.moja.dictionary.br.cnh.v2.Cnh",
      "documentId": "doc-abc-123"
    }
  ]
}
字段类型描述
itemsarray为该用户找到的可重用文档列表。如果未找到与给定 code 和 type 匹配的可重用文档，则为空数组。
items[].documentTypestring文档类型标识符。可能的值：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[].documentIdstring文档标识符。在 POST /processes/v1 中将此值传入 document.documentId 以重用该文档。
403 Forbidden

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

429 Too Many Requests

Rate limit reached. When your system receives an HTTP 429 error, you must implement mechanisms to prevent cascading failures and avoid worsening the restriction.

Best practices:

  • Cool-down period (backoff): Immediately halt or throttle subsequent requests from your system. Do not continuously retry failed requests in a tight loop.
  • Queueing & throttling: Buffer or queue outgoing requests on your end to control the traffic flow before re-sending them.
  • Exponential backoff with jitter: When retrying, increase the waiting time exponentially between attempts (e.g., 1 s, 2 s, 4 s, 8 s) and add a small random delay ("jitter") to prevent a herd effect where all queued requests retry at the exact same millisecond.
警告

Continuously hitting a rate-limited endpoint without backing off can prolong the restriction period and severely impact your system's operational throughput. Properly throttling requests on your side ensures a smoother, more resilient integration.

For default limits, increase requests and additional details, see Rate Limits.

使用 documentId 进行文档重用​

获取 documentId 后，将其传入 Document 流程请求中以跳过采集步骤：

{
  "subject": {
    "code": "12345678909",
    "name": "Luke Skywalker"
  },
  "document": {
    "purpose": "onboarding",
    "authProcessId": "<biometric-process-id>",
    "documentId": "doc-abc-123"
  }
}
字段描述
document.purpose此文档流程的业务用途。可接受的值：creditprocess、carpurchase、paybypaycheck、onboarding、fgts。这些值专用于 Document API，与生物识别 SDK 的 purpose 枚举不同。
document.authProcessId之前为该用户创建的生物识别流程的 ID（来自 POST /processes/v1）。
document.documentId从此端点响应中获取的文档 ID。提供此参数后，可以省略 document.files — 平台会自动检索之前采集的文档。

有关完整的 Document 流程请求模式，请参见创建 Document 流程。

错误代码​

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