---
title: 设置流程证件
description: 在采集完成后从你的后端发送用户的身份证件，使流程得以完成。
canonical: https://developer.unico.io/zh-CN/developers/api-reference/set-process-document
locale: zh-CN
generated_by: markdown-export
---

- [/zh-CN/](/zh-CN/)
- API 参考
- 设置流程证件

**本页内容设置流程证件POST创建一个不带证件的流程，让用户完成采集，然后从你的后端发送证件。此后流程即会完成。

### 生命周期​

**你的后端**通过[创建流程](/zh-CN/developers/api-reference/post-processes)创建流程，不传 `person.duiType` 和 `person.duiValue`。该 flow 必须允许可选证件。流程的初始状态为 `PROCESS_STATE_CREATED`。
**用户**进行旅程并完成采集。
**Unico API** 将流程置为 `AWAITING_FOR_DOCUMENT`，在流程等待证件期间，[获取流程](/zh-CN/developers/api-reference/get-process)返回的就是该状态。此时你已经可以读取不依赖 `duiValue` 的能力的部分结果。
**你的后端**调用此端点，在 URL 中传入流程 ID，并在请求体中传入证件。随后 Unico API 完成该流程，流程状态变为 `PROCESS_STATE_FINISHED`。

响应中不包含最终结果请通过[获取流程](/zh-CN/developers/api-reference/get-process)读取最终状态和结果，或等待 [webhook](/zh-CN/developers/webhooks-and-events)。
### 端点​

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

请求头
Header值`Authorization``Bearer <access_token>`（参见[身份验证](/zh-CN/developers/start/authentication)）`Content-Type``application/json`
所用凭据需要具备与调用[创建流程](/zh-CN/developers/api-reference/post-processes)相同的权限。
路径参数
参数类型是否必填描述`processId`string (UUID)是[创建流程](/zh-CN/developers/api-reference/post-processes)返回的  流程标识符。
请求体参数
字段类型是否必填描述`duiType`enum是证件类型。`DUI_TYPE_UNSPECIFIED` 会被拒绝。参见下方的 [`duiType` 取值](#duitype-values)。`duiValue`string是证件号码，不带格式。最多 320 个字符。
**`duiType` 值**国家值描述AR`DUI_TYPE_AR_PASSPORT`阿根廷护照AR`DUI_TYPE_AR_DNI`阿根廷 DNIAR`DUI_TYPE_AR_LNC`阿根廷驾驶证（Licencia Nacional de Conducir）AT`DUI_TYPE_AT_STNR`奥地利税号（STNR）BE`DUI_TYPE_BE_NN`比利时国家号码（NN）BR`DUI_TYPE_BR_CPF`巴西 CPFBR`DUI_TYPE_BR_PASSPORT`巴西护照BR`DUI_TYPE_BR_CNPJ`巴西 CNPJCA`DUI_TYPE_CA_SIN`加拿大 SINCH`DUI_TYPE_CH_AHV`瑞士 AHV/AVS 号码CL`DUI_TYPE_CL_RUN`智利 RUNCL`DUI_TYPE_CL_PASSPORT`智利护照CL`DUI_TYPE_CL_LICENCIA_CONDUCIR`智利驾驶证（Licencia de Conducir）CO`DUI_TYPE_CO_NIT`哥伦比亚 NITCO`DUI_TYPE_CO_PASSPORT`哥伦比亚护照CO`DUI_TYPE_CO_LICENCIA_CONDUCCION`哥伦比亚驾驶证（Licencia de Conducción）CO`DUI_TYPE_CO_CC`哥伦比亚公民身份证（Cédula de Ciudadanía）DE`DUI_TYPE_DE_IDNR`德国税务识别号码（IdNr）DK`DUI_TYPE_DK_CPR`丹麦 CPREC`DUI_TYPE_EC_NI`厄瓜多尔 NIES`DUI_TYPE_ES_NIE`西班牙外国人身份号码（NIE）ES`DUI_TYPE_ES_DNI`西班牙国民身份证（DNI）FI`DUI_TYPE_FI_HETU`芬兰个人身份代码（HETU）FR`DUI_TYPE_FR_SPI`法国税务参考号码（SPI）GB`DUI_TYPE_GB_NINO`英国国民保险号码（NINO）GT`DUI_TYPE_GT_CUI`危地马拉 CUIID`DUI_TYPE_ID_NIK`印度尼西亚 NIKIE`DUI_TYPE_IE_PPSN`爱尔兰个人公共服务号码（PPSN）IT`DUI_TYPE_IT_CF`意大利税务代码（CF）LK`DUI_TYPE_LK_NIC`斯里兰卡 NICLU`DUI_TYPE_LU_MATRICULE`卢森堡国民身份号码（Matricule）MX`DUI_TYPE_MX_CURP`墨西哥 CURPMX`DUI_TYPE_MX_RFC_PERSONA_FISICA`墨西哥 RFC（自然人）MX`DUI_TYPE_MX_LICENCIA_CONDUCIR`墨西哥驾驶证（Licencia de Conducir）NG`DUI_TYPE_NG_NIN`尼日利亚 NINNG`DUI_TYPE_NG_BVN`尼日利亚银行验证号码（BVN）NG`DUI_TYPE_NG_BVN_TOKEN`尼日利亚 BVN 令牌（哈希）NG`DUI_TYPE_NG_NIN_TOKEN`尼日利亚 NIN 令牌（哈希）NL`DUI_TYPE_NL_BSN`荷兰公民服务号码（BSN）NO`DUI_TYPE_NO_FNR`挪威国民身份号码（Fødselsnummer）PE`DUI_TYPE_PE_RUC`秘鲁 RUCPE`DUI_TYPE_PE_DNI`秘鲁 DNIPE`DUI_TYPE_PE_PASSPORT`秘鲁护照PL`DUI_TYPE_PL_PESEL`波兰 PESELPT`DUI_TYPE_PT_NIF`葡萄牙税务识别号码（NIF）SE`DUI_TYPE_SE_PNR`瑞典个人号码（PNR）SE`DUI_TYPE_SE_SAMORDNINGSNUMMER`瑞典协调号码（Samordningsnummer）TR`DUI_TYPE_TR_TCKN`土耳其身份证号码（TCKN）US`DUI_TYPE_US_SSN`美国 SSNUS`DUI_TYPE_US_PASSPORT`美国护照US`DUI_TYPE_US_DRIVER_LICENSE`美国驾驶执照US`DUI_TYPE_US_PASSPORT_CARD`美国护照卡US`DUI_TYPE_US_POLYCARBONATE_PASSPORT`美国聚碳酸酯护照US`DUI_TYPE_US_ID_CARD`美国身份证UY`DUI_TYPE_UY_CI`乌拉圭 CIZZ`DUI_TYPE_ZZ_EMAIL`电子邮件地址ZZ`DUI_TYPE_ZZ_PHONE_NUMBER`电话号码
调用被接受的条件

流程处于 `AWAITING_FOR_DOCUMENT` 状态：用户已完成采集。
流程尚未过期。
该 flow 允许可选证件。

证件一经设置便不可更改。第二次调用会失败，因为流程已不再等待证件。
### 示例​

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

```
import fetch from 'node-fetch';const res = await fetch(  `https://api.idcloud.unico.app/client/v1/process/${processId}/document`,  {    method: 'POST',    headers: {      Authorization: `Bearer ${accessToken}`,      'Content-Type': 'application/json',    },    body: JSON.stringify({      duiType: 'DUI_TYPE_BR_CPF',      duiValue: '12345678909',    }),  });const { processId: id, duiType, duiValue } = await res.json();
```

### 响应​

200 OK
```
{  "processId": "3116552c-6a3e-4c1f-9d2b-8f0e7a5b4c21",  "duiType": "DUI_TYPE_BR_CPF",  "duiValue": "12345678909"}
```

字段类型描述`processId`string (UUID)流程标识符。`duiType`enum为该流程登记的证件类型。`duiValue`string为该流程登记的证件号码。
示例中的值均为占位符。
### 错误代码​

400 Bad Request401 Unauthorized403 Forbidden404 Not Found429 Too Many Requests500 Internal Server Error代码描述`3``processId` 缺失或无效、`duiType` 未指定，或 `duiValue` 为空或超过 320 个字符。`9`流程未在等待证件（包括证件已设置的情况）、已过期或已完成，或该 flow 不允许可选证件。代码消息描述—Jwt header is an invalid JSON所用访问令牌包含不正确的字符。—Jwt is expired所用访问令牌已过期。代码描述`7`凭据缺少[创建流程](/zh-CN/developers/api-reference/post-processes)所需的权限。代码描述`5`流程不存在，或不属于你的公司。已达到速率限制。当您的系统收到 HTTP 429 错误时，必须实施机制以防止级联故障并避免加重限制。
**最佳实践：**

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

警告在未应用退避的情况下持续请求受速率限制的端点，可能会**延长限制期**并严重影响系统的运行吞吐量。在您的一侧正确限流请求可确保更顺畅、更具弹性的集成。
有关默认限制、增加请求及其他详细信息，请参阅[速率限制](/zh-CN/developers/start/rate-limits)。代码描述`13`无法保存  证件。
备注证件在存储之前会先在身份服务中登记。如果登记失败，调用将返回该失败对应的状态。
### 后续步骤​

要读取最终状态和结果，请参见[获取流程](/zh-CN/developers/api-reference/get-process)。
要在流程完成时收到通知，请参见 [Webhooks and Events](/zh-CN/developers/webhooks-and-events)。
最后更新 于 2026年10月8日**