创建流程

这是所有 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。
person.duiValue	string	是	证件号码，不含格式化符号。
person.friendlyName	string	否	旅程界面中显示的用户名称。最多 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）和 Smart Revalidation（idsmart）必填。
references	array	条件必填	用于 1:1 验证和 Smart Revalidation 流程的参考输入，替代 bioTokenId。每项包含 referenceType（REFERENCE_TYPE_IMAGE_BASE64 或 REFERENCE_TYPE_PROCESS_ID）和 referenceContent（base64 编码图像或流程 UUID）。
useCase	string	条件必填	Smart Revalidation 使用场景。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.currency	string	否	向用户显示的货币代码。可接受的值：BRL、MXN、USD。
contextualization.price	number	否	向用户显示的交易金额。
contextualization.locale	object	否	本地化的原因文本。键：ptBr、enUs、esMx——每项包含旅程中显示的 reason 字符串。

示例

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

已达到速率限制。请在响应头中指示的时间间隔后重试。

错误代码

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 值无效时。
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 状态码。

500 Internal Server Error

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

下一步

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