开发者文档

长期号码 API

长期号码使用独立的 JSON REST 接口，固定产品为美国 OpenAI Codex。价格由产品接口返回，客户端应以 priceCents 与 durationDays 为准，不要在程序中写死金额。

长期号码客户入口开启后，网页 /long-numbers.html 与本组 REST 才可访问；未开放时，页面与本组 API 均返回 404。入口开放不代表当前可提取或续费，请先读取产品的 salesEnabled。

身份验证

浏览器网页使用登录后由服务端设置的 customer_session Cookie，并以同源请求访问；不要手工读取或复制该 Cookie。服务端接入可使用下面任一请求头。三种方式都只代表对应的普通客户账户；若同时发送登录会话与 API Key，两者必须属于同一账户。

X-API-Key: YOUR_API_KEY
Authorization: Bearer YOUR_API_KEY

不要把 API Key 放进 URL。所有 POST、PATCH 与 DELETE 请求都必须发送 Content-Type: application/json；使用登录会话执行修改时还必须是同源请求。

产品

GET /api/long-numbers/product 返回 product，公开字段为 code、name、accountNamespace、priceCents、durationDays、retentionDays 与 salesEnabled。每次开通或续费延长 26 天，到期后保留 3 天；保留期内可以续费，但不能接收新验证码。accountNamespace 是当前认证账户的非敏感稳定命名空间，网页用它隔离本地幂等操作记录；调用方不得把它当作认证凭据。当前固定 code 为 us-openai-codex；只有 salesEnabled 为 true 时才应提交新的付费动作。

接口一览

开通号码

每一次新开通都要由调用方生成并持久保存唯一的 operationId，并把刚从产品接口读取的 priceCents 原样作为 expectedPriceCents 提交。请求超时、断网或返回结果待确认时，同一次提取或续费重试必须复用同一个 operationId 和确认价格，不能生成新值；价格已经变化时，应先刷新产品再由用户重新确认。

curl -X POST "https://api.gynb6666.com/api/long-numbers/orders" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"operationId":"create:YOUR_UNIQUE_ID","expectedPriceCents":400}'

成功响应为 JSON，包含 ok 与当前账户可见的 order。手机号、订单和验证码始终按认证所对应的账户隔离。

查询订单与验证码

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.gynb6666.com/api/long-numbers/orders?view=current&page=1"

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.gynb6666.com/api/long-numbers/orders/ORDER_ID"

view=current 返回 status 为 waiting 的订单；view=mine 返回 status 为 success 的订单；view=history 返回当前账户尚可见且未从历史视图隐藏的记录。列表接口返回 orders、page、pageSize、total 与 totalPages。

订单公开字段包括 id、productCode、phone、status、lifecycle、chargedPriceCents、refundCents、expiresAt、retentionEndsAt、note、messageCount、latestCode、lastMessageAt 与 receive。详情接口还返回 messages；未收到验证码时 latestCode、lastMessageAt 为 null 且 messages 为空。验证码正文默认只保留24小时：到期后 messages 仍保留时间与事件元数据，但 code 为 null。删除历史记录会立即清除该订单已交付的验证码正文，不会释放仍有效的号码。

status：waiting、success、cancelled、failed、released。lifecycle：waiting、active、renewal_due、retention、reconciliation、cancelled、failed、released。是否可取消、开窗或续费应分别读取 canCancel、canReceive 与 canRenew，不要只按状态文字推断。

收码、取消、续费、释放与记录

# 开启或取消当前 15 分钟收码窗口
POST /api/long-numbers/orders/{orderId}/receive
POST /api/long-numbers/orders/{orderId}/receive/cancel

# 续费；operationId 与 expectedPriceCents 规则均与开通相同
POST /api/long-numbers/orders/{orderId}/renew
{"operationId":"renew:YOUR_UNIQUE_ID","expectedPriceCents":400}

# 释放号码；释放后无法恢复，剩余有效期不退款
POST /api/long-numbers/orders/{orderId}/release

# 备注与隐藏历史记录
PATCH /api/long-numbers/orders/{orderId}/note
{"note":"我的备注"}
DELETE /api/long-numbers/records
{"ids":["ORDER_ID"]}

首码前且订单允许取消时，可调用 POST /api/long-numbers/orders/{orderId}/cancel；成功退款会记入账户余额与资金流水。只有 canRelease 为 true 时才能释放号码，释放后无法恢复且剩余有效期不退款。绑定到期后会进入保留期，最终释放状态以订单查询结果为准。

状态码与安全重试

错误响应仍为 JSON：{"ok":false,"error":"..."}。若同时返回 reconciliationRequired: true，表示结果尚未确认，请勿自动重试或更换 operationId；请先查询订单，仍未恢复时联系技术支持。只有响应明确返回 operationTerminal: true 时，才可结束该 operationId 的重试周期。