API 文档

鉴权与重试

在主控台创建 API 密钥，以 Authorization: Bearer obk_… 传入。创建订单必须复用相同的 Idempotency-Key 重试，禁止在网络错误后换一个键。租号续租发生不确定结果时会保持待核对状态，请勿重送。

端点 · /api/v1

租号 body：{ country, days, autoRenew }。租号需 Idempotency-Key。响应分别包在 verification 或 rental 字段。

示例

curl -X POST https://YOUR_DOMAIN/api/v1/verifications   -H 'Authorization: Bearer obk_PREFIX_SECRET'   -H 'Idempotency-Key: my-order-0001'   -H 'Content-Type: application/json'   -d '{"service":"whatsapp","country":"US"}'

// Keep this key when retrying this order.
const orderKey = crypto.randomUUID();
const response = await fetch(baseUrl + '/api/v1/verifications', {
  method: 'POST',
  headers: { Authorization: 'Bearer ' + apiKey, 'Content-Type': 'application/json',
    'Idempotency-Key': orderKey },
  body: JSON.stringify({ service: 'whatsapp', country: 'US' })
});
const result = await response.json();
if (!response.ok) throw new Error(result.error?.code);

import requests, uuid
# Keep this key when retrying this order.
order_key = str(uuid.uuid4())
r = requests.post(base_url + '/api/v1/verifications',
  headers={'Authorization': 'Bearer ' + api_key, 'Idempotency-Key': order_key},
  json={'service': 'whatsapp', 'country': 'US'})
r.raise_for_status()
print(r.json())

免登录取码 API

持有单笔订单的分享令牌即可直接读取号码、当前状态和短信，不需要登录网页、cookie 或 OneBox 账户密钥。GET 使用下方 Bearer 令牌；也支持 POST JSON { token }。链接默认不自动到期，可由拥有者撤销或换发；租号本身仍按购买的租期到期。

curl https://YOUR_DOMAIN/api/auth/order-share/read \
  -H 'Authorization: Bearer ORDER_SHARE_TOKEN'

返回 { order: { kind, service, country, phone, status, latestCode, latestMessageAt, endsAt, linkExpiresAt, messages } }。无效或撤销的令牌返回 404。管理分享令牌可调用上面的 /api/v1/.../share，无需网页登录。

错误码

错误格式为 { error: { code, message } }，根据 HTTP 状态和 code 处理。

401 unauthorized
402 insufficient_balance
403 email_not_verified / service_prohibited / account_suspended
404 not_found
409 out_of_stock / renewal_pending / not_renewable
429 rate_limited / order_limit
503 upstream_unavailable / payment_provider_not_configured

Webhook

订阅 verification.received、verification.expired、rental.message、rental.expiring。先验证 X-OneBox-Signature 的时间与 HMAC-SHA256 签名，以事件 id 去重，然后回复 2xx。失败后在 1、5、30 分钟、2、6 小时重试，仍失败就停用端点。

import { createHmac, timingSafeEqual } from 'node:crypto';
// rawBody must be the exact received bytes, before JSON parsing.
const parts = Object.fromEntries(signatureHeader.split(',').map(p => p.split('=')));
if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) throw new Error('expired');
const expected = createHmac('sha256', secret).update(parts.t + '.' + rawBody).digest();
const provided = Buffer.from(parts.v1 || '', 'hex');
if (expected.length !== provided.length || !timingSafeEqual(expected, provided))
  throw new Error('invalid signature');
// Deduplicate payload.id, then return HTTP 2xx.