API 文档

前台 API 接口页面

按日常联调路径整理当前运行时 API 地址、Basic Auth 授权、短信查询、号码市场和购买号码接口。

API Base URL

https://k8sms.com

总数

10 个接口

需登录

6 个

公开

4 个

基础信息

当前运行时 API 地址

页面直接读取当前环境的 API Base URL，和前端实际发请求时使用的地址保持一致。

当前值

https://k8sms.com

开发环境默认回退到 http://localhost:8000。 生产环境请通过 BACKEND_API_URL 注入真实后端地址。

联调约定

前端请求

运行时读取配置，无需重新构建镜像。

认证方式

受保护接口统一使用 Basic Auth。

授权方式

Basic Auth 请求头

登录和注册会把邮箱与密码保存为本地 Basic Auth 凭证，后续受保护接口会自动携带 Authorization 请求头。

Authorization: Basic base64(email:password)
  1. 1先调用 POST /auth/login 或 POST /auth/register 建立登录态。
  2. 2登录成功后，前端保存邮箱与密码，并自动生成 Basic Auth 头。
  3. 3调用短信、号码市场、购买号码等受保护接口时会携带认证信息。
  4. 4修改邮箱或密码后，客户端会同步刷新本地凭证。

接口分组

用户授权

登录与注册接口会写入本地 Basic Auth 凭证，供后续受保护接口复用。

这两个接口本身是公开接口；登录成功后，前端会保存邮箱与密码，并在后续请求中自动附加 Authorization 请求头。

POST公开
/auth/login

用户登录

使用邮箱与密码登录，返回当前用户信息。

关键参数

  • email: 登录邮箱
  • password: 登录密码

简短示例

curl -X POST "$API_BASE_URL/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"******"}'
POST公开
/auth/register

用户注册

使用邮箱与密码创建新账户，邮箱全局唯一。

关键参数

  • email: 注册邮箱
  • password: 登录密码

简短示例

curl -X POST "$API_BASE_URL/auth/register" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"******"}'

接口分组

短信查询

获取短信列表，或按 token 读取最新短信内容。

GET /sms 与 GET /sms/recent 需要 Basic Auth；GET /sms/token 与 GET /sms/{token} 为公开接口。

GET需登录
/sms

分页查询短信

按关键字、国家、项目或号码过滤短信列表，仅返回当前用户可访问的数据。

关键参数

  • keyword: 关键字，可选
  • country_id: 国家 ID，可选
  • project_id: 项目 ID，可选
  • phone_number_id: 号码 ID，可选
  • page / page_size: 分页参数

简短示例

curl -u "[email protected]:******" "$API_BASE_URL/sms?keyword=验证码&country_id=86&page=1&page_size=20"
GET需登录
/sms/recent

最近短信列表

返回最近 N 条短信，常用于仪表盘快速预览。

关键参数

  • limit: 返回条数，默认 10，最大 50

简短示例

curl -u "[email protected]:******" "$API_BASE_URL/sms/recent?limit=4"
GET公开
/sms/token

通过 token 查询最新短信

通过号码 token 获取最新一条短信，返回完整对象结构。

关键参数

  • token: 号码 token

简短示例

curl "$API_BASE_URL/sms/token?token=tk_xxx"
GET公开
/sms/{token}

通过 token 获取短信正文

公开简化路径，仅返回最近 5 分钟内的最新短信正文。

关键参数

  • token: 路径参数

简短示例

curl "$API_BASE_URL/sms/tk_xxx"

接口分组

号码市场

获取指定国家下可购买的项目、库存和价格档位。

市场列表需要登录，只返回前台购买所需字段，不暴露内部匹配规则或排除规则。

GET需登录
/projects/market?country_id=86

获取号码市场

按国家查询可售项目列表，包含业务名称、描述、库存、最低价和价格档位。

关键参数

  • country_id: 国家 ID，必填

响应说明

  • available_count 表示当前可购买库存。
  • price_tiers 中包含 min_days、max_days、price 与对应库存。
  • locked 项目和内部匹配规则不会出现在前台响应中。

简短示例

curl -u "[email protected]:******" "$API_BASE_URL/projects/market?country_id=86"

接口分组

购买号码

购买前可获取号段、预览优惠券折扣，最终提交购买请求。

购买相关接口都需要 Basic Auth；库存不足、余额不足或号码已售出时会返回明确错误。

POST需登录
/numbers/purchase/prefix-options

获取可购买号段

按国家、项目和价格档位返回可购买号段及每个号段的可售库存。

关键参数

  • country_id: 国家 ID，必填
  • project_id: 项目 ID，必填
  • price_tier_ids: 价格档位 ID 列表，可选

响应说明

  • prefix_length 表示号段长度。
  • items 返回 prefix 与 available_count。

简短示例

curl -u "[email protected]:******" -X POST "$API_BASE_URL/numbers/purchase/prefix-options" \
  -H "Content-Type: application/json" \
  -d '{"country_id":86,"project_id":1001,"price_tier_ids":[1]}'
POST需登录
/numbers/purchase/coupon-preview

预览优惠券折扣

根据购买国家、项目、数量、天数、价格档位和优惠码预览应付金额。

关键参数

  • country_id: 国家 ID，必填
  • project_id: 项目 ID，必填
  • quantity: 购买数量，必填
  • days: 购买天数，可选
  • price_tier_ids: 价格档位 ID 列表，可选
  • prefixes: 偏好号段列表，可选
  • coupon_code: 优惠码，必填

响应说明

  • 返回 original_amount、discount_amount、final_amount 等金额字段。

常见错误

  • coupon_not_available: 优惠券不可用或不适用
  • coupon_already_used: 优惠券已被使用

简短示例

curl -u "[email protected]:******" -X POST "$API_BASE_URL/numbers/purchase/coupon-preview" \
  -H "Content-Type: application/json" \
  -d '{"country_id":86,"project_id":1001,"quantity":2,"days":7,"price_tier_ids":[1],"coupon_code":"SAVE10"}'
POST需登录
/numbers/purchase

购买号码

按国家与项目购买可售号码，成功后返回订单编号、分配数量、余额和号码明细。

关键参数

  • country_id: 国家 ID，必填
  • project_id: 项目 ID，必填
  • quantity: 购买数量，必填
  • days: 购买天数，可选
  • group_id: 购买后加入的分组 ID，可选
  • price_tier_ids: 价格档位 ID 列表，可选
  • prefixes: 偏好号段列表，可选
  • coupon_code: 优惠码，可选

响应说明

  • items 返回分配到的号码列表。
  • token_scopes 中包含号码对应项目的短信查询 token。

常见错误

  • phone_number_inventory_insufficient: 库存不足
  • phone_number_project_already_sold: 号码与项目组合已售出
  • user_balance_insufficient: 余额不足

简短示例

curl -u "[email protected]:******" -X POST "$API_BASE_URL/numbers/purchase" \
  -H "Content-Type: application/json" \
  -d '{"country_id":86,"project_id":1001,"quantity":2,"days":7,"group_id":2001,"price_tier_ids":[1],"prefixes":["86138"],"coupon_code":"SAVE10"}'