鉴权

两种方式：

JWT（网页 / 后台）：POST /api/sms/auth/login 获取 token，后续请求带 Authorization: Bearer <token>。另有 POST /api/sms/auth/register 注册、GET /api/sms/auth/me 获取当前用户。
API Key（服务端集成，推荐）：在用户后台创建，请求头带 X-API-Key: psk_xxx（Key 以 psk_ 开头）。可为 Key 设置 IP 白名单。

Base URL

https://api.simsmsbox.com

商城查询（取号前置）

下单前必须先查询在售国家、项目与卡型，得到下单所需的 service（项目代码）/ country（国家代码）/ cardKind。注意 service 是 market 返回的 service 代码（如 instagram），不是显示名「Instagram」。

# 在售国家（含国旗 / 中英文名 / 在售项目数）
curl "https://api.simsmsbox.com/api/sms/shop/countries" -H "X-API-Key: psk_xxx"

# 号码类型（卡型字典，如 physical=实卡 / virtual=虚拟卡）
curl "https://api.simsmsbox.com/api/sms/shop/number-types" -H "X-API-Key: psk_xxx"

# 某国家在售项目与各供应商报价（按价格升序，含每个项目的 service 代码与 stock 库存）
curl "https://api.simsmsbox.com/api/sms/shop/market?country=US&cardKind=physical" -H "X-API-Key: psk_xxx"

下单取号

下单走价格优先智能路由，自动在多家上游中选最低价且有货的号码。service 可传商城 market 的 项目代码或显示名（如 instagram 或 Instagram 均可），country 可传代码或名称（US / us / 美国），均忽略大小写；请确认该项目 stock > 0，否则会返回「暂无可用平台」。rentDays 为号码有效期（天，1~30）；实卡在有效期内可重复接收同一应用的验证码，到期后号码自动释放。

# 单张取号（service 用商城返回的项目代码，非显示名）
curl -X POST https://api.simsmsbox.com/api/sms/orders/purchase \
  -H "X-API-Key: psk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"service":"instagram","country":"US","cardKind":"physical","rentDays":30}'

# 批量取号（逐张下单，返回每张结果与成功/失败统计）
curl -X POST https://api.simsmsbox.com/api/sms/orders/purchase-batch \
  -H "X-API-Key: psk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"service":"instagram","country":"US","cardKind":"physical","rentDays":30,"quantity":5}'

下单请求体字段：

service（必填）项目代码或显示名，取自商城 market 的 service/serviceName（如 instagram 或 Instagram），忽略大小写
country（必填）国家代码或名称，取自商城 country（如 US / us / 美国），忽略大小写
cardKind（选填）卡型：physical 实卡 / virtual 虚拟；留空走价格最优
rentDays（选填）有效期天数 1~30，默认 30；期内可重复接收
platformCode（选填）指定供应商；留空走智能路由
includeSegment / operator（选填）号段前缀 / 运营商筛选
quantity（仅 purchase-batch）批量数量，默认 1

查询验证码 / 我的订单

{id} 可填订单数字 id（下单返回的 orderId，如 19）或订单号（展示单号 displayOrderNo，如 S2606…），两者皆可。

# 单个订单（含最新验证码 latestCode、状态、有效期 expireAt）；{id} 可用 orderId 或 displayOrderNo
curl https://api.simsmsbox.com/api/sms/orders/{id} -H "X-API-Key: psk_xxx"

# 我的订单列表（可按 status 过滤）
curl "https://api.simsmsbox.com/api/sms/orders/mine?page=1&pageSize=20" -H "X-API-Key: psk_xxx"

# 我收到的全部短信记录
curl "https://api.simsmsbox.com/api/sms/orders/messages?page=1&pageSize=20" -H "X-API-Key: psk_xxx"

自定义取码地址（对外集成推荐）

下单响应里带有 apiBindingKey。凭此 key 可用一个固定 URL 实时拉取该订单最新短信——对外只暴露我方地址，不泄露上游供应商。该接口无需鉴权头，凭 key 访问。

返回格式（format 参数）：

默认（不传 format）：返回 JSON，含 status（YES=已收到 / NO=未收到）与 data（orderNo/phone/content/codeValue…）。若你在「取码设置」里配置了模板，则按模板渲染。
format=json：强制 JSON。
format=txt：极简文本 状态|整条短信内容——已收到为 YES|整条短信内容，未收到为 NO|。

# 默认 JSON
curl "https://api.simsmsbox.com/api/sms/record?key={apiBindingKey}"

# 极简文本：YES|123456 或 NO|
curl "https://api.simsmsbox.com/api/sms/record?key={apiBindingKey}&format=txt"

# 中转 BaseUrl（用于拼接对外 record 链接，可在系统设置配置）
curl https://api.simsmsbox.com/api/sms/orders/base-url -H "X-API-Key: psk_xxx"

订单操作

POST /api/sms/orders/{id}/cancel 取消（未收码可退款）
POST /api/sms/orders/{id}/renew 续期，请求体 {"days": 7}
POST /api/sms/orders/{id}/rotate 换号
POST /api/sms/orders/{id}/blacklist 拉黑当前号码

# 续期 7 天
curl -X POST https://api.simsmsbox.com/api/sms/orders/{id}/renew \
  -H "X-API-Key: psk_xxx" -H "Content-Type: application/json" \
  -d '{"days":7}'

批量 TOKEN 导出 / 查询

# 导出 TOKEN：返回「号码----中转URL」多行文本（scope: selected/current/renewal/all）
curl -X POST https://api.simsmsbox.com/api/sms/orders/export-tokens \
  -H "X-API-Key: psk_xxx" -H "Content-Type: application/json" \
  -d '{"scope":"all"}'

# 批量按 key 或号码查订单 token（含最新码 / 状态）
curl -X POST https://api.simsmsbox.com/api/sms/orders/query-tokens \
  -H "X-API-Key: psk_xxx" -H "Content-Type: application/json" \
  -d '{"terms":["+1xxxx","psk_orderkey_xxx"]}'

钱包

# 余额（balance / frozenAmount / totalRecharge / totalConsume）
curl https://api.simsmsbox.com/api/sms/wallet/balance -H "X-API-Key: psk_xxx"
# 流水
curl "https://api.simsmsbox.com/api/sms/wallet/txs?page=1&pageSize=20" -H "X-API-Key: psk_xxx"

API Key 管理

需用 JWT（Authorization: Bearer）操作。创建后可在用户后台「API Key」页随时查看 / 复制完整 Key。

# 列表
curl https://api.simsmsbox.com/api/sms/api-keys -H "Authorization: Bearer <token>"
# 创建（返回 { id, key }，之后也可在后台 API Key 页查看/复制）
curl -X POST https://api.simsmsbox.com/api/sms/api-keys \
  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{"name":"server-1"}'
# 撤销
curl -X DELETE https://api.simsmsbox.com/api/sms/api-keys/{id} -H "Authorization: Bearer <token>"

提示：示例域名 https://api.simsmsbox.com 为本站 API 域名；若你自建部署，请替换为你自己的域名。完整字段与所有接口以在线 Swagger（/swagger）为准。

在线调试

想直接填入 API Key 实时测试？两种方式任选：

🧪 在线 API 调试台 在用户后台填 Key、选接口、即时看响应（覆盖常用接口） 📘 Swagger UI 后端自动收录的全部接口，Authorize 里填 X-API-Key 即可测试 🔑 创建 API Key 前往用户后台生成 psk_ 开头的密钥

REST API 文档

鉴权