---
title: 创建流程
description: 创建一个验证流程。返回旅程 URL 和 SDK 令牌，用于将用户交接给 Unico 托管的采集体验。
canonical: https://developer.unico.io/zh-CN/developers/api-reference/post-processes
locale: zh-CN
generated_by: markdown-export
---

- [/zh-CN/](/zh-CN/)
- API 参考
- 创建流程

**本页内容# 创建流程

这是每个 Unico API 集成的入口点。你的后端调用它来创建流程；你的前端使用返回的令牌来渲染 iFrame、重定向用户，或初始化原生 SDK。
完整的集成流程请参见[流程](/zh-CN/developers/start/flows)。
### 端点​

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

Headers
Header值`Authorization``Bearer <access_token>`（参见[身份验证](/zh-CN/developers/start/authentication)）`Content-Type``application/json`
Body parameters
字段要求取决于所使用的 flow某个字段是必填、可选还是不适用，取决于你所集成的 `flow`——在仅凭这张表判断某个字段的要求之前，先到[流程](/zh-CN/developers/start/flows)中查看你所使用的具体配方。
字段类型描述`callbackUri`string旅程结束后用户被重定向到的 URL。对于回调在应用内处理的原生 SDK 流程，使用 `/`。`flow`stringFlow 标识符——决定运行哪些能力。示例：`idunicodocs`、`idunicosign`、`idchecktrust`、`idtoken`、`idsmart`。参见[可用流程](/zh-CN/developers/start/flows)。`purpose`string业务用途。可接受的值：`creditprocess`、`biometryonboarding`、`carpurchase`、`ageverification`。`person.duiType`enum证件类型。参见下方的 [`duiType` 值](#duitype-values)。`person.duiValue`string证件号码，不带格式。`person.friendlyName`string在旅程界面中显示的用户展示名称。最多 50 个字符。`person.phone`string电话号码，格式为国际区号 + 区 域码 + 号码，不含分隔符。通过 SMS 或 WhatsApp 发送通知时为必填项。`person.email`string邮箱地址。对于包含电子签名的流程为必填项。`person.​notifications`array用于发送旅程链接的通知渠道。每个条目都带有 `notificationChannel`：`NOTIFICATION_CHANNEL_WHATSAPP`、`NOTIFICATION_CHANNEL_SMS` 或 `NOTIFICATION_CHANNEL_EMAIL`。`references`array1:1 验证和智能重新验证流程的参照输入。每个条目包含 `referenceType`（`REFERENCE_TYPE_IMAGE_BASE64` 或 `REFERENCE_TYPE_PROCESS_ID`）和 `referenceContent`（base64 编码的图像或流程 UUID）。最多只能发送一个条目——数组更长会被以 `400` 拒绝，且 `referenceContent` 不能为空。`useCase`string智能重新验证场景。对于 🇧🇷 的 `idsmart`、`idsmart_r2`、`idsmart_tp1` 为必填项。示例：`USE_CASE_LOGIN`、`USE_CASE_FIN_TRANSACTIONS`。`clientReference`string你系统中该用户的唯一标识符。**[多账号](/zh-CN/capabilities/multi-accounts)能力的必填项。** 在你的数据库中唯一，最多 256 个字符，不含空格。`companyBranchId`string (UUID)分支机构 ID。仅当服务账号关联了多个分支机构时才需要。`expiresIn`string流程从创建起的有效期窗口。格式：`"3600s"`。若省略，默认为 7 天。`flowConfig`object按流程覆盖的配置项。`flowConfig.​biometryCapture.​enabledBackCamera`boolean使用设备的后置摄像头。与证件采集或电子签名流程不兼容。`contextualization`object旅程期间向用户展示的交易背景信息，用于解释采集目的。适用于任何地区的客户 — 不限于特定国家。`contextualization.​company_name`string旅程期间展示的公司名称。最多 20 个字符。`contextualization.​currency`string向用户展示的货币代码。可接受的值：`BRL`、`MXN`、`USD`。`contextualization.​price`number向用户展示的交易金额。`contextualization.​locale`object旅程期间展示的本地化文本。键：`ptBr`、`enUs`、`esMx` — 无论客户所在地区如何，这些都是文本仅支持的语言。`contextualization.locale.{ptBr|enUs|esMx}.reason`string旅程期间展示的采集简要原因。最多 50 个字符。`contextualization.locale.{ptBr|enUs|esMx}.title`string旅程期间展示的客户提示标题。最多 100 个字符。必须与 `text` 一起提供。HTML 标签会被剥离。`contextualization.locale.{ptBr|enUs|esMx}.text`string旅程期间展示的客户提示正文。最多 210 个字符。必须与 `title` 一起提供。HTML 标签会被剥离。`imageBase64`string直接发送的自拍照。可接受 SDK 的采集 JWT。`document.purpose`enum证件的用途。固定取值：`DOCUMENT_PURPOSE_ONBOARDING`、`DOCUMENT_PURPOSE_CREDIT_PROCESS`、`DOCUMENT_PURPOSE_CAR_PURCHASE`、`DOCUMENT_PURPOSE_PAY_BY_PAYCHECK`、`DOCUMENT_PURPOSE_FGTS`。仅在 Face Document Match 流程中使用。`document.​files[].​data`bytes新的证件采集，base64 编码。全球可用，不限于巴西。与 `document.documentId` 互斥。`document.documentId`string (UUID)重用同一人此前已采集的证件，而不进行新的采集。与 `document.files[]` 互斥。`expectedResult`object在测试/沙箱环境中模拟某项能力的结果，并将响应标记为 `simulated: true`。参见[模拟结果（Test Mock）](/zh-CN/developers/start/test-mock)。
**`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`电话号码
创建不带证件的流程当 flow 允许可选证件时，你可以省略 `person.duiType` 和 `person.duiValue`。采集完成后，流程会停留在 `AWAITING_FOR_DOCUMENT` 状态，直到你的后端通过[设置流程证件](/zh-CN/developers/api-reference/set-process-document)发送证件。
### 示例​

cURLNode.js```
curl -X POST https://api.idcloud.unico.app/client/v1/process \  -H "Authorization: Bearer $TOKEN" \  -H "Content-Type: application/json" \  -d '{    "flow": "idunicodocs_r2",    "purpose": "biometryonboarding",    "clientReference": "pedido-88216",    "callbackUri": "https://your-app.example.com/onboarding/callback",    "person": {      "duiType": "DUI_TYPE_BR_CPF",      "duiValue": "12345678909"    }  }'
```

```
import fetch from 'node-fetch';const res = await fetch('https://api.idcloud.unico.app/client/v1/process', {  method: 'POST',  headers: {    Authorization: `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,    'Content-Type': 'application/json',  },  body: JSON.stringify({    flow: 'idunicodocs_r2',    purpose: 'biometryonboarding',    clientReference: 'pedido-88216',    callbackUri: 'https://your-app.example.com/onboarding/callback',    person: {      duiType: 'DUI_TYPE_BR_CPF',      duiValue: '12345678909',    },  }),});const { process: proc } = await res.json();// proc.userRedirectUrl, proc.token, proc.webAppToken
```

### 响应​

200 OK
```
{  "process": {    "id": "b7c1f0a2-63d4-4f3e-9a17-2c8e5d41b0aa",    "flow": "idunicodocs_r2",    "state": "PROCESS_STATE_CREATED",    "result": "PROCESS_RESULT_UNSPECIFIED",    "purpose": "biometryonboarding",    "clientReference": "pedido-88216",    "person": {      "duiType": "DUI_TYPE_BR_CPF",      "duiValue": "12345678909"    },    "capacities": [      "PROCESS_CAPACITY_IDLIVE",      "PROCESS_CAPACITY_IDUNICO",      "PROCESS_CAPACITY_IDDOCS"    ],    "authenticationInfo": {      "authenticationId": ""    },    "companyData": {      "branchId": "",      "countryCode": "BRA"    },    "callbackUri": "https://your-app.example.com/onboarding/callback",    "userRedirectUrl": "https://cadastro.unico.app/flow?id=b7c1f0a2-63d4-4f3e-9a17-2c8e5d41b0aa",    "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…",    "webAppToken": "eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiZGlyIn0…",    "simulated": false  }}
```

字段类型描述`process.id`string (UUID)流程标识符。使用它通过[  获取流程](/zh-CN/developers/api-reference/get-process)获取结果。`process.state`enum`PROCESS_STATE_CREATED`——流程已创建，旅程尚未开始。`PROCESS_STATE_FAILED`——流程创建失败。`process.result`enum验证结果。仅当 `state = PROCESS_STATE_FINISHED` 时存在——参见[流程](/zh-CN/developers/start/flows)以了解某个 flow 可能返回的结果值。`process.flow`string创建时发送的 Flow 标识符。`process.purpose`string创建时发送的业务用途。`process.callbackUri`string创建时发送的回调 URI。`process.​clientReference`string创建时发送的你方内部标识符。仅在请求中提供时才存在。`process.​companyBranchId`string (UUID)分支机构 ID。仅在请求中提供时才存在。`process.​userRedirectUrl`string用于重定向用户的 URL（Web 重定向和 iFrame 集成）。请勿修改此 URL。`process.token`string用于初始化 **Web SDK iFrame** 的 JWT。`process.webAppToken`string用于初始化**原生 SDK**（Android、iOS、Flutter）的 JWT。`process.createdAt`string (date-time)流程创建时的时间戳。`process.expiresAt`string (date-time)流程过期、无法再完成的时间戳。`process.capacities`array为该流程配置的能力。`process.​authenticationInfo`object该流程的身份验证信息（创建时为空）。`process.person`object创建时发送的 `person` 对象的回显。`process.​companyData.​branchId`string (UUID)与该流程关联的分支机构 ID。`process.​companyData.​countryCode`string与该分支机构关联的国家代码（例如 `BR`、`MX`）。
### 错误代码​

400 Bad Request401 Unauthorized403 Forbidden404 Not Found429 Too Many Requests500 Internal Server Error代码消息描述`3`invalid flow指定的 flow 不存在。`3`invalid person: friendly name exceeds 50 characters.展示名称超过 50 个字符。`3`invalid purpose提供的用途无效。`3`invalid callbackUri: unable to parse callbackUri: parse "": empty url, invalid callbackUri: url:提供的 callbackUri 无效。`3`invalid person: email required for notification channel NOTIFICATION_CHANNEL_EMAIL, invalid email address for notification channel NOTIFICATION_CHANNEL_EMAIL提供的邮箱无效，且已配置邮件通知。`3`invalid person: phone number required for notification channel NOTIFICATION_CHANNEL_WHATSAPP, phone number does not contain 13 chars for notification channel NOTIFICATION_CHANNEL_WHATSAPP提供的电话号码无效，且已配置 SMS 或 WhatsApp 通知。`3`idnsv2/GetPublicID request error: rpc error: code = InvalidArgument desc = invalid dui value提供的标识符（duiValue）无效。`3`invalid expiresIn argument`expiresIn` 的值无效。`3`invalid company_name argument in process contextualization, max length is 20`contextualization.​company_name` 超过 20 个字符。`3`title and text must be provided together in process contexts某个 locale 只提供了 `title` 或 `text` 中的一个。`3`invalid title argument in process contexts, max length is 100某个 locale 的 `title` 超过 100 个字符。`3`invalid text argument in process contexts, max length is 210某个 locale 的 `text` 超过 210 个字符。`3`invalid reason argument in process contexts, max length is 50某个 locale 的 `reason` 超过 50 个字符。`3`The references array must contain at most one element.`references` 中发送了多个条目。`3`The references[].referenceContent field is missing.`referenceContent` 为空。`3`The references[].referenceType field must be IMAGE_BASE64 or PROCESS_ID.`referenceType` 不是受支持的值之一。`3`A reference is required for this flow.该 flow 需要参照，但未发送。请发送带有 `referenceType`（`PROCESS_ID` 或 `IMAGE_BASE64`）的 `references[0]`。`9`The referenceProcessId field is invalid.参照流程不存在或无法被重用。会指出你发送的具体字段——如果你发送的是该字段，则为 `bioTokenId`。`3`INVALID_IMAGE图像不是有效的 base64，或看起来像注入攻击。`3`INVALID_DUI证件号码不符合标准格式或不存在。`3`IMAGE_TOO_LARGE图像超过最大 800 KB 的限制。`3`UNSUPPORTED_IMAGE_FORMAT图像格式不是 PNG、JPEG 或 WebP。`3`MISSING_IMAGE该 flow 需要图像，但未发送。`3`MISSING_NAME该 flow 需要姓名，但未发送。`3`MISSING_DUI该 flow 需要证件号码，但未发送。`3`MISSING_PERSON该 flow 需要 `person` 对象，但未发送。`3`INVALID_REQUEST请求体为空或无法解析。`3`TOKEN_ALREADY_USED采集令牌已被使用过。它是一次性的。`3`TOKEN_EXPIRED采集令牌已过期。它必须在 10 分钟内使用。`3`INVALID_BUNDLE请求不满足安全要求。`3`INVALID_NAME姓名超过了允许的最大长度。`3`INVALID_EMAIL邮箱地址格式错误或太长。`3`INVALID_PHONE电话号码超过 20 个字符。`3`INVALID_DUI_TYPE证件类型不是受支持的值之一。`3`INVALID_CLIENT_REFERENCE`clientReference` 太长，或包含空格或 `#`。`3`INVALID_CONSENT_TYPE`consentType` 不是 `NONE`、`DIRECT` 或 `INDIRECT`。`3`INVALID_USE_CASE`useCase` 无法识别，或太长。`3`INVALID_DEVICE_TRUST_TOKEN设备信任令牌无效或已被使用过。`3`TOO_MANY_REFERENCES`references` 中发送了多个条目。`3`INVALID_REFERENCE_TYPE`referenceType` 不是 `IMAGE_BASE64` 或 `PROCESS_ID`。`3`INVALID_REFERENCE_PROCESS参照流程 ID 不是有效的标识符。`3`REFERENCE_PROCESS_NOT_FOUND被参照的流程不存在。`3`REFERENCE_PROCESS_NOT_READY被参照的流程没有可重用的结果，或已被使用过。`3`REFERENCE_SELFIE_NOT_FOUND被参照的流程没有可供重用的自拍照。`3`INVALID_CAPTURE_TOKEN采集到的图像不是由采集 SDK 生成的有效令牌。`3`INVALID_CAPTURE_SIGNATURE采集令牌的签名验证失败。`3`PRIOR_CAPTURE_NOT_FOUND找不到此请求所依赖的先前采集记录。请重新开始该流程。`3`PRIOR_CAPTURE_IN_PROGRESS先前的采集尚未完成。请稍后重试。`3`PRIOR_CAPTURE_FAILED先前的采集未能完成。请重新开始该流程。`3`INVALID_DOCUMENT证件文件不可读、受密码保护，或格式不受支持。`3`INVALID_AUTH_PROCESS`document.authProcessId` 无效、已过期，或属于另一个人。`3`INVALID_DOCUMENT_PURPOSE`document.purpose` 不是受支持的值之一。`3`PROCESS_REUSE_NOT_ENABLED该 flow 不允许在没有图像的情况下重用先前的流程。请改为发送图像。`9`PROCESS_FAILED流程在创建过程中出现终止性失败。`9`Tenant API key is not configuredAPI 密钥未正确配置。Bearer 令牌缺失、已过期或无效。参见[身份验证](/zh-CN/developers/start/authentication)。消息描述Jwt header is an invalid JSON所用访问令牌包含不正确的字符。Jwt is expired所用访问令牌已过期。代码消息描述`7`INVALID_API_KEYAPI 密钥无效或缺失。`7`INVALID_AUTH_TOKEN身份验证令牌无效。`7`PERMISSION_DENIED凭据有效，但无权执行此操作。`7`TOKEN_TENANT_MISMATCH采集令牌是为另一个租户签发的。`7`MISSING_ACCESS_TOKEN缺少 authorization header。代码消息描述`5`NO_RESULTS_FOUND请求中引用的证件未找到。已达到速率限制。当您的系统收到 HTTP 429 错误时，必须实施机制以防止级联故障并避免加重限制。
**最佳实践：**

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

警告在未应用退避的情况下持续请求受速率限制的端点，可能会**延长限制期**并严重影响系统的运行吞吐量。在您的一侧正确限流请求可确保更顺畅、更具弹性的集成。
有关默认限制、增加请求及其他详细信息，请参阅[速率限制](/zh-CN/developers/start/rate-limits)。代码消息描述`13`Internal failure! Try again later发生内部错误。
### 后续步骤​

用户完成旅程后，调用[获取流程](/zh-CN/developers/api-reference/get-process)以获取结果，或等待[webhook](/zh-CN/developers/webhooks-and-events)。
要查看所有配方组合及其可能的结果值，请参见[流程](/zh-CN/developers/start/flows)。
要在没有真实生物特征采集的情况下测试结果，请参见[模拟结果（Test Mock）](/zh-CN/developers/start/test-mock)。
最后更新 于 2026年10月8日**