设置流程文件

在未设置身份证明文件的流程中设置该文件（CPF、CURP、SSN 或其他 duiType）。文件一旦设置，即不可更改。

仅适用于自定义流程允许在不提供文件的情况下创建的流程，即处于 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。此端点支持创建流程所接受证件类型的子集——允许可选文件创建的自定义流程目前仅针对此较窄的列表进行验证。
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 token 缺失、已过期或无效。参见身份验证。

404 Not Found

流程未找到。

429 Too Many Requests

已达到速率限制。不提供详细错误代码，仅返回 HTTP 状态码。

错误代码

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 状态码。

500 Internal Server Error

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

后续步骤

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