跳转到主要内容
获取流程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}

请求​

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、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该 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

使用统一模式（字段参考中的 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。

process.services[].documents[].doc.code 将证件类型报告为一个简短的大写代码。unico.moja.dictionary.br.cnh.v2.Cnh 会变为 CNH。 该代码既不包含国家信息，也不包含模式版本；版本会在 doc.version 中单独返回。

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 为空
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": "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"
              }
            }
          }
        ]
      }
    ]
  }
}
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-2 国家代码。
process.​bioTokenDataobject参照流程信息——仅存在于 1:1 验证和智能重新验证流程中。
process.servicesarray已签名的 envelope、已采集的证件以及其他服务输出。见下文。
process.state values
值含义
PROCESS_STATE_CREATED流程已创建；用户尚未完成旅程。
AWAITING_FOR_DOCUMENT流程创建时未提供身份证件。仅当 Custom Flow 允许可选证件时才会出现。请通过设置流程证件发送证件。
PROCESS_STATE_FINISHED旅程已完成。请查看 result 和 authenticationInfo。
PROCESS_STATE_FAILED处理出错。
状态命名不一致

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

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（集成错误）。
process.services fields
services 中混用的命名约定

services 数组在 envelope 级字段（envelopeId、documentIds）上使用 camelCase，在文档级字段（doc_id、consent_granted、face_match 等）上使用 snake_case。这反映的是实际的 API 响应——两种约定都是有意为之，并非文档错误。

字段类型描述
envelopeIdstring (UUID)已签名 envelope 的标识符。
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 引擎实际产生的值。

错误代码​

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

Polling vs webhook​

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

后续步骤​

最后更新 于