获取流程

警告

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

在 API 合约中，POST /processes/v1 的响应已包含最终结果。此端点用于重新查询——例如，当您需要检索之前保存的流程，或对历史事务进行审计时。 在 API 合约中，POST /processes/v1 的响应即为最终结果。此端点用于重新查询 — 例如，当您需要检查之前持久化的流程或审计先前的交易时。

端点

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

请求

请求头

请求头	值
Authorization	Bearer <access_token>
APIKEY	已配置的 API 密钥。

路径参数

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

示例

cURL

curl -X GET https://api.id.unico.app/processes/v1/$PROCESS_ID \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY"

Node.js

import fetch from 'node-fetch';

const res = await fetch(
  `https://api.id.unico.app/processes/v1/${processId}`,
  {
    headers: {
      Authorization: `Bearer ${accessToken}`,
      APIKEY: apiKey
    }
  }
);
const result = await res.json();

响应

200 OK

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "unicoId": {
    "result": "yes"
  },
  "riskLevel": {
    "result": "inconclusive"
  },
  "idFace": {
    "personId": "a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890",
    "result": "FOUND"
  },
  "identityFraudsters": {
    "result": "inconclusive"
  },
  "government": {
    "serpro": 87
  },
  "liveness": 1
}

响应字段取决于您的 APIKey

以上示例展示了所有可能的功能字段。您的实际响应仅包含在 APIKey 配置中已启用功能的字段——未启用功能的字段将被完全省略。请联系您的 Unico 项目经理以启用或调整功能。

字段	类型	描述
id	string (UUID)	流程标识符。
status	integer	1（处理中）、2（差异）、3（成功完成）、4（已取消）、5（错误）。
unicoId.result	string	yes、no、inconclusive — 参见身份验证。
riskLevel.result	string	not_approved、critical_risk、high_risk、inconclusive — 参见欺诈风险分类。
idFace.result	string	FOUND、NOT_FOUND — 参见 Face Identifier。
idFace.personId	string	人脸的稳定不透明标识符。仅当 idFace.result = FOUND 时存在。
identityFraudsters.result	string	已弃用。 请改用 riskLevel。正在进行集成的客户可在与项目团队协调迁移工作的同时继续使用此字段。
government.serpro	integer	Serpro 相似度分数（0-100、-1、-2）。仅在巴西可用。参见 Serpro 相似度返回。
liveness	integer	1（通过）、2（未通过） — 参见活体检测。
score	integer	概率风险评分。当 unicoId.result = inconclusive 且风险评分编排处于活动状态时出现。正值表示更高的持有人概率；负值表示更高的风险。仅在巴西可用。

400 Bad Request

processId 路径参数缺失或格式错误。请参阅下方错误代码。

403 Forbidden

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

404 Not Found

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

410 Gone

流程存在但结果为错误。仅返回 id 和 status: 5。

429 Too Many Requests

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

最佳实践：

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

警告

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

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

500 Internal Server Error

意外的服务器错误。

何时使用此端点

API 合约同步返回结果，因此大多数集成不需要此端点。在以下情况下使用它：

• 您仅持久化了 processId，需要稍后检索完整结果（审计、支持）。
• 您怀疑原始响应在传输中丢失（平台完成工作后出现网络错误）。
• 您正在构建审查历史流程的后台管理工具。

错误代码

400 Bad Request

代码	消息	描述
20023	O parâmetro processId não foi informado.	缺少流程 ID 参数。
20002	O parâmetro APIKey não foi informado.	请求头中缺少 APIKEY 参数。
20001	O parâmetro authtoken não foi informado.	请求头中缺少集成令牌参数。

404 Not Found

代码	消息	描述
50001	O processo informado não foi encontrado.	该流程在数据库中不存在。

403 Forbidden

代码	消息	描述
30017	User does not have permission to perform this action.	JWT 格式错误或用户无权执行此操作。
10502	O token informado está expirado.	使用的访问令牌已过期。
10501	O token informado é inválido.	认证令牌无效。
10201	O AppKey informado é inválido.	APIKEY 参数未输入或不存在。

410 Gone

流程存在但结果为错误。仅返回 id 和 status: 5。

500 Internal Server Error

代码	消息	描述
99999	Internal failure! Try again later	出现内部错误时。