--- title: 创建流程 description: 创建验证流程。返回旅程 URL 和 SDK 令牌，将用户引导至 Unico 托管的采集体验。 canonical: https://developer.unico.io/zh-CN/dual-api/developers/api-reference/web-sdk/post-process locale: zh-CN generated_by: markdown-export --- - [/zh-CN/](/zh-CN/) - [API 参考](/zh-CN/dual-api/developers/api-reference/) - [Web 与原生](/zh-CN/dual-api/developers/api-reference/web-sdk/) - Create Process **本页内容# 创建流程 这是每个 Web & SDK 集成的入口点。您的后端调用它来创建流程；前端使用返回的令牌来渲染 iFrame、重定向用户或初始化原生 SDK。 有关完整的集成流程，请参阅 [Web & SDK 概述](/zh-CN/dual-api/developers/api-reference/web-sdk/)。 ### 端点​ 环境URL**生产环境**`POST https://api.idcloud.unico.app/client/v1/process`**沙箱环境**`POST https://api.idcloud.uat.unico.app/client/v1/process` ### 请求​ 请求头 请求头值`Authorization``Bearer `（参见[认证](/zh-CN/dual-api/developers/api-reference/authentication)）`Content-Type``application/json` 请求体参数 字段类型必填描述`callbackUri`string是旅程结束后用户被重定向到的 URL。原生 SDK 流程中回调在应用内处理时使用 `/`。`flow`string是流程标识符 — 决定运行哪些功能。示例：`idunicodocs`、`idunicosign`、`idchecktrust`、`idtoken`、`idsmart`。参见[可用流程](/zh-CN/dual-api/capabilities/available-flows)。`purpose`string是业务用途。接受的值：`creditprocess`、`biometryonboarding`、`carpurchase`、`ageverification`。`person.duiType`enum否文件类型。接受的值：`DUI_TYPE_AR_PASSPORT`、`DUI_TYPE_AR_DNI`、`DUI_TYPE_AR_LNC`、`DUI_TYPE_AT_STNR`、`DUI_TYPE_BE_NN`、`DUI_TYPE_BR_CPF`、`DUI_TYPE_BR_PASSPORT`、`DUI_TYPE_BR_CNPJ`、`DUI_TYPE_CA_SIN`、`DUI_TYPE_CH_AHV`、`DUI_TYPE_CL_RUN`、`DUI_TYPE_CL_PASSPORT`、`DUI_TYPE_CL_LICENCIA_CONDUCIR`、`DUI_TYPE_CO_NIT`、`DUI_TYPE_CO_PASSPORT`、`DUI_TYPE_CO_LICENCIA_CONDUCCION`、`DUI_TYPE_CO_CC`、`DUI_TYPE_DE_IDNR`、`DUI_TYPE_DK_CPR`、`DUI_TYPE_EC_NI`、`DUI_TYPE_ES_NIE`、`DUI_TYPE_ES_DNI`、`DUI_TYPE_FI_HETU`、`DUI_TYPE_FR_SPI`、`DUI_TYPE_GB_NINO`、`DUI_TYPE_GT_CUI`、`DUI_TYPE_ID_NIK`、`DUI_TYPE_IE_PPSN`、`DUI_TYPE_IT_CF`、`DUI_TYPE_LU_MATRICULE`、`DUI_TYPE_MX_CURP`、`DUI_TYPE_MX_RFC_PERSONA_FISICA`、`DUI_TYPE_MX_LICENCIA_CONDUCIR`、`DUI_TYPE_NG_NIN`、`DUI_TYPE_NG_BVN`、`DUI_TYPE_NG_BVN_TOKEN`、`DUI_TYPE_NG_NIN_TOKEN`、`DUI_TYPE_NL_BSN`、`DUI_TYPE_NO_FNR`、`DUI_TYPE_PE_RUC`、`DUI_TYPE_PE_DNI`、`DUI_TYPE_PE_PASSPORT`、`DUI_TYPE_PL_PESEL`、`DUI_TYPE_PT_NIF`、`DUI_TYPE_SE_PNR`、`DUI_TYPE_SE_SAMORDNINGSNUMMER`、`DUI_TYPE_TR_TCKN`、`DUI_TYPE_US_SSN`、`DUI_TYPE_US_PASSPORT`、`DUI_TYPE_US_DRIVER_LICENSE`、`DUI_TYPE_US_PASSPORT_CARD`、`DUI_TYPE_US_POLYCARBONATE_PASSPORT`、`DUI_TYPE_US_ID_CARD`、`DUI_TYPE_UY_CI`、`DUI_TYPE_ZZ_EMAIL`、`DUI_TYPE_ZZ_PHONE_NUMBER`。`person.duiValue`string否文件号码，不含格式化字符。`person.friendlyName`string否旅程 UI 中显示的用户显示名称。最大 50 个字符。`person.phone`string否DDI + DDD + 号码格式的电话号码，无分隔符。通过短信或 WhatsApp 发送通知时必填。`person.email`string否电子邮件地址。包含电子签名的流程必填。`person.notifications`array否用于发送旅程链接的通知渠道。每个项目有 `notificationChannel`：`NOTIFICATION_CHANNEL_WHATSAPP`、`NOTIFICATION_CHANNEL_SMS` 或 `NOTIFICATION_CHANNEL_EMAIL`。`bioTokenId`string (UUID)有条件**已弃用。** 请改用 `references`。参考生物识别流程的 ID。1:1 验证流程（`idtoken`、`idtokentrust`、`idtokensign`）和智能重新验证（`idsmart`）必填。`references`array有条件1:1 验证和智能重新验证流程的参考输入，替代 `bioTokenId`。每个项目包含 `referenceType`（`REFERENCE_TYPE_IMAGE_BASE64` 或 `REFERENCE_TYPE_PROCESS_ID`）和 `referenceContent`（base64 编码的图像或流程 UUID）。`useCase`string有条件智能重新验证场景。`idsmart` 必填。示例：`USE_CASE_LOGIN`、`USE_CASE_IDENTITY_REVALIDATION_7_DAYS`、`USE_CASE_FIN_TRANSACTIONS`。`clientReference`string有条件您系统中用户的唯一标识符。**[多账号](/zh-CN/capabilities/multi-accounts)能力必填。**在您的库中唯一，最多 256 个字符，不含空格。`companyBranchId`string (UUID)否分支 ID。仅在服务账户关联了多个分支时必填。`expiresIn`string否从创建起的流程有效期窗口。格式：`"3600s"`。如省略，默认为 7 天。`flow_config`object否每个流程的配置覆盖。`flow_config.biometry_capture.enabled_back_camera`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 标签将被去除。 ### 示例​ cURLNode.js``` curl -X POST https://api.idcloud.unico.app/client/v1/process \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "callbackUri": "https://app.client.com/callback", "flow": "idunicodocs", "purpose": "biometryonboarding", "person": { "duiType": "DUI_TYPE_BR_CPF", "duiValue": "12345678909", "friendlyName": "Luke Skywalker", "phone": "5511912345678", "email": "luke@example.com" } }' ``` ``` 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({ callbackUri: 'https://app.client.com/callback', flow: 'idunicodocs', purpose: 'biometryonboarding', person: { duiType: 'DUI_TYPE_BR_CPF', duiValue: '12345678909', friendlyName: 'Luke Skywalker', phone: '5511912345678', email: 'luke@example.com' } })});const { process: proc } = await res.json();// proc.userRedirectUrl, proc.token, proc.webAppToken ``` ### 响应​ 200 OK ``` { "process": { "id": "53060f52-f146-4c12-a234-5bb5031f6f5b", "state": "PROCESS_STATE_CREATED", "flow": "idunicosign", "purpose": "biometryonboarding", "callbackUri": "https://app.client.com/callback", "clientReference": "your-internal-id-123", "companyBranchId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "userRedirectUrl": "https://cadastro.unico.app/process/53060f52-f146-4c12-a234-5bb5031f6f5b", "token": "eyJhbGciOiJSUzI1NiIs...", "webAppToken": "eyJhbGciOiJSUzI1NiIs...", "createdAt": "2023-10-09T09:15:25.417105Z", "expiresAt": "2023-10-09T16:15:25.417105Z", "capacities": [], "authenticationInfo": {}, "person": { "duiType": "DUI_TYPE_BR_CPF", "duiValue": "12345678909", "friendlyName": "Luke Skywalker", "phone": "5511912345678", "email": "luke@example.com", "notifications": [] }, "companyData": { "branchId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "countryCode": "BR" } }} ``` 字段类型描述`process.id`string (UUID)流程标识符。使用它通过[获取流程](/zh-CN/dual-api/developers/api-reference/web-sdk/get-process)获取结果。`process.state`enum`PROCESS_STATE_CREATED` — 流程已创建，旅程尚未开始。`PROCESS_STATE_FAILED` — 流程创建失败。`process.flow`string创建时发送的流程标识符。`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 Unauthorized429 Too Many Requests500 Internal Server Error代码消息描述`3`invalid 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配置了短信或 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当某个语言区域中仅提供了 `title` 或 `text` 其中之一时。`3`invalid title argument in process contexts, max length is 100当某个语言区域的 `title` 超过 100 个字符时。`3`invalid text argument in process contexts, max length is 210当某个语言区域的 `text` 超过 210 个字符时。`3`invalid reason argument in process contexts, max length is 50当某个语言区域的 `reason` 超过 50 个字符时。`9`XX ID Apikeys are not setAPI Key 未正确配置时。Bearer 令牌缺失、过期或无效。请参阅[认证](/zh-CN/dual-api/developers/api-reference/authentication)。消息描述Jwt header is an invalid JSON使用的访问令牌包含不正确的字符。Jwt is expired使用的访问令牌已过期。已达到速率限制。当您的系统收到 HTTP 429 错误时，您必须实施机制以防止级联故障并避免加重限制。**最佳实践：** **冷却期（退避）：** 立即停止或限制系统中的后续请求。不要在紧密循环中持续重试失败的请求。 **队列和限流：** 在您端缓冲或排队传出请求，以在重新发送之前控制流量。 **指数退避与抖动：** 重试时，以指数方式增加尝试之间的等待时间（例如 1 秒、2 秒、4 秒、8 秒），并添加小的随机延迟（"抖动"）以防止所有排队请求在完全相同的毫秒重试的"群体效应"。 警告在未退避的情况下持续请求被限速的端点会**延长限制期**并严重影响系统的运行吞吐量。在您端正确限制请求可确保更平稳、更具弹性的集成。有关默认限制、增加请求和其他详细信息，请参阅[速率限制](/zh-CN/dual-api/developers/api-reference/rate-limits)。代码消息描述`99999`Internal failure! Try again later出现内部错误时。 ### 下一步​ 用户完成旅程后，调用[获取流程](/zh-CN/dual-api/developers/api-reference/web-sdk/get-process)获取结果，或等待 [webhook](/zh-CN/developers/webhooks-and-events)。 要查看所有配方组合及其可能的结果值，请参阅[流转](/zh-CN/dual-api/developers/api-reference/web-sdk/flows)。 最后更新 于 2026年10月8日**