跳转到主要内容

获取流程

警告

在获取流程之前，请查看我们的 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": "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、RG）。
documents[].doc.dataobject提取的 OCR 字段。内容因文档类型和可用数据而异。doc.data 中的字段名（例如 nomeCivil、dataNascimento）以葡萄牙语返回——这是 OCR 引擎实际输出的值。
400 Bad Request

processId 路径参数缺失或格式错误。

401 Unauthorized

Bearer 令牌缺失、过期或无效。

404 Not Found

processId 不存在或不属于已认证的租户。

429 Too Many Requests

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

最佳实践：

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

在未退避的情况下持续请求被限速的端点会延长限制期并严重影响系统的运行吞吐量。在您端正确限制请求可确保更平稳、更具弹性的集成。

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

错误代码​

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

轮询 vs webhook​

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

下一步​

最后更新 于