创建流程

MarkdownChatGPTClaude

这是每个 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）和 referenceContent（base64 编码的图像或流程 UUID）。最多只能发送一个条目——数组更长会被以 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 编码。全球可用，不限于巴西。与 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。采集完成后，流程会停留在 AWAITING_FOR_DOCUMENT 状态，直到你的后端通过设置流程证件发送证件。

示例

cURL

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"
    }
  }'

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({
    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

代码	消息	描述
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 configured	API 密钥未正确配置。

401 Unauthorized

Bearer 令牌缺失、已过期或无效。参见身份验证。

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

403 Forbidden

代码	消息	描述
7	INVALID_API_KEY	API 密钥无效或缺失。
7	INVALID_AUTH_TOKEN	身份验证令牌无效。
7	PERMISSION_DENIED	凭据有效，但无权执行此操作。
7	TOKEN_TENANT_MISMATCH	采集令牌是为另一个租户签发的。
7	MISSING_ACCESS_TOKEN	缺少 authorization header。

404 Not Found

代码	消息	描述
5	NO_RESULTS_FOUND	请求中引用的证件未找到。

429 Too Many Requests

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

最佳实践：

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

警告

在未应用退避的情况下持续请求受速率限制的端点，可能会延长限制期并严重影响系统的运行吞吐量。在您的一侧正确限流请求可确保更顺畅、更具弹性的集成。

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

500 Internal Server Error

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

后续步骤

• 用户完成旅程后，调用获取流程以获取结果，或等待webhook。
• 要查看所有配方组合及其可能的结果值，请参见流程。
• 要在没有真实生物特征采集的情况下测试结果，请参见模拟结果（Test Mock）。