API

一套遵循虚拟号码行业事实标准协议的 REST API。把现有客户端的基础地址和密钥换成我们的，就能直接用。

把你现有的客户端指向我们

只改两行 — 基础地址和令牌 — 客户端原有的每个调用都照常工作。路径、查询参数、JSON 字段名和错误文本完全一致。

基础地址

https://otphub-api.43.203.247.133.nip.io/v1

身份验证

每次请求都以 Bearer 令牌的形式携带你的密钥。

请求

curl -H "Authorization: Bearer $OTPHUB_KEY" -H "Accept: application/json" "https://otphub-api.43.203.247.133.nip.io/v1/user/profile"

快速上手

在账户页创建密钥，导出为环境变量，然后购买一个号码。

快速上手

export OTPHUB_KEY="your-api-key"

# 1. what is in stock
curl "https://otphub-api.43.203.247.133.nip.io/v1/guest/products/england/any"

# 2. buy a number
curl -H "Authorization: Bearer $OTPHUB_KEY" "https://otphub-api.43.203.247.133.nip.io/v1/user/buy/activation/england/any/facebook"

# 3. poll it until the code lands
curl -H "Authorization: Bearer $OTPHUB_KEY" "https://otphub-api.43.203.247.133.nip.io/v1/user/check/11631253"

接口

免登录

GET/v1/guest/countries无需令牌

我们覆盖的所有国家，含国际区号和当地运营商。

请求

curl "https://otphub-api.43.203.247.133.nip.io/v1/guest/countries"

响应

{
  "england": {
    "iso": { "gb": 1 },
    "prefix": { "+44": 1 },
    "text_en": "England",
    "text_ru": "England",
    "vodafone": { "activation": 1 }
  }
}

GET/v1/guest/products/{country}/{operator}无需令牌

指定国家和运营商下可用的服务，含数量和价格。两个片段都可以填 any。

请求

curl "https://otphub-api.43.203.247.133.nip.io/v1/guest/products/england/any"

响应

{
  "1day":     { "Category": "hosting",    "Qty": 14,  "Price": 80 },
  "facebook": { "Category": "activation", "Qty": 133, "Price": 21 }
}

GET/v1/guest/prices?country=&product=无需令牌

完整价格矩阵，按国家 → 服务 → 运营商嵌套。可用 country 或 product 过滤。

请求

curl "https://otphub-api.43.203.247.133.nip.io/v1/guest/prices?country=england&product=facebook"

响应

{
  "england": {
    "facebook": {
      "vodafone": { "cost": 21, "count": 1260, "rate": 99.99 }
    }
  }
}

GET/v1/guest/flash/{lang}无需令牌

以你指定的语言返回当前站点公告。

请求

curl "https://otphub-api.43.203.247.133.nip.io/v1/guest/flash/en"

账户

GET/v1/user/profileBearer 令牌

你的余额、冻结金额、信誉分和默认设置。

请求

curl -H "Authorization: Bearer $OTPHUB_KEY" "https://otphub-api.43.203.247.133.nip.io/v1/user/profile"

响应

{
  "id": 1,
  "email": "you@example.com",
  "vendor": "otphub",
  "default_forwarding_number": "",
  "balance": 100,
  "rating": 96,
  "default_country": { "name": "england", "iso": "gb", "prefix": "+44" },
  "default_operator": { "name": "" },
  "frozen_balance": 0
}

GET/v1/user/orders?category=&limit=&offset=&order=&reverse=Bearer 令牌

你的订单记录，最新的在前。

请求

curl -H "Authorization: Bearer $OTPHUB_KEY" "https://otphub-api.43.203.247.133.nip.io/v1/user/orders?category=activation&limit=25"

响应

{ "Data": [ /* orders */ ], "ProductNames": [], "Statuses": [], "Total": 3 }

GET/v1/user/payments?limit=&offset=&order=&reverse=Bearer 令牌

充值和调整的账本记录。

请求

curl -H "Authorization: Bearer $OTPHUB_KEY" "https://otphub-api.43.203.247.133.nip.io/v1/user/payments?limit=25"

响应

{
  "Data": [
    {
      "ID": 30011934,
      "TypeName": "charge",
      "ProviderName": "admin",
      "Amount": 100,
      "Balance": 100,
      "CreatedAt": "2026-08-17T15:37:08.149895Z"
    }
  ],
  "PaymentTypes": [{ "Name": "charge" }],
  "PaymentProviders": [{ "Name": "admin" }],
  "Total": 1
}

GET/v1/user/max-pricesBearer 令牌

你为各项服务设置的价格上限。

请求

curl -H "Authorization: Bearer $OTPHUB_KEY" "https://otphub-api.43.203.247.133.nip.io/v1/user/max-prices"

响应

[{ "id": 14, "product": "facebook", "price": 11, "CreatedAt": "2026-08-17T15:37:08Z" }]

POST/v1/user/max-pricesBearer 令牌

为某项服务设置上限，超过则拒绝购买。

请求

curl -X POST "https://otphub-api.43.203.247.133.nip.io/v1/user/max-prices" \
  -H "Authorization: Bearer $OTPHUB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product_name":"facebook","price":30}'

DELETE/v1/user/max-pricesBearer 令牌

删除某个上限。

请求

curl -X DELETE "https://otphub-api.43.203.247.133.nip.io/v1/user/max-prices" \
  -H "Authorization: Bearer $OTPHUB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product_name":"facebook"}'

购买

GET/v1/user/buy/activation/{country}/{operator}/{product}Bearer 令牌

购买一次性验证号码，返回带手机号的订单。

请求

curl -H "Authorization: Bearer $OTPHUB_KEY" \
  "https://otphub-api.43.203.247.133.nip.io/v1/user/buy/activation/england/any/facebook?maxPrice=30"

响应

{
  "id": 11631253,
  "phone": "+447350690992",
  "operator": "vodafone",
  "product": "facebook",
  "price": 21,
  "status": "PENDING",
  "expires": "2026-08-17T08:28:38.809469028Z",
  "sms": null,
  "created_at": "2026-08-17T08:13:38.809469028Z",
  "forwarding": false,
  "forwarding_number": "",
  "country": "england"
}

GET/v1/user/buy/hosting/{country}/{operator}/{product}Bearer 令牌

按时长租用号码：3hours、1day、10days 或 1month。

请求

curl -H "Authorization: Bearer $OTPHUB_KEY" "https://otphub-api.43.203.247.133.nip.io/v1/user/buy/hosting/england/any/1day"

GET/v1/user/reuse/{product}/{number}Bearer 令牌

在运营商允许的情况下，为同一服务再次购买同一号码。

请求

curl -H "Authorization: Bearer $OTPHUB_KEY" "https://otphub-api.43.203.247.133.nip.io/v1/user/reuse/facebook/447350690992"

订单管理

GET/v1/user/check/{id}Bearer 令牌

轮询订单，查看是否有新短信。

请求

curl -H "Authorization: Bearer $OTPHUB_KEY" "https://otphub-api.43.203.247.133.nip.io/v1/user/check/11631253"

响应

{
  "id": 11631253,
  "phone": "+447350690992",
  "operator": "vodafone",
  "product": "facebook",
  "price": 21,
  "status": "PENDING",
  "expires": "2026-08-17T08:28:38.809469028Z",
  "sms": null,
  "created_at": "2026-08-17T08:13:38.809469028Z",
  "forwarding": false,
  "forwarding_number": "",
  "country": "england"
}

GET/v1/user/finish/{id}Bearer 令牌

关闭用完的订单，冻结金额将正式扣除。

请求

curl -H "Authorization: Bearer $OTPHUB_KEY" "https://otphub-api.43.203.247.133.nip.io/v1/user/finish/11631253"

GET/v1/user/cancel/{id}Bearer 令牌

在短信到达前取消，冻结随即释放。

请求

curl -H "Authorization: Bearer $OTPHUB_KEY" "https://otphub-api.43.203.247.133.nip.io/v1/user/cancel/11631253"

GET/v1/user/ban/{id}Bearer 令牌

举报号码已被使用。冻结释放，号码移出库存。

请求

curl -H "Authorization: Bearer $OTPHUB_KEY" "https://otphub-api.43.203.247.133.nip.io/v1/user/ban/11631253"

GET/v1/user/sms/inbox/{id}Bearer 令牌

租用号码收到的全部短信。

请求

curl -H "Authorization: Bearer $OTPHUB_KEY" "https://otphub-api.43.203.247.133.nip.io/v1/user/sms/inbox/11631253"

响应

{
  "Data": [
    {
      "ID": 1,
      "created_at": "2026-08-17T17:23:25.106597Z",
      "date": "2026-08-17T17:23:15Z",
      "sender": "Facebook",
      "text": "Use 415127 as your login code",
      "code": "415127",
      "is_wave": false,
      "wave_uuid": ""
    }
  ],
  "Total": 1
}

订单状态

每笔购买都会经历这些状态，下面的字符串就是 API 实际返回的值。

状态	说明
`PENDING`等待中	号码已激活，正在等待短信。
`RECEIVED`已收到验证码	已收到至少一条验证码。
`CANCELED`已取消	订单已取消，冻结金额已释放。
`TIMEOUT`已超时	在规定时间内没有收到短信，费用已退回。
`FINISHED`已完成	订单已关闭，费用已扣除。
`BANNED`已举报	已被举报为用过的号码，费用已退回。

错误

请求失败时返回一段纯文本说明原因，与标准协议完全一致。

错误内容	返回条件
`no free phones`	该国家、运营商和服务的组合没有库存。
`not enough user balance`	余额不足以支付价格。
`not enough rating`	信誉分为 0，24 小时后才能再次下单。
`select country`	国家片段为空。
`select operator`	运营商片段为空。
`bad country`	目录中没有这个国家标识。
`bad operator`	目录中没有这个运营商标识。
`no product`	目录中没有这个服务标识。
`server offline`	无法连接上游供应商。
`order not found`	该账户下没有这个订单号。
`order expired`	订单已超过有效期。
`order has sms`	短信已经到达，订单无法取消。
`hosting order`	该调用不适用于租用类订单。
`reuse not possible`	运营商不允许重复使用这个号码。
`reuse false`	原订单下单时没有开启复用。
`reuse expired`	该号码的复用期限已结束。

调用频率限制

每个 API 密钥每秒 100 次请求。持续滥用会被临时封禁。

每个 IP 每秒 100 次请求，超出返回 503。
每个 API 密钥每秒 100 次请求，超出返回 429。
整个账户每秒最多 100 次购买。
十分钟内五次触及限制，该密钥会被封禁十分钟。

无缝兼容

路径、JSON 结构和错误文本都与行业标准协议完全一致，包括首字母大写的字段名和纯文本错误响应。现有客户端库无需任何改动。