跳转到主要内容
获取流程GET

通过标识符获取一个已存在的流程。根据 API 契约,结果已经在流程创建时同步返回——此端点用于重新查询、审计和支持场景。

Markdown
警告

在获取流程之前,请先了解我们的 webhook 配置和回退策略——点击这里。

端点​

环境URL
生产环境GET https://api.idcloud.unico.app/client/v1/process/{processId}
沙箱环境GET https://api.idcloud.uat.unico.app/client/v1/process/{processId}

请求​

Headers
Header值
AuthorizationBearer <access_token>
Path parameters
参数类型是否必填描述
processIdstring (UUID)是创建流程返回的流程标识符。

示例​

curl -X GET https://api.idcloud.unico.app/client/v1/process/$PROCESS_ID \
-H "Authorization: Bearer $TOKEN"

响应​

200 OK
{
"process": {
"id": "226fd950-4b80-4da6-a476-ba9d397ddc91",
"flow": "id_r2",
"callbackUri": "/",
"userRedirectUrl": "https://cadastro.uat.unico.app/flow?collect-data=true&dynamic-wrapper=true&id=226fd950-4b80-4da6-a476-ba9d397ddc91",
"state": "PROCESS_STATE_FINISHED",
"result": "PROCESS_RESULT_APPROVED",
"createdAt": "2026-08-06T01:42:21.693615Z",
"finishedAt": "2026-08-06T01:43:03.080508Z",
"person": {
"duiType": "DUI_TYPE_BR_CPF",
"duiValue": "40*******50",
"friendlyName": "teste",
"email": "",
"phone": "5511999999999",
"notifications": [
{ "notificationChannel": "NOTIFICATION_CHANNEL_WHATSAPP" }
],
"phoneCountryCodeAlpha3": ""
},
"purpose": "personAuthentication",
"services": [],
"authenticationInfo": { "authenticationId": "55cba227-9828-49df-a16f-bcdaa7bdaa4d" },
"capacities": ["PROCESS_CAPACITY_IDCLOUDONE"],
"expiresAt": "2026-08-13T01:42:21.536500Z",
"token": "",
"companyData": { "branchId": "", "countryCode": "BRA" },
"simulated": false
}
}
Process fields
字段含义
id流程 UUID;用于查询和跟踪该 flow 的键。
flow执行的旅程类型(例如 id_r2、idlivetrust_r2、idtrust_r2 等)。
callbackUri客户端应用在 flow 结束时被重定向到的回调 URI。
userRedirectUrl用户打开以运行旅程的 CbU 页面完整 URL(携带 id 和行为标志)。
state流程生命周期状态(例如 PROCESS_STATE_CREATED、PROCESS_STATE_FAILED、PROCESS_STATE_FINISHED、PROCESS_STATE_AWAITING_FOR_DOCUMENT、PROCESS_STATE_UNSPECIFIED)。
result评估的最终结论。PROCESS_RESULT_* 值(例如 APPROVED、AUTHENTICATED、NOT_APPROVED 等)。仅在 state = PROCESS_STATE_FINISHED 时具有结论性。
createdAt流程创建时间戳(UTC)。
finishedAt流程完成时间戳(UTC)。
person包含被验证人数据的子对象。
purpose该流程的用途(例如 personAuthentication、人员注册)。
services附加到该流程的其他服务列表;无则为空。
authenticationInfo.​authenticationId该 flow 生成的身份验证事件 ID。
capacities使用的能力/产品。PROCESS_CAPACITY_* 值(例如 IDCLOUDONE)。
expiresAt流程/链接过期时间戳(UTC)。
token与该流程关联的会话/访问令牌(可能为空)。
companyData包含拥有该流程的公司/租户数据的子对象。
simulated布尔值;表示这是模拟/沙箱流程(true)还是真实流程(false)。
Person fields
字段含义
duiType唯一身份证件的类型。DUI_TYPE_* 值(例如 BR_CPF)。
duiValue证件的值(例如 CPF 号码)。
friendlyName该人的友好名称/昵称(自由文本,不做校验)。
email该人的邮箱;可能为空。
phoneE.164 格式的电话号码(国家代码 + 区域代码 + 号码)。
notifications通知渠道列表。每个条目携带 notificationChannel,取值为 NOTIFICATION_CHANNEL_*(例如 WHATSAPP、SMS、EMAIL)。
phoneCountryCodeAlpha3电话号码所属国家的 ISO alpha-3 代码(例如 BRA);可能为空。
Company data fields
字段含义
branchId租户分支机构的标识符;未按分支机构分段时为空。
countryCode公司所在国家的 ISO alpha-3 代码(例如 BRA)。
Document types and OCR fields

process.services[].documents[].doc.code 会以两种形式之一报告证件类型。由 Unico 证件模块处理的证件(包括复用的证件)带有简短的大写代码(CNH)。仅通过 API 创建的流程通常带有完整的字典类型(unico.moja.dictionary.br.cnh.v2.Cnh),但也可能带有简短代码。无论采用哪种集成方式,请同时处理这两种形式。 简短代码既不包含国家信息,也不包含模式版本;版本会在 doc.version 中单独返回。

在简短形式中,使用统一模式(字段参考中的 unified_schema)的证件类型,会以采集期间识别出的大写类型标识符返回。最常见的值是 IDCARD、DRIVERLICENSE、PASSPORT 和 VOTERID,但该列表是开放的:采集期间识别出的其他类型会按原样以大写形式返回。请处理此列表之外的值。 美国护照会保留自己的变体,而不会归并为 PASSPORT:还会返回 POLYCARBONATEPASSPORT、PASSPORTCARD、PAPERPASSPORT、CONSULARPASSPORT、ALIENPASSPORT 和 REFUGEEPASSPORT。 例如,unico.moja.dictionary.ar.generic.v1.IdCard 和 unico.moja.dictionary.us.generic.v1.PolycarbonatePassport 会分别报告为 IDCARD 和 POLYCARBONATEPASSPORT。

Specific schemas

使用自有字段模式的证件类型——列在字段参考的 specific_document_schemas 之下——如下表所示。使用字典类型在该文件中查找对应的模式。

国家/地区doc.code字典类型证件
BRRGunico.​moja.​dictionary.​br.​rg.​v2.​RgRG
BRCNHunico.​moja.​dictionary.​br.​cnh.​v2.​CnhCNH(驾照)
BRCINunico.​moja.​dictionary.​br.​cin.​v1.​CinCIN
BRPASSAPORTEunico.​moja.​dictionary.​br.​passaporte.​v1.​Passaporte护照
MXINEunico.​moja.​dictionary.​mx.​ine.​v1.​IneINE 选民证
MXLPCunico.​moja.​dictionary.​mx.​lpc.​v1.​LpcLicencia para conducir(驾照)
MXPASAPORTEunico.​moja.​dictionary.​mx.​pasaporte.​v1.​Pasaporte护照
—UNKNOWNunico.​moja.​dictionary.​other.​unknown.​v1.​Unknown无法识别类型,或为没有专属模式的巴西或墨西哥类型——doc.data 为空

巴西和墨西哥的证件仅使用上述专用模式。任何其他类型的巴西或墨西哥证件(例如墨西哥居民卡)都会报告为 UNKNOWN,而不会使用统一模式。

PASSAPORTE 和 PASAPORTE 是不同的证件

巴西护照是 PASSAPORTE(双 S),墨西哥护照是 PASAPORTE(单 S),两者各自对应其字典中的拼写。这不是拼写错误——不要把这两个值当作等同的。

当 doc.code 为 UNKNOWN 时,不会执行 OCR 提取,doc.data 中也不会报告任何字段。

Brazil巴西的客户可能会收到完整的流程负载

整体响应结构保持不变——单一结果仍是默认设置。

巴西的集成可能会收到下方完整的流程对象,其中 authenticationInfo 中包含各能力的结果。

{
"process": {
"id": "53060f52-f146-4c12-a234-5bb5031f6f5b",
"flow": "iddocs_r2",
"callbackUri": "https://example.com/callback",
"userRedirectUrl": "https://example.com/redirect",
"state": "PROCESS_STATE_FINISHED",
"result": "PROCESS_RESULT_OK",
"createdAt": "2024-01-01T10:00:00Z",
"finishedAt": "2024-01-01T10:15:00Z",
"expiresAt": "2024-01-08T10:00:00Z",
"purpose": "VERIFICATION",
"clientReference": "client-ref-abc",
"useCase": "USE_CASE_LOGIN",
"capacities": ["liveness", "face_match"],
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"person": {
"duiType": "DUI_TYPE_BR_CPF",
"duiValue": "12345678909",
"friendlyName": "Luke Skywalker",
"notifications": [
{
"notificationChannel": "email"
}
]
},
"authenticationInfo": {
"authenticationId": "auth-123",
"livenessResult": "LIVENESS_RESULT_LIVE",
"authenticationResult": "AUTHENTICATION_RESULT_INCONCLUSIVE",
"identityFraudstersResult": "TRUST_RESULT_UNSPECIFIED",
"bioTokenEngineResult": "BIO_TOKEN_ENGINE_RESULT_UNSPECIFIED",
"smartRevalidationResult": "SMART_REVALIDATION_RESULT_UNSPECIFIED",
"idAgeResult": "ID_AGE_RESULT_UNSPECIFIED",
"scoreEngineResult": {
"scoreEnabled": "SCORE_ENABLED_TRUE",
"score": 85.5
}
},
"companyData": {
"branchId": "branch-123",
"countryCode": "BRA"
},
"bioTokenData": {
"referenceProcessId": "ref-proc-123",
"authenticationId": "auth-ref-123"
},
"services": [
{
"consent_granted": true,
"documents": [
{
"doc_id": "doc-abc-123",
"share_id": "share-abc-123",
"typified": true,
"cpf_match": true,
"validate_doc": true,
"face_match": true,
"verified": true,
"reused_doc": false,
"signed_url": "https://example.com/doc?token=xyz",
"doc": {
"version": 2,
"code": "CNH",
"data": {
"numero": "044589731564",
"cpfNumero": "12345678909",
"nomeCivil": "Luke Skywalker",
"dataNascimento": "1990-05-12T00:00:00Z",
"dataExpiracao": "2027-12-07T00:00:00Z",
"categoria": "B"
}
}
}
]
}
]
}
}
Top-level fields
字段类型描述
process.idstring (UUID)流程标识符。
process.flowstring创建时发送的 Flow 标识符。
process.callbackUristring为流程事件配置的回调 URL。
process.​userRedirectUrlstring旅程完成后重定向用户的 URL。
process.stateenum流程当前状态。参见下方的值。
process.resultenum验证结果。仅当 state = PROCESS_STATE_FINISHED 时存在。
process.createdAtstring (datetime)流程创建时的 ISO 8601 时间戳。
process.finishedAtstring (datetime)流程完成时的 ISO 8601 时间戳。仅当 state = PROCESS_STATE_FINISHED 时存在。
process.expiresAtstring (datetime)流程过期时的 ISO 8601 时间戳。
process.purposestring该 flow 中配置的流程用途。
process.​clientReferencestring用于在控制台中索引的、可选的客户端参照。
process.useCasestring与该 flow 关联的场景标识符。
process.capacitiesarray of strings此流程中启用的能力列表。
process.tokenstring用于 SDK 集成的已签名 JWT。
process.personobject创建时提供的身份信息。
process.​person.​notificationsarray为该旅程配置的通知渠道(例如 email)。
process.​authenticationInfoobject各能力的结果。见下文。
process.companyDataobject公司和分支机构上下文。
process.​companyData.​branchIdstring分支机构标识符。
process.​companyData.​countryCodestringISO 3166-1 alpha-3 国家代码(例如 BRA)。
process.​bioTokenDataobject参照流程信息——仅存在于 1:1 验证和智能重新验证流程中。
process.servicesarray已签名的 envelope、已采集的证件以及其他服务输出。见下文。
process.state values
值含义
PROCESS_STATE_CREATED流程已创建;用户尚未完成旅程。
PROCESS_STATE_AWAITING_FOR_DOCUMENT流程创建时未提供身份证件。仅当 Custom Flow 允许可选证件时才会出现。请通过设置流程证件发送证件。
PROCESS_STATE_FINISHED旅程已完成。请查看 result 和 authenticationInfo。
PROCESS_STATE_FAILED处理出错。
process.result values
值含义
PROCESS_RESULT_OK所有能力都返回了积极结果。
PROCESS_RESULT_INVALID_IDENTITY至少有一项能力返回了明确的否定结果(例如活体检测失败、身份不匹配)。
PROCESS_RESULT_ERROR结果处理过程中出错。
PROCESS_RESULT_EXPIRED流程在旅程完成前已过期。
PROCESS_RESULT_UNSPECIFIED流程尚未完成。
Capability results in authenticationInfo

无论 flow 如何,所有字段都会一直返回。该 flow 中未使用的能力,其对应字段会返回 *_UNSPECIFIED。

枚举值的缩写形式

缩写值(例如 livenessResult = LIVE、authenticationResult = INCONCLUSIVE)直接对应本文档记录的完整枚举值(LIVENESS_RESULT_LIVE、AUTHENTICATION_RESULT_INCONCLUSIVE 等)——为简洁起见省略了前缀。

字段能力可能的值
authenticationId—此次身份验证尝试的唯一标识符。
livenessResult活体检测LIVENESS_RESULT_LIVE、LIVENESS_RESULT_NOT_LIVE、LIVENESS_RESULT_UNSPECIFIED
authenticationResult身份验证AUTHENTICATION_RESULT_POSITIVE、AUTHENTICATION_RESULT_NEGATIVE、AUTHENTICATION_RESULT_INCONCLUSIVE、AUTHENTICATION_RESULT_UNSPECIFIED
identityFraudstersResult欺诈风险分类TRUST_RESULT_YES、TRUST_RESULT_INCONCLUSIVE、TRUST_RESULT_UNSPECIFIED
bioTokenEngineResult1:1 验证BIO_TOKEN_ENGINE_RESULT_POSITIVE、BIO_TOKEN_ENGINE_RESULT_NEGATIVE、BIO_TOKEN_ENGINE_RESULT_UNSPECIFIED
smartRevalidationResult智能重新验证SMART_REVALIDATION_RESULT_POSITIVE、SMART_REVALIDATION_RESULT_NEGATIVE、SMART_REVALIDATION_RESULT_UNSPECIFIED
idAgeResult年龄验证ID_AGE_RESULT_POSITIVE、ID_AGE_RESULT_NEGATIVE、ID_AGE_RESULT_INCONCLUSIVE、ID_AGE_RESULT_UNSPECIFIED
scoreEngineResult.​scoreEnabled风险评分SCORE_ENABLED_TRUE、SCORE_ENABLED_FALSE、SCORE_ENABLED_UNSPECIFIED
scoreEngineResult.​score风险评分-100 到 +100 之间的数字。当 authenticationResult = AUTHENTICATION_RESULT_INCONCLUSIVE 且已启用风险评分时存在。
serproResult.scoreSerpro 相似度0–100(相似度);-1(该 CPF 没有存档人脸);-2(集成错误)。
deviceMetadata设备元数据包含 status(found、not_found、unavailable)和设备数据的对象。流程中未启用此能力时不存在此字段。
process.services fields
每个模块一个条目

services 中,流程里每个已完成的模块各对应一个条目:仅包含每个模块最近一次完成的执行,且仅在流程处于 PROCESS_STATE_FINISHED 或 PROCESS_STATE_AWAITING_FOR_DOCUMENT 时返回。仅通过 API 创建的流程在任何状态下都带有其证件条目。证件采集条目包含 documents 和 consent_granted。电子签名条目包含 envelope_id 和 document_ids。条目没有类型字段,且顺序不固定:请根据键而非位置识别每个条目,并忽略无法识别的条目。键均为 snake_case,但 doc.data 中的键遵循证件的模式(例如 nomeCivil)。

字段类型描述
consent_grantedboolean证件采集条目。用户是否同意与贵公司共享证件。
documentsarray证件采集条目。带有 OCR 数据和校验结果的已采集证件。
documents[].doc_idstring证件标识符。
documents[].​share_idstring用户在此流程中授予贵公司的共享的标识符。
documents[].​typifiedboolean是否识别出了证件类型。
documents[].​cpf_matchboolean仅限巴西。证件上的 CPF 是否与创建时发送的 CPF 匹配。对于国家设置为巴西的公司始终存在;其他国家以及未设置国家的公司则省略。
documents[].​validate_docboolean仅限巴西。证件是否通过了 Unico 的证件校验。对于国家设置为巴西的公司始终存在(未执行校验时为 false);其他国家以及未设置国家的公司则省略。
documents[].​face_matchboolean or null自拍照是否与证件上的照片匹配。null 表示未执行该检查——这并不是否定结果。
documents[].​verifiedboolean or null仅当证件类型已知、证件未被删除、face_match 为 true 且证件通过了质量检查时才为 true。其他情况下为 false,包括 face_match 未执行时。当流程未经过证件模块时为 null。
documents[].​reused_docboolean该证件是否是从之前的流程中重用的。
documents[].​signed_urlstring用于下载证件图片的短时效签名 URL。该 URL 会过期:请勿存储,也不要依赖固定的有效期;需要新的 URL 时,请再次调用此端点。
documents[].​doc.​versioninteger证件类型字典的版本(例如 unico.moja.dictionary.br.cnh.v2.Cnh 为 2)。
documents[].​doc.​codestring证件类型:简短代码(例如 CNH)或完整的字典类型(例如 unico.moja.dictionary.br.cnh.v2.Cnh)。由证件模块处理的证件为简短代码。请同时处理这两种形式。所有取值以及该代码的推导方式,请参见证件类型与 OCR 字段。
documents[].​doc.​dataobject提取出的 OCR 字段。内容因证件类型而异——完整目录请参见完整字段参考。字段名遵循证件的模式:巴西证件使用葡萄牙语(例如 nomeCivil、dataNascimento),墨西哥证件使用西班牙语,统一模式使用英语。
envelope_idstring (UUID)电子签名条目。已签名 envelope 的标识符。
document_idsarray of strings电子签名条目。envelope 中证件的 ID。
仅通过 API 创建的流程

在仅通过 API 创建的流程中,证件条目来自 API 调用,而非 Unico 的证件模块,部分取值与上表不同:

  • consent_granted 始终为 false:由贵公司收集同意,Unico 不对其进行跟踪。
  • share_id 和 signed_url 为空。
  • face_match 始终为 true 或 false,绝不会为 null。
  • verified 始终为 null。
  • doc.version 为 0。
  • doc.code 通常带有完整的字典类型(例如 unico.moja.dictionary.br.cnh.v2.Cnh),但也可能带有简短代码。
  • 无法读取 OCR 数据时,doc.data 为 null。

错误代码​

代码消息描述
3process id is invalid流程 ID 无效。

Polling vs webhook​

你可以对该端点进行轮询以检查进度,但推荐的方式是订阅 webhook,仅将此端点用作回退方案。参见Webhooks and Events。

后续步骤​