API 技术文档

概述与安全声明

本文档为 小P黑名单系统 的公开 API 技术文档，面向开发者和自动化 Agent。

Base URL：https://your-domain.com/api/v1

响应格式：JSON（UTF-8）

当前版本：v1

认证与授权

Bearer Token 认证

需要认证的接口通过 HTTP Header 传递 Token：

Authorization: Bearer xpzc_live_****example

• Token 由超级管理员在后台创建，格式为 xpzc_live_ + 48 位随机字符
• Token 明文仅在创建时展示一次，后续不可查看
• 数据库仅存储 SHA-256 哈希，不存储明文
• Token 支持禁用、吊销、过期时间设置
• 每次认证实时校验关联账号状态（存在、启用、角色合法）

Scope 权限

每个 Token 创建时分配一组 scope，接口声明所需 scope：

匿名接口

标记为"允许匿名"的接口无需 Token。当前仅 POST /api/v1/blacklist/submit 允许匿名投稿。

统一规则

request_id 幂等

• 写接口和扣费接口必须提供 request_id
• 建议使用 UUID v4，仅允许字母、数字、下划线、横线，最长 64 字符
• 重复 request_id 返回 duplicate_request: true，不重复写入或扣费
• 幂等范围：request_id + endpoint_path 全局唯一

P币扣费规则

• 仅当 P币制度启用且查询费用 > 0 时扣费
• 超级管理员免扣费
• 查询无结果仍扣费（查询服务已执行）
• 余额不足时拒绝查询，不扣费
• 价格解析顺序：endpoint 专用价格 → 全局网页价格

审计日志

• 所有 API 调用均记录审计日志，包括成功、失败、拒绝
• 日志记录：Token ID、接口、状态码、耗时、P币消耗、IP
• 不记录明文 Token、完整手机号、身份证号

限流

• 默认每分钟 60 次，每日 1000 次
• 有 Token 时按 Token 限流，无 Token 时按 IP 哈希限流
• 超限返回 HTTP 429

脱敏

• 手机号显示为 138****1234
• 身份证号显示为 110***********1234
• 可通过 mask_sensitive_data 配置控制

错误码

GET /api/v1/token/info implemented

获取当前 Bearer Token 的元信息，包括名称、scope、过期时间和限流使用情况。

curl 示例

curl -H "Authorization: Bearer xpzc_live_****example" \
  https://your-domain.com/api/v1/token/info

成功响应

{
  "success": true,
  "data": {
    "token_id": 1,
    "name": "agent-query-token",
    "scopes": ["blacklist:query", "pcoin:balance:read"],
    "expires_at": "2026-12-31 23:59:59",
    "last_used_at": "2026-06-03 10:00:00",
    "created_at": "2026-06-01 00:00:00",
    "rate_limit": {
      "per_minute": { "limit": 60, "used": 3 },
      "per_day": { "limit": 1000, "used": 42 }
    }
  },
  "business_status": "success"
}

GET /api/v1/pcoin/balance implemented

读取当前 Token 所属账号的 P币余额。

curl 示例

curl -H "Authorization: Bearer xpzc_live_****example" \
  https://your-domain.com/api/v1/pcoin/balance

成功响应

{
  "success": true,
  "data": {
    "admin_id": 5,
    "p_coin_balance": 100
  },
  "business_status": "success"
}

GET /api/v1/pcoin/transactions implemented

分页读取当前 Token 所属账号的 P币流水记录。

curl 示例

curl -H "Authorization: Bearer xpzc_live_****example" \
  "https://your-domain.com/api/v1/pcoin/transactions?page=1"

成功响应

{
  "success": true,
  "data": [
    {
      "id": 10,
      "type": "blacklist_query",
      "amount": -5,
      "balance_before": 105,
      "balance_after": 100,
      "related_type": "blacklist_query",
      "remark": "黑名单查询扣费",
      "created_at": "2026-06-03 12:00:00"
    }
  ],
  "total": 1,
  "page": 1,
  "totalPages": 1,
  "business_status": "success"
}

POST /api/v1/blacklist/query implemented

按关键词查询黑名单。可能触发 P币扣费。

curl 示例

curl -X POST \
  -H "Authorization: Bearer xpzc_live_****example" \
  -H "Content-Type: application/json" \
  -d '{"keyword":"张三","request_id":"agent-docs-example-001"}' \
  https://your-domain.com/api/v1/blacklist/query

成功响应（有结果）

{
  "success": true,
  "data": [
    {
      "name": "张三",
      "phone": "138****1234",
      "id_card": "110***********1234",
      "violation_desc": "逾期不还",
      "created_at": "2026-01-01 00:00:00"
    }
  ],
  "request_id": "agent-docs-example-001",
  "p_coin_deducted": 5,
  "balance_after": 95,
  "p_coin_cost": 5,
  "business_status": "success"
}

成功响应（无结果）

{
  "success": true,
  "data": [],
  "request_id": "agent-docs-example-001",
  "p_coin_deducted": 5,
  "balance_after": 95,
  "p_coin_cost": 5,
  "business_status": "success"
}

余额不足响应

{
  "success": false,
  "message": "P币余额不足，本次查询需要 5 P币，当前余额 2 P币。",
  "insufficient_balance": true,
  "request_id": "agent-docs-example-001",
  "p_coin_cost": 5,
  "balance": 2
}

重复请求响应

{
  "success": true,
  "data": [],
  "request_id": "agent-docs-example-001",
  "duplicate_request": true,
  "business_status": "success"
}

POST /api/v1/blacklist/submit implemented

提交黑名单投稿。允许匿名，不扣费。

curl 示例

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"name":"李四","phone":"13900001111","id_card":"110101199001011234","violation_desc":"损坏车辆","request_id":"agent-docs-example-002"}' \
  https://your-domain.com/api/v1/blacklist/submit

成功响应

{
  "success": true,
  "message": "投稿成功，等待管理员审核",
  "id": 10,
  "request_id": "agent-docs-example-002",
  "business_status": "success"
}

GET /api/v1/blacklist/logs implemented

分页读取当前 Token 所属账号的黑名单查询日志。普通担保人仅可查看自己的日志。

curl 示例

curl -H "Authorization: Bearer xpzc_live_****example" \
  "https://your-domain.com/api/v1/blacklist/logs?page=1"

成功响应

{
  "success": true,
  "data": [
    {
      "request_id": "agent-docs-example-001",
      "query_type": "search",
      "result_count": 1,
      "status": "success",
      "p_coin_cost": 5,
      "p_coin_deducted": 5,
      "balance_before": 100,
      "balance_after": 95,
      "source": "api",
      "created_at": "2026-06-03 12:00:00"
    }
  ],
  "total": 1,
  "page": 1,
  "totalPages": 1,
  "business_status": "success"
}

Phase 2 建议接口 proposed

以下接口尚未实现，仅为后续版本规划。具体参数和行为可能在实现时调整。

担保人登录

客户登录

订单列表

订单详情

订单状态修改

客户资料读取

Machine-Readable Schema

以下 JSON 可被自动化工具和 Agent 直接解析。不包含真实凭据。

loading...