设置流程证件POST

创建一个不带证件的流程，让用户完成采集，然后从你的后端发送证件。此后流程即会完成。

MarkdownChatGPTClaude

生命周期

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

响应中不包含最终结果

请通过获取流程读取最终状态和结果，或等待 webhook。

端点

环境	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>（参见身份验证）
Content-Type	application/json

所用凭据需要具备与调用创建流程相同的权限。

路径参数

参数	类型	是否必填	描述
processId	string (UUID)	是	创建流程返回的流程标识符。

请求体参数

字段	类型	是否必填	描述
duiType	enum	是	证件类型。DUI_TYPE_UNSPECIFIED 会被拒绝。参见下方的 duiType 取值。
duiValue	string	是	证件号码，不带格式。最多 320 个字符。

duiType 值

国家	值	描述
AR	DUI_TYPE_AR_PASSPORT	阿根廷护照
AR	DUI_TYPE_AR_DNI	阿根廷 DNI
AR	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	巴西 CPF
BR	DUI_TYPE_BR_PASSPORT	巴西护照
BR	DUI_TYPE_BR_CNPJ	巴西 CNPJ
CA	DUI_TYPE_CA_SIN	加拿大 SIN
CH	DUI_TYPE_CH_AHV	瑞士 AHV/AVS 号码
CL	DUI_TYPE_CL_RUN	智利 RUN
CL	DUI_TYPE_CL_PASSPORT	智利护照
CL	DUI_TYPE_CL_LICENCIA_CONDUCIR	智利驾驶证（Licencia de Conducir）
CO	DUI_TYPE_CO_NIT	哥伦比亚 NIT
CO	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	丹麦 CPR
EC	DUI_TYPE_EC_NI	厄瓜多尔 NI
ES	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	危地马拉 CUI
ID	DUI_TYPE_ID_NIK	印度尼西亚 NIK
IE	DUI_TYPE_IE_PPSN	爱尔兰个人公共服务号码（PPSN）
IT	DUI_TYPE_IT_CF	意大利税务代码（CF）
LK	DUI_TYPE_LK_NIC	斯里兰卡 NIC
LU	DUI_TYPE_LU_MATRICULE	卢森堡国民身份号码（Matricule）
MX	DUI_TYPE_MX_CURP	墨西哥 CURP
MX	DUI_TYPE_MX_RFC_PERSONA_FISICA	墨西哥 RFC（自然人）
MX	DUI_TYPE_MX_LICENCIA_CONDUCIR	墨西哥驾驶证（Licencia de Conducir）
NG	DUI_TYPE_NG_NIN	尼日利亚 NIN
NG	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	秘鲁 RUC
PE	DUI_TYPE_PE_DNI	秘鲁 DNI
PE	DUI_TYPE_PE_PASSPORT	秘鲁护照
PL	DUI_TYPE_PL_PESEL	波兰 PESEL
PT	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	美国 SSN
US	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	乌拉圭 CI
ZZ	DUI_TYPE_ZZ_EMAIL	电子邮件地址
ZZ	DUI_TYPE_ZZ_PHONE_NUMBER	电话号码

调用被接受的条件

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

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

示例

cURL

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"
  }'

Node.js

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 Request

代码	描述
3	processId 缺失或无效、duiType 未指定，或 duiValue 为空或超过 320 个字符。
9	流程未在等待证件（包括证件已设置的情况）、已过期或已完成，或该 flow 不允许可选证件。

401 Unauthorized

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

403 Forbidden

代码	描述
7	凭据缺少创建流程所需的权限。

404 Not Found

代码	描述
5	流程不存在，或不属于你的公司。

429 Too Many Requests

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

最佳实践：

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

警告

在未应用退避的情况下持续请求受速率限制的端点，可能会延长限制期并严重影响系统的运行吞吐量。在您的一侧正确限流请求可确保更顺畅、更具弹性的集成。

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

500 Internal Server Error

代码	描述
13	无法保存证件。

备注

证件在存储之前会先在身份服务中登记。如果登记失败，调用将返回该失败对应的状态。

后续步骤

• 要读取最终状态和结果，请参见获取流程。
• 要在流程完成时收到通知，请参见 Webhooks and Events。