---
title: 获取流程
description: 获取验证流程当前的状态和结果。
canonical: https://developer.unico.io/zh-CN/developers/api-reference/get-process
locale: zh-CN
generated_by: markdown-export
---

- [/zh-CN/](/zh-CN/)
- API 参考
- 获取流程

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

警告在获取流程之前，请先了解我们的 webhook 配置和回退策略——[点击这里](/zh-CN/developers/webhooks-and-events/setup)。
### 端点​

环境URL**生产环境**`GET https://api.idcloud.unico.app/client/v1/process/{processId}`**沙箱环境**`GET https://api.idcloud.uat.unico.app/client/v1/process/{processId}`
### 请求​

Headers
Header值`Authorization``Bearer <access_token>`
Path parameters
参数类型是否必填描述`processId`string (UUID)是[创建流程](/zh-CN/developers/api-reference/post-processes)返回的流程标识符。
### 示例​

cURLNode.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": "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`该人的邮箱；可能为空。`phone`E.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
使用统一模式（[字段参考](/zh-CN/assets/files/document-content-fields-0e4663f2ade946e901bbc7523c21f032.json)中的 `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
使用自有字段模式的证件类型——列在[字段参考](/zh-CN/assets/files/document-content-fields-0e4663f2ade946e901bbc7523c21f032.json)的 `specific_document_schemas` 之下——如下表所示。使用字典类型在该文件中查找对应的模式。
国家/地区`doc.code`字典类型证件BR`RG``unico.​moja.​dictionary.​br.​rg.​v2.​Rg`RGBR`CNH``unico.​moja.​dictionary.​br.​cnh.​v2.​Cnh`CNH（驾照）BR`CIN``unico.​moja.​dictionary.​br.​cin.​v1.​Cin`CINBR`PASSAPORTE``unico.​moja.​dictionary.​br.​passaporte.​v1.​Passaporte`护照MX`INE``unico.​moja.​dictionary.​mx.​ine.​v1.​Ine`INE 选民证MX`LPC``unico.​moja.​dictionary.​mx.​lpc.​v1.​Lpc`Licencia para conducir（驾照）MX`PASAPORTE``unico.​moja.​dictionary.​mx.​pasaporte.​v1.​Pasaporte`护照—`UNKNOWN``unico.​moja.  ​dictionary.​other.​unknown.​v1.​Unknown`无法识别类型——`doc.data` 为空
`PASSAPORTE` 和 `PASAPORTE` 是不同的证件巴西护照是 `PASSAPORTE`（双 S），墨西哥护照是 `PASAPORTE`（单 S），两者各自对应其字典中的拼写。这不是拼写错误——不要把这两个值当作等同的。
当 `doc.code` 为 `UNKNOWN` 时，不会执行 OCR 提取，`doc.data` 中也不会报告任何字段。
巴西的客户可能会收到完整的流程负载整体响应结构保持不变——单一结果仍是默认设置。巴西的集成可能会收到下方完整的流程对象，其中 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.id`string (UUID)流程标识符。`process.flow`string创建时发送的 Flow 标识符。`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该 flow 中配置的流程用途。`process.​clientReference`string用于在控制台中索引的、可选的客户端参照。`process.useCase`string与该 flow 关联的场景标识符。`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`stringISO 3166-1 alpha-2 国家代码。`process.​bioTokenData`object参照流程信息——仅存在于 1:1 验证和智能重新验证流程中。`process.services`array已签名的 envelope、已采集的证件以及其他 服务输出。见下文。process.state values值含义`PROCESS_STATE_CREATED`流程已创建；用户尚未完成旅程。`AWAITING_FOR_DOCUMENT`流程创建时未提供身份证件。仅当 Custom Flow 允许可选证件时才会出现。请通过[设置流程证件](/zh-CN/developers/api-reference/set-process-document)发送证件。`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`[活体检测](/zh-CN/capabilities/liveness)`LIVENESS_RESULT_LIVE`、`LIVENESS_RESULT_NOT_LIVE`、`LIVENESS_RESULT_UNSPECIFIED``authenticationResult`[身份验证](/zh-CN/capabilities/identity-verification)`AUTHENTICATION_RESULT_POSITIVE`、`AUTHENTICATION_RESULT_NEGATIVE`、`AUTHENTICATION_RESULT_INCONCLUSIVE`、`AUTHENTICATION_RESULT_UNSPECIFIED``identityFraudstersResult`[欺诈风险分类](/zh-CN/capabilities/fraud-risk-classification)`TRUST_RESULT_YES`、`TRUST_RESULT_INCONCLUSIVE`、`TRUST_RESULT_UNSPECIFIED``bioTokenEngineResult`[1:1 验证](/zh-CN/capabilities/1-1-validation)`BIO_TOKEN_ENGINE_RESULT_POSITIVE`、`BIO_TOKEN_ENGINE_RESULT_NEGATIVE`、`BIO_TOKEN_ENGINE_RESULT_UNSPECIFIED``smartRevalidationResult`[智能重新验证](/zh-CN/capabilities/smart-revalidation)`SMART_REVALIDATION_RESULT_POSITIVE`、`SMART_REVALIDATION_RESULT_NEGATIVE`、`SMART_REVALIDATION_RESULT_UNSPECIFIED``idAgeResult`[年龄验证](/zh-CN/capabilities/age-verification)`ID_AGE_RESULT_POSITIVE`、`ID_AGE_RESULT_NEGATIVE`、`ID_AGE_RESULT_INCONCLUSIVE`、`ID_AGE_RESULT_UNSPECIFIED``scoreEngineResult.​scoreEnabled`[风险评分](/zh-CN/capabilities/risk-score)`SCORE_ENABLED_TRUE`、`SCORE_ENABLED_FALSE`、`SCORE_ENABLED_UNSPECIFIED``scoreEngineResult.​score`[风险评分](/zh-CN/capabilities/risk-score)-100 到 +100 之间的数字。当 `authenticationResult = AUTHENTICATION_RESULT_INCONCLUSIVE` 且已启用风险评分时存在。`serproResult.score`[Serpro 相似度](/zh-CN/capabilities/serpro-similarity-return)`0`–`100`（相似度）；`-1`（该 CPF 没有存档人脸）；`-2`（集成错误）。process.services fields`services` 中混用的命名约定`services` 数组在 envelope 级字段（`envelopeId`、`documentIds`）上使用 camelCase，在文档级字段（`doc_id`、`consent_granted`、`face_match` 等）上使用 snake_case。这反映的是实际的 API 响应——两种约定都是有意为之，并非文档错误。字段类型描述`envelopeId`string (UUID)已签名 envelope 的标识符。`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`integerOCR 模式版本。`documents[].​doc.​code`string简短的证件类型代码（例如 `CNH`）。所有取值以及该代码的推导方式，请参见[证件类型与 OCR 字段](#document-type-values)。`documents[].​doc.​data`object提取出的 OCR 字段。内容因证件类型而异——完整目录请参见[完整字段参考](/zh-CN/assets/files/document-content-fields-0e4663f2ade946e901bbc7523c21f032.json)。`doc.data` 内的字段名（例如 `nomeCivil`、`dataNascimento`）以葡萄牙语返回——这些是 OCR 引擎实际产生的值。
### 错误代码​

400 Bad Request401 Unauthorized404 Not Found429 Too Many Requests500 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。已达到速率限制。当您的系统收到 HTTP 429 错误时，必须实施机制以防止级联故障并避免加重限制。
**最佳实践：**

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

警告在未应用退避的情况下持续请求受速率限制的端点，可能会**延长限制期**并严重影响系统的运行吞吐量。在您的一侧正确限流请求可确保更顺畅、更具弹性的集成。
有关默认限制、增加请求及其他详细 信息，请参阅[速率限制](/zh-CN/developers/start/rate-limits)。代码消息描述`99999`Internal failure! Try again later发生内部错误。
### Polling vs webhook​

你可以对该端点进行轮询以检查进度，但推荐的方式是**订阅 webhook**，仅将此端点用作回退方案。参见[Webhooks and Events](/zh-CN/developers/webhooks-and-events)。
### 后续步骤​

有关采集到的自拍照，请参见[获取自拍照](/zh-CN/developers/api-reference/get-selfie)。
有关证据审计集，请参见[获取证据集](/zh-CN/developers/api-reference/get-evidence-set)。
最后更新 于 2026年10月8日**