创建流程

这是每个 Web & SDK 集成的入口点。您的后端调用它来创建流程；前端使用返回的令牌来渲染 iFrame、重定向用户或初始化原生 SDK。

有关完整的集成流程，请参阅 Web & SDK 概述。

端点

环境	URL
生产环境	POST https://api.idcloud.unico.app/client/v1/process
沙箱环境	POST https://api.idcloud.uat.unico.app/client/v1/process

请求

请求头

请求头	值
Authorization	Bearer <access_token>（参见认证）
Content-Type	application/json

请求体参数

字段	类型	必填	描述
callbackUri	string	是	旅程结束后用户被重定向到的 URL。原生 SDK 流程中回调在应用内处理时使用 /。
flow	string	是	流程标识符 — 决定运行哪些功能。示例：idunicodocs、idunicosign、idchecktrust、idtoken、idsmart。参见可用流程。
purpose	string	是	业务用途。接受的值：creditprocess、biometryonboarding、carpurchase、ageverification。
person.duiType	enum	是	文件类型。接受的值：DUI_TYPE_BR_CPF、DUI_TYPE_MX_CURP、DUI_TYPE_US_SSN、DUI_TYPE_BR_PASSPORT、DUI_TYPE_AR_PASSPORT、DUI_TYPE_AR_DNI、DUI_TYPE_NG_NIN、DUI_TYPE_CL_RUN、DUI_TYPE_EC_NI、DUI_TYPE_US_PASSPORT、DUI_TYPE_GT_CUI、DUI_TYPE_UY_CI、DUI_TYPE_ZZ_EMAIL、DUI_TYPE_ID_NIK、DUI_TYPE_ZZ_PHONE_NUMBER、DUI_TYPE_US_DRIVER_LICENSE、DUI_TYPE_NG_BVN、DUI_TYPE_MX_RFC_PERSONA_FISICA、DUI_TYPE_CO_NIT、DUI_TYPE_PE_RUC、DUI_TYPE_CA_SIN、DUI_TYPE_DK_CPR、DUI_TYPE_GB_NINO、DUI_TYPE_PL_PESEL、DUI_TYPE_SE_PNR、DUI_TYPE_AT_STNR、DUI_TYPE_FI_HETU。
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	否	您的内部标识符，用于在门户中进行交叉引用（外键）。
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 标签将被去除。

示例

cURL

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": "[email protected]"
    }
  }'

Node.js

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: '[email protected]'
    }
  })
});

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": "[email protected]",
      "notifications": []
    },
    "companyData": {
      "branchId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "countryCode": "BR"
    }
  }
}

字段	类型	描述
process.id	string (UUID)	流程标识符。使用它通过获取流程获取结果。
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 Request

当请求体格式错误、缺少必填字段或 flow 值未知时返回。

401 Unauthorized

Bearer 令牌缺失、过期或无效。请参阅认证。

429 Too Many Requests

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

最佳实践：

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

警告

在未退避的情况下持续请求被限速的端点会延长限制期并严重影响系统的运行吞吐量。在您端正确限制请求可确保更平稳、更具弹性的集成。

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

错误代码

400 Bad Request

代码	消息	描述
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 set	API Key 未正确配置时。

401 Unauthorized

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

429 Too Many Requests

此状态不提供详细的错误代码 — 仅 HTTP 状态码。有关最佳实践，请参阅上方的 429 Too Many Requests 部分。

500 Internal Server Error

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

下一步

• 用户完成旅程后，调用获取流程获取结果，或等待 webhook。