API Reference 概览

从零到获取第一个 humanToken 所需的一切。

Markdown

Human Token 有三个端点。本页展示了它们如何协同工作，以便您可以立即开始集成。

基础 URL

环境	基础 URL
生产环境	https://humantoken.unico.app

所有请求都需要 x-unico-accesskey 请求头。请参阅身份验证来生成您的密钥。

---

快速入门流程

---

步骤 1 — 身份验证

在 Human Dashboard 或通过 Authentication API 生成您的 x-unico-accesskey。下面的每个请求都使用此密钥。

x-unico-accesskey: uip_ak.prod.a1b2c3d4.e5f6g7h8.i9j0k1l2

---

步骤 2 — 创建流程

调用 Create Process 开始验证。选择以下两种模式之一：

模式	流程	工作方式
API Only	api+humantoken, api+liveness+humantoken, api+liveness+humantoken+revalidation	您的后端将自拍照作为 imageBase64 发送。humanToken 在同一响应中返回。
Human Token Journey	humantoken, humantoken+revalidation	用户在 Unico 平台上完成采集。您获得 token 和 link 来展示 journey，然后通过 Get Process 获取结果。

API Only 示例：

curl -X POST https://humantoken.unico.app/client/v1/process \
  -H "x-unico-accesskey: $UNICO_ACCESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "flow": "api+humantoken",
    "imageBase64": "<base64-encoded-selfie>",
    "companyBranchId": "<your-branch-id>"
  }'

Human Token Journey 示例：

curl -X POST https://humantoken.unico.app/client/v1/process \
  -H "x-unico-accesskey: $UNICO_ACCESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "flow": "humantoken",
    "callbackUri": "https://yourapp.com/callback",
    "companyBranchId": "<your-branch-id>"
  }'

有关所有流程、参数和响应详情，请参阅 Create Process。

---

步骤 3 — 向用户展示 journey（仅限 Journey 流程）

对于 humantoken 和 humantoken+revalidation 流程，Create Process 响应包括：

• token — 初始化 Web SDK 或原生集成
• link — 重定向用户的 URL

选择适合您平台的集成方式：

平台	方法
Web — SDK	使用 idpay-b2b-sdk 内联嵌入 journey → Web Integration
Web — Redirect	将用户重定向到 link → Web Integration
Android	Custom Tabs → Android
iOS	ASWebAuthenticationSession → iOS
Ionic	Capacitor plugin → Ionic
React Native	Native module → React Native
Flutter	Platform Channels → Flutter

当 journey 结束时，用户返回到您的 callbackUri。继续执行步骤 4。

API Only 流程

跳过此步骤 — 结果已在 Create Process 响应中。

---

步骤 4 — 获取结果（仅限 Journey 流程）

使用流程 id 调用 Get Process 获取结果：

curl https://humantoken.unico.app/client/v1/process/$PROCESS_ID \
  -H "x-unico-accesskey: $UNICO_ACCESS_KEY"

响应包含 data.humanToken.value（标准流程）或 data.humanTokenMatch（重新验证流程）。有关完整响应模式和状态值，请参阅 Get Process。

---

步骤 5 — 使用 humanToken

humanToken 是一个稳定的不透明标识符（最多 100 个字符）。同一人始终解析为相同的值。

const { humanToken } = process.data;

if (!humanToken?.value) {
  // Inconclusive — retry or reject per your business rules
  return;
}

const existing = await db.persons.findByHumanToken(humanToken.value);

if (existing) {
  // Same person seen before — returning user or duplicate
} else {
  // First time — create a new record
  await db.persons.create({ humanToken: humanToken.value });
}

警告

在存储或匹配之前，请务必检查 data.humanToken.value 是否为空。

---

步骤 6 — 获取自拍照（可选）

调用 Get Selfie 下载采集的图像。自拍照在流程结束后 24 小时内可用 — 之后将被永久删除。

curl https://humantoken.unico.app/client/v1/process/$PROCESS_ID/selfie \
  -H "x-unico-accesskey: $UNICO_ACCESS_KEY"

有关响应详情和错误代码，请参阅 Get Selfie。

---

端点概览

方法	端点	描述
POST	/client/v1/process	Create Process — 开始验证
GET	/client/v1/process/{processId}	Get Process — 获取结果
GET	/client/v1/process/{processId}/selfie	Get Selfie — 下载自拍照（24 小时）

下一步

• Create Process — 五种流程的完整参数参考
• Authentication — 生成和管理您的访问密钥
• Build With LLM — 将提示粘贴到您的 AI 助手中以生成完整集成