设置流程文档

在创建时未提供身份证明文件（CPF、CURP、SSN 或其他 duiType）的流程上设置文件。设置后，文件不可修改。

仅适用于 Custom Flow 允许在没有文件的情况下创建的流程 — 即处于 AWAITING_FOR_DOCUMENT 状态的流程。

端点

环境	URL
生产环境	POST https://api.idcloud.unico.app/client/v1/process/{processId}/document
沙箱环境	POST https://api.idcloud.uat.unico.app/client/v1/process/{processId}/document

请求

请求头

请求头	值
Authorization	Bearer <access_token>（参见认证）
Content-Type	application/json

路径参数

字段	类型	必填	描述
processId	string	是	创建时在 process.id 中返回的流程 ID。

请求体参数

字段	类型	必填	描述
duiType	enum	是	文件类型。值：DUI_TYPE_BR_CPF、DUI_TYPE_MX_CURP、DUI_TYPE_US_SSN。此端点支持创建流程所接受的文件类型的一个子集 — 允许可选文件创建的 Custom Flow 目前对照此更窄的列表进行验证。
duiValue	string	是	文件号码，不含格式化字符。最大 320 个字符（可容纳编码或复合标识符；CPF 或 CURP 等标准文件号码要短得多）。

示例

cURL

curl -X POST https://api.idcloud.unico.app/client/v1/process/abc-123/document \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "duiType": "DUI_TYPE_BR_CPF",
    "duiValue": "12345678901"
  }'

Node.js

import fetch from 'node-fetch';

const res = await fetch(
  'https://api.idcloud.unico.app/client/v1/process/abc-123/document',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      duiType: 'DUI_TYPE_BR_CPF',
      duiValue: '12345678901',
    }),
  }
);

const { process: proc } = await res.json();
// proc.id, proc.person.duiType, proc.person.duiValue

响应

200 OK

{
  "process": {
    "id": "abc-123",
    "person": {
      "duiType": "DUI_TYPE_BR_CPF",
      "duiValue": "12345678901"
    }
  }
}

字段	类型	描述
process.id	string	流程标识符。
process.person.duiType	string	在流程上设置的文件类型。
process.person.duiValue	string	在流程上设置的文件值。

400 Bad Request

当请求体格式错误、缺少必填字段或流程状态不允许该操作时返回。

401 Unauthorized

Bearer 令牌缺失、过期或无效。请参阅认证。

404 Not Found

未找到流程。

429 Too Many Requests

已达到速率限制。当您的系统收到 HTTP 429 错误时，您必须实施机制以防止级联故障并避免加重限制。

最佳实践：

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

警告

在未退避的情况下持续请求被限速的端点会延长限制期并严重影响系统的运行吞吐量。在您端正确限制请求可确保更平稳、更具弹性的集成。

有关默认限制、增加请求和其他详细信息，请参阅速率限制。

错误代码

400 Bad Request

代码	消息	描述
3	process id is invalid	流程 ID 无效时。
3	dui_type is required	未提供文件类型时。
3	dui_value is required	未提供文件号码时。
3	dui_value exceeds maximum length	文件号码超过最大字符限制时。
9	process is not awaiting for document	指定的流程不接受文件提交时。
9	process expired	指定的流程已过期时。
9	document already set, cannot be modified	流程已有关联文件时。
9	process already finished	流程已最终完成时。
9	flow does not allow optional document	流程执行的流程要求必须提供文件时。

401 Unauthorized

消息	描述
Jwt header is an invalid JSON	使用的访问令牌包含不正确的字符。
Jwt is expired	使用的访问令牌已过期。

404 Not Found

代码	消息	描述
5	error getting process: rpc error: code = NotFound desc = process not found	未找到流程 ID 时。

429 Too Many Requests

此状态不提供详细的错误代码 — 仅 HTTP 状态码。有关最佳实践，请参阅上方的 429 Too Many Requests 部分。

500 Internal Server Error

代码	消息	描述
99999	Internal failure! Try again later	发生内部错误时。

下一步

• 设置文件后，流程将继续其管道。调用获取流程获取结果，或等待 webhook。