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

通过标识符检索已有流程。根据 API 合约，结果已在流程创建时同步返回——请将此端点用于重新查询、审计和支持场景。

MarkdownChatGPTClaude
警告

在获取流程之前，请查看我们的 webhook 配置和回退策略 — 点击此处。

端点​

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

请求​

请求头
请求头值
AuthorizationBearer <access_token>
路径参数
参数类型必填描述
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
  }
}
流程字段
字段含义
id流程 UUID；用于查询和跟踪该流程的键。
flow所执行旅程的类型（例如 id_r2、idlivetrust_r2、idtrust_r2 等）。
callbackUri流程结束时客户端应用被重定向到的回调 URI。
userRedirectUrl用户打开以执行旅程的 CbU 页面的完整 URL（携带 id 和行为标志）。
state流程生命周期状态。取值为 PROCESS_STATE_*（例如 CREATED、FAILED、FINISHED、AWAITING_FOR_DOCUMENT、UNSPECIFIED）。
result评估的最终判定结果。取值为 PROCESS_RESULT_*（例如 APPROVED、AUTHENTICATED、NOT_APPROVED 等）。仅在 state = PROCESS_STATE_FINISHED 时才具有结论性。
createdAt流程创建时间戳（UTC）。
finishedAt流程完成时间戳（UTC）。
person包含被验证人员数据的子对象。
purpose流程的目的（例如 personAuthentication、人员注册）。
services附加到该流程的其他服务列表；无附加服务时为空。
authenticationInfo.authenticationId该流程生成的身份认证事件的 ID。
capacities所使用的功能/产品。取值为 PROCESS_CAPACITY_*（例如 IDCLOUDONE）。
expiresAt流程/链接过期时间戳（UTC）。
token与该流程关联的会话/访问令牌（可能为空）。
companyData包含拥有该流程的公司/租户数据的子对象。
simulated布尔值；表示这是模拟/沙箱流程（true）还是真实流程（false）。
人员字段
字段含义
duiType唯一身份证明文件的类型。取值为 DUI_TYPE_*（例如 BR_CPF）。
duiValue证件的值（例如 CPF 号码）。
friendlyName该人员的友好名称/昵称（自由文本，不做校验）。
email该人员的电子邮箱；可能为空。
phoneE.164 格式的电话号码（国家代码 + 区域代码 + 号码）。
notifications通知渠道列表。每一项都带有 notificationChannel，取值为 NOTIFICATION_CHANNEL_*（例如 WHATSAPP、SMS、EMAIL）。
phoneCountryCodeAlpha3该电话号码的 ISO alpha-3 国家代码（例如 BRA）；可能为空。
公司数据字段
字段含义
branchId租户分支的标识符；未按分支细分时为空。
countryCode以 ISO alpha-3 表示的公司所在国家（例如 BRA）。
文档类型与 OCR 字段

process.services[].documents[].doc.code 以简短的大写代码返回文档类型。unico.moja.dictionary.br.cnh.v2.Cnh 会变为 CNH。 该代码既不包含国家，也不包含架构版本；版本会单独在 doc.version 中返回。

使用统一架构的文档类型——即字段参考中的 unified_schema——以采集时识别出的类型的大写形式返回：IDCARD、DRIVERLICENSE、PASSPORT 或 VOTERID。 美国护照会保留其变体，而不会统一归为 PASSPORT，因此 POLYCARBONATEPASSPORT、PASSPORTCARD 和 PAPERPASSPORT 等值也会被返回。 例如，unico.moja.dictionary.ar.generic.v1.IdCard 和 unico.moja.dictionary.us.generic.v1.PolycarbonatePassport 会分别返回为 IDCARD 和 POLYCARBONATEPASSPORT。

专用架构

使用自有字段架构的文档类型——即字段参考中 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 为空
PASSAPORTE 与 PASAPORTE 是不同的文档

巴西护照为 PASSAPORTE（双 S），墨西哥护照为 PASAPORTE（单 S），二者分别沿用各自字典中的拼写。这不是笔误——请勿将这两个值视为等同。

当 doc.code 为 UNKNOWN 时，不会执行 OCR 提取，doc.data 中也不会返回任何字段。

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

整体响应结构保持不变——单一结果为默认方式。

巴西的集成可能会收到下方完整的流程对象，其中 authenticationInfo 包含按功能划分的结果。

{
  "process": {
    "id": "53060f52-f146-4c12-a234-5bb5031f6f5b",
    "flow": "idchecktrust",
    "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": "smart_revalidation",
    "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_INCONCLUSIVE",
      "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": "BR"
    },
    "bioTokenData": {
      "referenceProcessId": "ref-proc-123",
      "authenticationId": "auth-ref-123"
    },
    "services": [
      {
        "envelopeId": "4d4f3d90-04a3-4259-b63b-930ab10d2e47",
        "documentIds": ["doc-abc-123"],
        "consent_granted": true,
        "documents": [
          {
            "doc_id": "doc-abc-123",
            "typified": true,
            "cpf_match": true,
            "face_match": true,
            "validate_doc": true,
            "reused_doc": false,
            "signed_url": "https://example.com/doc?token=xyz",
            "doc": {
              "version": 1,
              "code": "CNH",
              "data": {
                "numero": "044589731564",
                "cpfNumero": "12345678909",
                "nomeCivil": "Luke Skywalker",
                "dataNascimento": "1990-05-12T00:00:00Z",
                "dataExpiracao": "2027-12-07T00:00:00Z",
                "categoria": "B"
              }
            }
          }
        ]
      }
    ]
  }
}
顶级字段
字段类型描述
process.idstring (UUID)流程标识符。
process.flowstring创建时发送的流程标识符。
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流程中配置的目的。
process.clientReferencestring可选的客户端引用，用于在门户中进行索引。
process.useCasestring与流程关联的场景标识符。
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-2 国家代码。
process.bioTokenDataobject参考流程信息 — 仅在 1:1 验证和智能重新验证流程中出现。
process.servicesarray签名信封、采集的文档和其他服务输出。参见下方。
process.state 值
值含义
PROCESS_STATE_CREATED流程已创建；用户尚未完成旅程。
AWAITING_FOR_DOCUMENT创建的流程没有身份证明文件；正在等待通过设置流程文档进行设置。仅在 Custom Flow 允许可选文档时出现。
PROCESS_STATE_FINISHED旅程已完成。检查 result 和 authenticationInfo。
PROCESS_STATE_FAILED处理错误。
状态命名不一致

AWAITING_FOR_DOCUMENT 不遵循其他状态使用的 PROCESS_STATE_* 前缀约定。这是当前 API 中已知的命名不一致问题。

process.result 值
值含义
PROCESS_RESULT_OK所有功能返回了正面结果。
PROCESS_RESULT_INVALID_IDENTITY至少一个功能返回了明确的否定结果（例如活体检测失败、身份不匹配）。
PROCESS_RESULT_ERROR结果处理过程中出错。
PROCESS_RESULT_EXPIRED旅程完成前流程已过期。
PROCESS_RESULT_UNSPECIFIED流程尚未完成。
authenticationInfo 中的功能结果

无论流程如何，所有字段始终返回。流程中未使用的功能的字段返回 *_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（集成错误）。
process.services 字段
services 中的混合命名规范

services 数组对信封级字段（envelopeId、documentIds）使用驼峰命名法，对文档级字段（doc_id、consent_granted、face_match 等）使用下划线命名法。这反映了实际的 API 响应——两种命名规范均为有意为之，并非文档错误。

字段类型描述
envelopeIdstring (UUID)签名信封标识符。
documentIdsarray of strings此服务中采集的文档 ID。
consent_grantedboolean用户是否同意数据共享。
documentsarray包含 OCR 数据和验证结果的采集文档。
documents[].doc_idstring文档标识符。
documents[].typifiedboolean文档类型是否成功识别。
documents[].cpf_matchboolean文档上的 CPF 是否与提供的 CPF 匹配（仅巴西）。
documents[].face_matchboolean自拍是否与文档上的照片匹配。
documents[].validate_docboolean文档是否通过了真实性验证。
documents[].reused_docboolean此文档是否从先前的流程中重用。
documents[].signed_urlstring用于下载文档 PDF 的预签名 URL（有效期 5 分钟 — 重新获取以续期）。
documents[].doc.versionintegerOCR 架构版本。
documents[].doc.codestring简短的文档类型代码（例如 CNH）。所有取值以及代码的推导方式，请参见文档类型与 OCR 字段。
documents[].doc.dataobject提取的 OCR 字段。内容因文档类型而异——完整目录请参见完整字段参考。doc.data 中的字段名（例如 nomeCivil、dataNascimento）以葡萄牙语返回——这是 OCR 引擎实际输出的值。
Mexico墨西哥的客户可能会收到 RENAPO Verification 块

响应结构保持不变，并新增 idGov 块。

在墨西哥启用了 RENAPO Verification 的集成，会在 authenticationInfo 下额外收到一个 idGov 块，其中包含 RENAPO 为用户 CURP 所持有的记录。它是与身份结果相互独立的答复。

{
  "process": {
    "id": "11111111-2222-3333-4444-555555555555",
    "state": "PROCESS_STATE_FINISHED",
    "result": "PROCESS_RESULT_APPROVED",
    "person": {
      "duiType": "DUI_TYPE_MX_CURP",
      "duiValue": "PUEA880304MDFRJN04"
    },
    "authenticationInfo": {
      "authenticationId": "22222222-3333-4444-5555-666666666666",
      "idGov": {
        "government_valid": true,
        "curp": "PUEA880304MDFRJN04",
        "government_name": "ANA PRUEBA EJEMPLO"
      }
    },
    "companyData": { "countryCode": "MEX" }
  }
}

为简洁起见，省略了其他字段和 idGov 的其余键。有关 idGov 字段的完整表格，请参见 RENAPO Verification。

字段类型描述
authenticationInfo.idGovobjectCURP 对应的 RENAPO 记录。未启用该功能时不存在。RENAPO 未响应时为 {}。仅限墨西哥。参见 RENAPO Verification。

错误代码​

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

轮询 vs webhook​

您可以轮询此端点来检查进度，但建议的模式是订阅 webhook，仅将此端点作为备用方案使用。请参阅Webhook 和事件。

下一步​

最后更新 于