# 智配系统对外接口说明

本文说明如何用账号密钥调用智配系统的 `/api/agent/*` 接口，完成文件解析与数据整理。只需中文这一份。

接口根地址：`https://zhipeiai.com/api/agent/*`。下文路径均相对于站点根 `https://zhipeiai.com`。

## 第一次怎么调用

请先到 `/console` 创建密钥。完整密钥只显示一次，之后只见后四位。下面示例一律用占位符 `zp_你的密钥`，不要把真实密钥写进文档、仓库或聊天。

**必须在自己的服务端发起调用。** 本接口不对第三方网页 Origin 返回跨域（CORS）头，浏览器前端直接 `fetch` 会失败。

### 准备

```bash
export ZP_KEY='zp_你的密钥'
export BASE='https://zhipeiai.com'
```

密钥只能放在 `Authorization` 头里，不要写进网址、查询参数、Cookie、日志或代码仓库。

### 1. 验密钥并查余额（不扣点）

```bash
curl -sS -H "Authorization: Bearer $ZP_KEY" "$BASE/api/agent/balance"
```

`points > 0` 再继续。不带密钥会得到 `401`。

### 2. 上传文件识别（异步，消耗点数）

```bash
curl -sS -X POST "$BASE/api/agent/upload" \
  -H "Authorization: Bearer $ZP_KEY" \
  -H "Idempotency-Key: $(python3 -c 'import uuid;print(uuid.uuid4())')" \
  -F "file=@你的文件.pdf;type=application/pdf"
```

只返回任务号，不会直接给识别结果。请把同一把 `Idempotency-Key` 存下来，24 小时内断线重试要用原键，不要换新的。

### 3. 轮询任务（建议每隔 10 秒，不要 1 秒一次）

```bash
curl -sS -H "Authorization: Bearer $ZP_KEY" "$BASE/api/agent/tasks/<task_id>"
```

`status`：`pending` → `processing` → `done` / `failed`。`done` 时带 `customer_id`。最长等待建议 10–15 分钟。上传后请用上传接口当时返回的 `task_id` 轮询，不要改用客户列表里的任务号。解析结果以客户详情为准。

### 4. 查看客户详情

```bash
curl -sS -H "Authorization: Bearer $ZP_KEY" "$BASE/api/agent/customers/<customer_id>"
```

详情里的身份证号、手机号会做掩码（前 3 后 4）。完整值不会出现在默认的列表或详情返回中。解析结果请以本接口为准，不要拿列表里的任务号去猜。列表和详情会分别给出 `parse_task_id`（该客户最近一次解析/上传任务）和 `match_task_id`（最近一次匹配任务），没有则为 null，不再返回一个含义不明的单独 `task_id`。

### 5. 发起匹配并查询结果

```bash
curl -sS -X POST "$BASE/api/agent/customers/<customer_id>/match" \
  -H "Authorization: Bearer $ZP_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(python3 -c 'import uuid;print(uuid.uuid4())')" \
  -d '{"loan_category":"信用贷"}'

curl -sS -H "Authorization: Bearer $ZP_KEY" "$BASE/api/agent/customers/<customer_id>/matches"
```

匹配结果只返回命中产品的名称、机构，以及申请所需字段（如产品 id、申请二维码路径 apply_qr）。不返回排除清单，也不返回额度、利率、期限、得分、是否通过、不通过原因、风险点或检查清单。规则原文、判定明细和内部阈值不会出网。

### Python 最小示例

```python
import os, time, uuid, requests

BASE = "https://zhipeiai.com"
KEY = os.environ["ZP_KEY"]  # 只从环境变量读，值为 zp_你的密钥
H = {"Authorization": f"Bearer {KEY}"}

print(requests.get(f"{BASE}/api/agent/balance", headers=H, timeout=20).json())

idem = str(uuid.uuid4())
with open("你的文件.pdf", "rb") as f:
    up = requests.post(
        f"{BASE}/api/agent/upload",
        headers={**H, "Idempotency-Key": idem},
        files={"file": ("你的文件.pdf", f, "application/pdf")},
        timeout=60,
    ).json()
print("任务:", up)

task_id, task = up["task_id"], {}
for _ in range(60):
    task = requests.get(f"{BASE}/api/agent/tasks/{task_id}", headers=H, timeout=20).json()
    if task.get("status") in ("done", "failed"):
        break
    time.sleep(10)
if task.get("status") != "done":
    raise SystemExit(f"识别未成功：{task}")

cid = task["customer_id"]
detail = requests.get(f"{BASE}/api/agent/customers/{cid}", headers=H, timeout=20).json()["data"]
print("客户编号:", detail.get("id"))

requests.post(
    f"{BASE}/api/agent/customers/{cid}/match",
    headers={**H, "Idempotency-Key": str(uuid.uuid4())},
    json={"loan_category": "信用贷"}, timeout=60,
)
res = requests.get(f"{BASE}/api/agent/customers/{cid}/matches", headers=H, timeout=20).json()
for rec in res.get("data") or []:
    for p in rec.get("match_result") or rec.get("matched") or []:
        print(" -", p.get("name"), "|", p.get("institution"))
```

## 1. 获取密钥

1. 在浏览器打开站点，登录你的智配系统账号。
2. 进入「密钥管理」页面（`/console`）。首页和工作台都有入口；未登录会先跳到登录页。
3. 为这把密钥起一个名字（例如「办公自动化」），创建后页面只会**展示一次完整密钥**。请立即复制并存放在只有你能访问的地方。
4. 之后页面只显示后四位。完整密钥无法再从页面取出。泄露后请在同一页吊销，再新建一把。

密钥以 `zp_` 开头，代表的是**你的账号权限**，不是某个助手的独立身份。同一账号可以创建多把具名密钥，一把泄露只吊销一把。

**不要把密钥发到群聊，也不要发给多人可见的对话。** 不要写进可被转发的提示词或公开仓库。

## 2. 调用约定

- 每个请求都必须带请求头：`Authorization: Bearer zp_你的密钥`。
- 密钥只能放在 `Authorization` 头里，**不要放进网址、查询参数或 Cookie**。
- 不要使用网页登录后的令牌来调用 `/api/agent/*`；也不要用密钥去调网页管理接口。
- 建议在消耗型请求（上传识别、跑匹配）加上请求头：`Idempotency-Key: <一把 UUID>`。24 小时内，同一账号重复发送同一把幂等键，会直接返回上次任务，不会重跑，也不会再扣点。
- **`force=true` 仅对消耗型接口（上传识别、发起匹配）会被拒绝。** 查询类接口带上该参数不会因此被拒。请不要用 `force=true` 强迫重跑已成功的识别。
- 接口只接受 JSON 或文件上传，成功时常见字段为 `success`、`data` 或任务状态。
- **必须服务端调用。** 第三方网站的浏览器请求不会得到 CORS 允许。
- **敏感字段须先取得信息主体授权，并做安全存储。** 对外返回的身份证号、手机号已掩码；不要把密钥、证件号或客户资料写入日志、聊天或第三方分析工具。请按最小必要原则使用。

## 3. 能力范围

可以做：

- 上传文件并识别（强制异步）
- 按任务号查询识别进度与结果
- 列出客户摘要、按编号查看详情
- 重命名客户、填写或更新资质
- 发起匹配、查询已有匹配结果
- 查询剩余点数

不可以做：

- 删除客户
- 修改产品或系统配置
- 充值、修改登录密码
- 创建或吊销密钥
- 使用管理备份、下载核心数据等管理能力

管理员账号也可以创建密钥，但这把密钥在本接口里只有普通账号能力，只能操作该账号自己的数据，匹配结果也走同一套对外视图。

## 4. 上传与识别（强制异步）

`POST /api/agent/upload`（请使用 POST；其它方法会返回 405）

- 使用 `multipart/form-data`，字段可以是单个 `file`，或多次 `files`。
- 请求会**立即返回任务号**，不要期望一次请求就拿到完整识别结果。
- 响应示例：`{"success": true, "task_id": "...", "status": "pending"}`
- 若 24 小时内同一批文件已经成功识别并扣过费，将直接返回上次任务结果，不会重新识别，也不会再扣点。重新拍照、重新压缩导致文件字节变化时，会按新文件处理并扣费。

然后轮询：

`GET /api/agent/tasks/<task_id>`

- 建议每隔 **10 秒** 查询一次，不要 1 秒一次。
- 任务状态：`pending`（排队）、`processing`（处理中）、`done`（完成）、`failed`（失败）。
- 上传后请用上传接口当时返回的 `task_id` 轮询，这是标准流程，不要改用客户列表里的任务号。
- 状态为 `done` 时，识别结果在 `result` 里。若轮询的是解析/上传任务，`result` 是征信解析结果；若轮询的是匹配任务（匹配接口返回的任务号），`result` 也是这个字段，但形状不同，主要是命中产品列表 `matched`。不要把两种结果混用。解析结果请再以客户详情为准。
- 状态为 `done` 时，也可用返回的 `customer_id` 再查客户详情。
- 请自行设定最长等待（例如 10–15 分钟）。若超时，请告诉使用者「任务仍在处理，可稍后按任务号再查」，**不要因此换一个新的幂等键重新上传**。
- 若状态为 `failed`，把失败说明转给使用者，并停止空转。

## 5. 客户与资质

- `GET /api/agent/customers`：只返回摘要（编号、姓名、时间、`parse_task_id`、`match_task_id` 及对应状态）。不会在列表里带回整份识别结果，也不会返回证件号或手机号明文。`parse_task_id` 是该客户最近一次解析/上传任务，`match_task_id` 是最近一次匹配任务，没有则为 null。不要拿列表任务号去猜解析结果；解析结果以客户详情为准。列表不再返回含义不明的单独 `task_id`。
- `GET /api/agent/customers/<id>`：按编号查看详情。身份证号、手机号为掩码（前 3 后 4）。详情同样给出 `parse_task_id` / `match_task_id`（及对应状态），不再返回含义不明的单独 `task_id` 或 `task_status`。客户详情和任务轮询里的查询次数同时给出 display（展示口径）和 hard（硬查询）。两者都是结果数字，含义不同，请分别读取。
- `PATCH /api/agent/customers/<id>`：重命名。正文示例：`{"name": "新的名称"}`。后写覆盖先写。
- `GET /api/agent/customers/<id>/qualifications`：读取资质。
- `POST` 或 `PATCH /api/agent/customers/<id>/qualifications`：填写或更新资质。后写覆盖先写。

同一账号若同时挂多个助手，可能互相覆盖姓名或资质，请约定好由谁来写。

## 6. 匹配与余额

- `POST /api/agent/customers/<id>/match`：对已有客户发起匹配（消耗点数）。可带 `Idempotency-Key`。可选正文：`{"loan_category": "信用贷"}` 或 `"抵押贷"`。首次成功与同一把幂等键重放，响应结构相同，命中产品都在 `data` 里。按上传返回的任务号轮询时，解析结果在 `result`；若按匹配任务号查询，`result` 也是结果字段，但内容是匹配结果（命中产品），形状不同，不要混用。
- `GET /api/agent/customers/<id>/matches`：查询该客户已有匹配结果。返回的产品只含名称、机构与申请所需字段，不含排除清单、额度、利率、期限、得分、原因或规则原文。
- `GET /api/agent/balance`：查询剩余点数。点数不足时，消耗型接口会返回 402，并附带充值指引。助手只能把指引转给使用者，**不得自行充值**。

## 7. 限流

仅消耗型操作计入额度：上传识别、发起匹配。

- 每分钟最多 5 次
- 每个自然日最多 50 次

查询客户、查询余额、轮询任务状态不计入。幂等重试（同一把 `Idempotency-Key` 重复提交）不计入。

## 8. 常见错误

| HTTP | 含义 | 建议做法 |
|---|---|---|
| 401 | 密钥无效、缺失、或已被吊销；或把密钥放进了查询参数 | 检查请求头，必要时请使用者到控制台吊销并重建 |
| 402 | 点数不足 | 把返回里的充值指引转给使用者，助手不要自己充值 |
| 403 | 没有这项权限（例如试图删除客户或做管理操作） | 停止该操作并告知超出范围 |
| 400 | 参数错误，或在消耗型接口使用了不支持的 `force=true` | 按返回说明改正，不要强行重试 |
| 404 | 客户或任务不存在 | 核对编号后告知使用者 |
| 405 | 方法不允许（例如用 GET 调用上传接口） | 改用文档中的方法，上传请用 POST |
| 422 | 识别结果不可用（例如文件不清晰） | 告知使用者并停止空转，必要时请其重新拍摄后再传（需新的文件，不要复用已失败任务的幂等键去「强迫成功」） |
| 429 | 消耗型操作达到 5 次/分钟或 50 次/日 | 稍后重试，查询和轮询仍可继续 |
| 503 | 当前解析繁忙 | 稍等再按同一幂等键重试，不要换新键 |

## 9. 安全提醒（请务必转达给密钥持有人）

- 密钥等于账号权限，能够查看和改写该账号下的客户资料。
- 不要把密钥放到网址里，不要写进聊天记录、工单或截图。
- 客户资料属于个人敏感信息，须先取得信息主体授权，按最小必要原则使用，并安全存储。
- 发现泄露：立刻到 `/console` 吊销，再创建一把新的。
