接码网关 API

1. 文档说明

1.1 服务概述

本服务提供号码获取与短信验证码接收能力。网关内部聚合多个上游号码资源通道，对调用方呈现为单一 API 入口：调用方无需感知通道差异，由网关依据项目渠道配置、通道优先级与可用状态完成调度，并在主通道不可用时按优先级自动降级至备用通道。

1.2 阅读约定

• 文中 必填 表示该参数缺失将直接返回参数错误；可选 表示可省略并使用默认值。
• 接口路径、字段名、枚举值均区分大小写。
• 示例中的密钥、订单号与号码均为示例值，不可用于实际调用。
• 金额单位为人民币元（CNY），以数值或字符串形式返回。
• 时间字段采用 RFC 3339 格式并携带时区偏移，示例：2026-10-31T11:47:46+08:00。

1.3 路径别名

除本文档列出的 /api/* 路径外，网关同时提供 /v1/* 前缀的等价路径（/v1/number、/v1/code、/v1/release、/v1/black、/v1/orders、/v1/projects、/v1/health），请求参数与响应结构完全一致。

2. 基础约定

2.1 鉴权

除特别说明外，所有接口均需携带 API 密钥，以下三种方式任选其一：

X-API-Key: <your_api_key>
Authorization: Bearer <your_api_key>
# 查询参数方式（仅建议临时验证使用）
?key=<your_api_key>

2.2 请求示例

# 取号
curl -X POST https://kaisajm.cc/api/number/get \
  -H "X-API-Key: <your_api_key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: req-20261031-0001" \
  -d '{"game_id": 1000, "country": "86", "timeout": 300}'

# 取码（长轮询）
curl "https://kaisajm.cc/api/code/get?order_id=<order_id>&wait=20" \
  -H "X-API-Key: <your_api_key>"

3. 响应结构与错误码

3.1 统一响应结构

{
  "code": 0,
  "msg": "ok",
  "data": { }
}

3.2 错误码定义

5. 订单对象与状态机

5.1 订单对象字段

5.2 订单状态

状态由 requesting 单向流转至终态，不存在回退。调用方轮询时收到 received、timeout、released、failed 任一状态即可停止；unknown 表示结果未知，应通过订单查询接口核实后再决定后续动作。

6. 接入流程

调用方                      网关                       上游通道
  │                          │                           │
  │── GET /api/games ───────▶│                           │
  │◀──── 项目列表 ───────────│                           │
  │                          │                           │
  │── POST /api/number/get ─▶│── 按优先级选择通道 ──────▶│
  │◀─ order_id + phone ──────│◀──── 号码 ────────────────│
  │                          │                           │
  │── GET /api/code/get ────▶│── 长轮询取码 ────────────▶│
  │   （wait=20，可重复）     │◀──── 验证码 / 无 ─────────│
  │◀─ status=received ───────│                           │
  │                          │                           │
  │── POST /api/order/release│── 号码回收入池 ──────────▶│

1. 调用项目列表接口获取 game_id，并可按需查询价目。
2. 调用号码获取接口创建订单，保存 order_id 与 phone；建议传入 Idempotency-Key。
3. 在业务系统提交号码，随后以长轮询方式调用验证码接口。
4. 收到 received 后取出 code 完成业务校验；号码不可用时调用加黑接口；放弃使用时调用释放接口。
5. 未收到短信的订单在 expire_at 到期后由服务端自动释放。

7. 调用约束

7.1 账户级限制

7.2 请求约定

• 验证码查询应使用长轮询，不得以固定短间隔高频轮询同一订单。
• 同一订单的轮询间隔不应小于 3 秒。
• 不得对同一项目发起高并发批量取号。
• 网关对通道实施分级限速，请求可能因排队产生额外等待，属正常现象。

7.3 重试策略

7.4 密钥管理

• 密钥等同于账户身份，应存放于服务端配置，不得写入客户端代码或公开仓库。
• 密钥泄露应立即更换，停用后其历史订单仍可查询。