获取流程

警告

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

端点

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

请求

请求头

请求头	值
`Authorization`	`Bearer <access_token>`

路径参数

参数	类型	必填	描述
`processId`	string (UUID)	是	由创建流程返回的流程标识符。

示例

cURL
Node.js

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

import fetch from 'node-fetch';

const res = await fetch(
  `https://api.idcloud.unico.app/client/v1/process/${processId}`,
  { headers: { Authorization: `Bearer ${accessToken}` } }
);
const { process: proc } = await res.json();

响应

200 OK

{
  "process": {
    "id": "53060f52-f146-4c12-a234-5bb5031f6f5b",
    "flow": "idunicosign",
    "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
      },
      "serproResult": {
        "score": 92
      }
    },
    "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.id`	string (UUID)	流程标识符。
`process.flow`	string	创建时发送的流程标识符。
`process.callbackUri`	string	为流程事件配置的回调 URL。
`process.userRedirectUrl`	string	用户完成流程后的跳转 URL。
`process.state`	enum	当前流程状态。见下方值说明。
`process.result`	enum	验证结果。仅在 `state = PROCESS_STATE_FINISHED` 时存在。
`process.createdAt`	string (datetime)	流程创建时的 ISO 8601 时间戳。
`process.finishedAt`	string (datetime)	流程完成时的 ISO 8601 时间戳。仅在 `state = PROCESS_STATE_FINISHED` 时存在。
`process.expiresAt`	string (datetime)	流程过期时的 ISO 8601 时间戳。
`process.purpose`	string	流程中配置的目的。
`process.clientReference`	string	可选的客户端侧引用，用于在门户中建立索引。
`process.useCase`	string	与流程关联的用例标识符。
`process.capacities`	array of strings	本流程中激活的能力列表。
`process.token`	string	用于 SDK 集成的签名 JWT。
`process.person`	object	创建时提供的身份信息。
`process.person.notifications`	array	为流程配置的通知渠道（例如 `email`）。
`process.authenticationInfo`	object	各功能的结果。见下方说明。
`process.companyData`	object	公司和分支机构上下文。
`process.companyData.branchId`	string	分支机构标识符。
`process.companyData.countryCode`	string	ISO 3166-1 alpha-2 国家代码。
`process.bioTokenData`	object	参考流程信息——仅在 1:1 验证和智能重新验证流程中存在。
`process.services`	array	已签名信封、采集文件及其他服务输出。见下方说明。

process.state 值

值	含义
`PROCESS_STATE_CREATED`	流程已创建；用户尚未完成流程。
`AWAITING_FOR_DOCUMENT`	流程已在无身份证件的情况下创建；等待通过设置流程文件进行设置。仅在自定义流程允许可选文件时出现。
`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`
`bioTokenEngineResult`	1: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.score`	Serpro 相似度	`0`–`100`（相似度）；`-1`（该 CPF 无人脸档案）；`-2`（集成错误）。

process.services 字段

字段	类型	描述
`envelopeId`	string (UUID)	已签名信封标识符。
`documentIds`	array of strings	本服务中采集的文件 ID。
`consent_granted`	boolean	用户是否授予数据共享同意。
`documents`	array	包含 OCR 数据和验证结果的采集文件。
`documents[].doc_id`	string	文件标识符。
`documents[].typified`	boolean	文件类型是否已成功识别。
`documents[].cpf_match`	boolean	文件上的 CPF 是否与提供的 CPF 匹配。
`documents[].face_match`	boolean	自拍是否与文件上的照片匹配。
`documents[].validate_doc`	boolean	文件是否通过真实性验证。
`documents[].reused_doc`	boolean	此文件是否来自之前流程的复用。
`documents[].signed_url`	string	用于下载文件 PDF 的预签名 URL（有效期 5 分钟——需重新获取以续期）。
`documents[].doc.version`	integer	OCR 模式版本。
`documents[].doc.code`	string	文件类型代码（例如 `CNH`、`RG`）。
`documents[].doc.data`	object	提取的 OCR 字段。内容因文件类型和可用数据而异。

400 Bad Request

processId 路径参数缺失或格式不正确。

401 Unauthorized

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

404 Not Found

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

429 Too Many Requests

已达到速率限制。

错误代码

400 Bad Request
401 Unauthorized
404 Not Found
429 Too Many Requests
500 Internal Server Error

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

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

代码	消息	描述
`5`	error getting process: rpc error: code = NotFound desc = process not found	当未找到流程 ID 时。

代码	消息	描述
`99999`	Internal failure! Try again later	当发生内部错误时。

轮询与 webhook

您可以轮询此端点检查进度，但推荐的方式是订阅 webhook，仅在备用情况下调用此端点。参见 Webhooks 与事件。

下一步

查看采集的自拍，请参见获取自拍照。
查看证据审计包，请参见获取证据集。

端点​

请求​

示例​

响应​

错误代码​

轮询与 webhook​

下一步​

端点

请求

示例

响应

错误代码

轮询与 webhook

下一步