创建流程
这是每个 Unico API 集成的入口点。你的后端调用它来创建流程;你的前端使用返回的令牌来渲染 iFrame、重定向用户,或初始化原生 SDK。
完整的集成流程请参见流程。
端点
| 环境 | 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>(参见身份验证) |
Content-Type | application/json |
Body parameters
字段要求取决于所使用的 flow
某个字段是必填、可选还是不适用,取决于你所集成的 flow——在仅凭这张表判断某个字段的要求之前,先到流程中查看你所使用的具体配方。
| 字段 | 类型 | 描述 |
|---|---|---|
callbackUri | string | 旅程结束后用户被重定向到的 URL。对于回调在应用内处理的原生 SDK 流程,使用 /。 |
flow | string | Flow 标识符——决定运行哪些能力。示例:idunicodocs、idunicosign、idchecktrust、idtoken、idsmart。参见可用流程。 |
purpose | string | 业务用途。可接受的值:creditprocess、biometryonboarding、carpurchase、ageverification。 |
person.duiType | enum | 证件类型。参见下方的 duiType 值。 |
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 | array | 1:1 验证和智能重新验证流程的参照输入。每个条目包含 referenceType(REFERENCE_TYPE_IMAGE_BASE64、REFERENCE_TYPE_PROCESS_ID 或 REFERENCE_TYPE_HUMAN_TOKEN)和 referenceContent(base64 编码的图像、流程 UUID 或 humanToken 值)。REFERENCE_TYPE_HUMAN_TOKEN 接收由 Human Token 为同一账户返回的 humanToken。未知的 humanToken,或签发给其他账户的 humanToken,将返回否定的 1:1 验证结果,而非错误。最多只能发送一个条目——数组更长会被以 400 拒绝,且 referenceContent 不能为空。 |
useCase | string | 智能重新验证场景。对于 🇧🇷 的 idsmart、idsmart_r2、idsmart_tp1 为必填项。示例:USE_CASE_LOGIN、USE_CASE_FIN_TRANSACTIONS。 |
clientReference | string | 你系统中该用户的唯一标识符。多账号能力的必填项。 在你的数据库中唯一,最多 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 编码的文件,格式为图片或 PDF,每个文件最大 16 MB。请先发送正面;第一个文件将被视为正面。全球可用,不限于巴西。与 document.documentId 互斥。 |
document.documentId | string (UUID) | 重用同一人此前已采集的证件,而不进行新的采集。与 document.files[] 互斥。 |
expectedResult | object | 在测试/沙箱环境中模拟某项能力的结果,并将响应标记为 simulated: true。参见模拟结果(Test Mock)。 |
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 | 电话号码 |
创建不带证件的流程
当 flow 允许可选证件时,你可以省略 person.duiType 和 person.duiValue。采集完成后,流程会停留在 PROCESS_STATE_AWAITING_FOR_DOCUMENT 状态,直到你的后端通过设置流程证件发送证件。
示例
- cURL
- Node.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) | 流程标识符。使用它通过获取流程获取结果。 |
process.state | enum | PROCESS_STATE_CREATED——流程已创建,旅程尚未开始。PROCESS_STATE_FAILED——流程创建失败。 |
process.result | enum | 验证结果。仅当 state = PROCESS_STATE_FINISHED 时存在——参见流程以了解某个 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 Request
- 401 Unauthorized
- 403 Forbidden
- 404 Not Found
- 429 Too Many Requests
- 500 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, PROCESS_ID, PERSON_ID or HUMAN_TOKEN. | referenceType 不是受支持的值之一。PERSON_ID 是 HUMAN_TOKEN 的内部别名:请发送 HUMAN_TOKEN。 |
3 | A reference is required for this flow. | 该 flow 需要参照,但未发送。请发送带有 referenceType(PROCESS_ID、IMAGE_BASE64 或 HUMAN_TOKEN)的 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 或 HUMAN_TOKEN。 |
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 | 证件所绑定的生物识别流程无效、已过期,或属于另一个人。 |
3 | INVALID_DOCUMENT_PURPOSE | document.purpose 不是受支持的值之一。 |
3 | PROCESS_REUSE_NOT_ENABLED | 该 flow 不允许在没有图像的情况下重用先前的流程。请改为发送图像。 |
9 | PROCESS_FAILED | 流程在创建过程中出现终止性失败。 |
9 | Tenant API key is not configured | API 密钥未正确配置。 |
Bearer 令牌缺失、已过期或无效。参见身份验证。
| 消息 | 描述 |
|---|---|
| Jwt header is an invalid JSON | 所用访问令牌包含不正确的字符。 |
| Jwt is expired | 所用访问令牌已过期。 |
| 代码 | 消息 | 描述 |
|---|---|---|
7 | INVALID_API_KEY | API 密钥无效或缺失。 |
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秒),并添加一个小的随机延迟("抖动"),以防止所有排队请求在完全相同的毫秒重试的羊群效应。
警告
在未应用退避的情况下持续请求受速率限制的端点,可能会延长限制期并严重影响系统的运行吞吐量。在您的一侧正确限流请求可确保更顺畅、更具弹性的集成。
有关默认限制、增加请求及其他详细信息,请参阅速率限制。
| 代码 | 消息 | 描述 |
|---|---|---|
13 | Internal failure! Try again later | 发生内部错误。 |
后续步骤
- 用户完成旅程后,调用获取流程以获取结果,或等待webhook。
- 要查看所有配方组合及其可能的结果值,请参见流程。
- 要在没有真实生物特征采集的情况下测试结果,请参见模拟结果(Test Mock)。