短信推送（Webhook）与 JSON 取码格式说明

本文说明两件事：新短信到达时推给你的 Webhook 长什么样，以及接码链接怎么用 JSON 取码。按 number + project + code 三个字段就能自动分拣，不需要自己写正则猜。

一、Webhook 推送（新短信到达时）

请求方式：POST 你配置的地址，Content-Type: application/json，请求体是 JSON：

{
  "caller": "发送方号码（可能为空）",
  "callee": "+接收号码",
  "number": "接收号码（纯数字，不带 +）",
  "phone": "同 number",
  "project": "项目短名，如 Facebook / OpenAI/ChatGPT / Payment索赔 / Instagram",
  "code": "验证码（已提取好，4-8 位数字；没有则为空串）",
  "item_key": "项目代号，如 c1p12t1344",
  "item_name": "项目全名，如 Facebook 21-30天",
  "content": "短信正文（保留实际收到的 content，验签前不要改写）",
  "sms_text": "同 content",
  "sendTime": "2026-10-14 22:15:00",
  "received_at": "2026-10-14 22:14:58",
  "delivery_id": "本接收目标的稳定投递标识",
  "source_event_id": "关联同一短信事件的标识",
  "sign": "可选：SHA256(caller + callee + content + sendTime + 密钥)"
}

字段说明

字段	说明
`number` / `phone`	收到短信的号码（纯数字）。用它跟你自己的订单号做匹配。
`project`	项目短名，与推送体中的 `project` 字段一致。同一个号码可能在多个项目下，用它区分是哪条码。
`code`	字符串类型，保留前导零；常见分段数字码会合并。无法识别时为空串，不要转成整数。
`item_key` / `item_name`	项目代号与全名（含天数档位）。
`content` / `sms_text`	实际短信正文；不同推送配置的正文呈现方式可能不同，不承诺固定项目名前缀。按结构化 project / item_key / code 分拣，验签使用原始 content。
`sendTime`	推送体内的时间字符串，格式 `YYYY-MM-DD HH:MM:SS`；验签使用原值，重试保持不变。短信接收时间另见 received_at。
`sign`	配置了密钥才有：`SHA256(caller + callee + content + sendTime + 密钥)`，小写十六进制。

投递与重试

请求头 X-Webhook-Delivery-Id 与请求体 delivery_id 一致。接收端按本目标 delivery_id 幂等处理；source_event_id 用于关联同一短信事件，不替代目标级幂等。
返回 2xx 确认本次投递；其它状态码或超时会重试。失败采用退避重试，受最多 10 次和事件创建后 24 小时上限约束；不会固定只重试一次。重试保持正文、时间、签名和两个投递请求头不变。网络超时可能发生在接收端已处理之后，因此仍须幂等。
推送失败不影响取码：号码和接码链接始终能在网站或接口重新取到。

提示：同一号码被多个项目复用时，我们只把「该项目买了这个号」的短信推给你，不会串项目。

二、接码链接支持 JSON 取码

普通链接继续显示短信、项目与可确认的到期时间；浏览器显示与文本工具兼容。推送请求体不包含接码链接。要结构化字段就加 ?format=json，或用专门接口：

# 方式一：在客户手上的链接后面加参数
GET https://sms688.com/sms/<令牌>?format=json

# 方式二：专门的 JSON 接口（推荐）
GET https://sms688.com/api/sms/link/<令牌>

# 兼容旧版命名的完整 JSON 入口（字段以本文为准）
GET https://sms688.com/api/v1/sms/token?token=<令牌>

# 兼容旧版命名的最近 5 分钟纯文本入口
GET https://sms688.com/api/v1/sms/<令牌>

# 方式三：带 Accept 头（自动返回 JSON）
GET https://sms688.com/sms/<令牌>
Accept: application/json

{
  "ok": true,
  "status": "ok",
  "number": "13034350145",
  "phone": "13034350145",
  "project": "Facebook",
  "item_key": "c1p12t1344",
  "code": "982797",
  "content": "【Facebook】982797 is your confirmation code.\n【验证码时间】10-14 21:33:00",
  "has_sms": true,
  "stale": false,
  "expires_at": "2026-11-11 18:30:00",
  "expires_on": "2026-11-11",
  "days_left": 28,
  "updated_at": "2026-10-14 22:18:00"
}

还没收到码：status=pending、has_sms=false，建议 2-3 秒轮询一次（也可以直接用 GET /api/sms/live?token= 或长轮询 /api/sms/live/wait?token=&timeout=15）。
验证码是「推送入库」的，收到就会立刻出现在 JSON 里，不需要再额外拉取。
到期字段只取当前令牌对应项目和渠道的数据。expires_at 精确到秒；只有日期时 expires_at 为空串、expires_on 保留日期。未知到期字段为空，不按套餐天数推算；失效链接可能返回 HTTP 404 / not_found。普通链接与完整 JSON 不承诺最近 5 分钟截断；仅 /api/v1/sms/<令牌> 纯文本兼容入口限制最近 5 分钟，暂无符合条件短信时返回“暂无短信”。

三、curl 示例

# 取码（JSON）
curl "https://sms688.com/sms/89d51f3d50dea51044c9ee67?format=json"

# 取码（纯文本，老工具用法）
curl "https://sms688.com/sms/89d51f3d50dea51044c9ee67"

# 模拟你的 Webhook 收推送（示例）
# POST /your-hook
# {"number":"13034350145","project":"Facebook","code":"982797","content":"【Facebook】982797 ..."}

四、常见问题

1. 推送里为什么有「项目」字段？

一个号码可能同时在多个项目下（例如同时挂 Facebook、OpenAI、Payment）。只用号码分拣会把别的项目的码推给错误的客户，所以推送里给了 project + item_key，正文按实际 content 保留，程序应优先读取结构化字段。

2. 客户打开链接看到「暂无短信」？

说明该号码这个项目还没收到短信。可以看 JSON 里的 status；pending 就是还没有码，expired 是号码到期了。

3. 想批量核对号码与到期时间？

用开放接口 GET /api/open/numbers（支持 order_id / min_order_id / days / 分页），详见 API 文档。