Vozira 开发者文档Vozira developer documentation

现有 X-Api-Key 与 /api/reseller 路径不变。本接口当前提供长期号码；临时号码暂未开放 API-key 购买。购买完成同时返回 request_status=completed 与 status=completed；处理中返回 HTTP 202、status=processing。failed_no_effect 表示该原单已结束且未扣款，重复提交原键只查询原结果，不再购买。不要仅凭 HTTP 200、ok:true 或 success:true 判断已获号码。价格错误保留 PRICE_CHANGED / PRICE_CONFIRMATION_REQUIRED 及 error.total_price；原单查询不存在保留 REQUEST_NOT_FOUND。顶层 request_id 是购买编号，error.request_id 是本次调用追踪号。

登录普通账户 → 控制台 API Access → 生成并安全保存密钥。只在服务端使用 X-Api-Key 请求头；禁止 URL 密钥。先调用 balance、apps，再按当前价格确认购买。密钥可轮换或独立撤销；完整值只显示一次。

个人 API 与网站共用余额、充值和零售价格；旧 Reseller 仍使用原账户及价格。先读取 /apps 的 price，提交 expected_total（USD，最多4位小数）和 Idempotency-Key。线路 route_option 必须与目录查询一致。PRICE_CHANGED 返回新价格，不派发购买。

pending、needs_review 或连接失联：保存原键与 request_id，查询原请求，不换键购买。未决请求可能暂时阻止本账户新的长期号码购买（网页与 API 共用保护）；保护窗口结束不代表原请求已确认失败。请继续查询原请求，不为同一需求换键购买。旧请求只能查询；旧 failed 不代表已核实无效果。HTTP 202 不是购买成功，只有 request_status=completed 才是完成。

实际购买数量、每日笔数/数量/金额上限以 /limits 为准。全站 API 每 IP 共用600次/分钟，API还有分层限额：IP180/分钟、账户120/分钟；购买5/分钟且1/秒；目录30/分钟；读取60/分钟；订单30/分钟；短信每号码12/分钟、每账户60/分钟；续费5/分钟。收到429遵守 Retry-After。短信至少间隔5秒，空结果后退避至10–15秒。

错误结构 {success:false,error:{code,message,request_id}}；HTTP 400/401/403/404/409/429/500/502/503。全站限流可能返回 {ok:false,msg}。错误追踪 request_id 不是持久购买编号；连接失联后按原 Idempotency-Key 查询。

expiry：0=随机；1=5–30天；2=10–30天；3=15–30天；4=30–60天；5=60–80天；6=80天以上（加价10%），不是6个月。选项表示范围；最终以回执 end_time 为准。当前 /buy 只开放 type=1 新号码；type=2/3 返回 SAME_NUMBER_UNAVAILABLE。普通号码续费使用独立 renewal 接口。

purchased_at、recorded_at 是带Z的UTC时间；renewal.quote_expires_at 是 Unix 毫秒，price_cents 是 USD 分。end_time 保留原值：10位/13位数字分别是 Unix 秒/毫秒；带偏移按其偏移解析；无偏移的日期时间按服务器时区 Asia/Shanghai（UTC+08:00）解释，不声明为UTC，不能自行加Z或按客户端时区转换。请保留原值并使用返回的号码 status 判断有效性。

普通续费仅限个人账户。先 eligibility，再 quote，确认时使用原 operation_id、同一个幂等键和空正文。HTTP200 或 ok:true 不等于续费成功。payment_state 只有 charged / checking / not_charged，表示本站钱包状态，不证明外部结果。状态处理见下表；任何未决状态都不要另建报价重试。

以下示例从隔离接口响应生成，全部为虚构数据。替换 YOUR_KEY 与 :id / :itemId / :reference，使用当前目录、实际报价和返回ID。旧 Extend 仅用于 session_end 会话，不是普通续费。旧 Reseller 登录和充值仍保留；个人账户直接使用网站充值。

quoted — 报价待确认；检查有效期和价格后按原ID/键确认

submitting — 派发中；只查询、等待，不能重发

succeeded — 成功且本站已扣费；以新 end_time 为准

needs_review — 结果待核实；只查询/联系支持，不重试

success_unpaid — 人工核实成功但未向用户扣费；不补扣，不当作失败重试

success_unpaid_isolated — 人工核实成功但访问材料待处理，仍隔离；联系支持，不重试

failed — 已判定无效果或人工确认无效果；原操作不可复用，查明原因再决定新请求

Existing X-Api-Key authentication and /api/reseller paths remain unchanged. This API offers long-term numbers; temporary-number purchases are not exposed to API keys. Completed purchases return request_status=completed and status=completed; processing returns HTTP 202 and status=processing. failed_no_effect closes that original request without a charge; replaying its key never buys again. HTTP 200, ok:true or success:true alone does not prove number delivery. Price errors preserve PRICE_CHANGED / PRICE_CONFIRMATION_REQUIRED and error.total_price; missing purchase lookups preserve REQUEST_NOT_FOUND. Top-level request_id is the purchase ID; error.request_id traces the current call.

Sign in to your personal account → dashboard API Access → generate and securely save a key. Send X-Api-Key from server-side code only, never in a URL. Start with balance and apps, then confirm the current price. Rotate or independently revoke keys in API Access; the full value is shown once.

Personal API shares website balance, recharge and retail prices. Existing resellers retain their account and prices. Read /apps price, then send expected_total (USD, up to 4 decimals) and Idempotency-Key. Reuse the same route_option as the catalog query. PRICE_CHANGED returns a new price without dispatching a purchase.

For pending, needs_review or connection loss, query the original key or request ID. Do not buy with another key. Unresolved requests may temporarily block new long-term purchases on both the website and API. The end of that protection window does not prove failure. Continue querying the original request; do not use a new key for the same intended purchase. Legacy requests are query-only; legacy failed does not prove no effect. HTTP202 is not success; only request_status=completed indicates completion.

Read /limits for current quantity and daily count/quantity/spend caps. The site-wide API IP limit is 600/minute shared with website traffic. Additional API limits: IP180/minute, account120/minute; Buy5/minute and1/second; catalog30/minute; reads60/minute; orders30/minute; SMS12/item/minute and60/account/minute; renewal5/minute. Respect Retry-After on429. Poll SMS at least5seconds apart and back off to10–15seconds after empty results.

Errors use {success:false,error:{code,message,request_id}} with HTTP400/401/403/404/409/429/500/502/503. Site-wide rate limits may return {ok:false,msg}. An error trace request_id is not the persistent purchase ID. After connection loss, query with the original Idempotency-Key.

expiry: 0=random; 1=5–30days; 2=10–30days; 3=15–30days; 4=30–60days; 5=60–80days; 6=80+days (+10%), not six months. These are ranges; the receipt end_time is authoritative. Currently /buy supports type=1 new numbers only; type=2/3 returns SAME_NUMBER_UNAVAILABLE. Use the separate renewal endpoints for standard renewal.

purchased_at and recorded_at are UTC with Z. renewal.quote_expires_at is Unix milliseconds; price_cents is USD cents. end_time preserves its source value: 10/13digit values are Unix seconds/milliseconds; offsets are respected. A date-time without an offset uses the server timezone Asia/Shanghai (UTC+08:00) and is not declared UTC. Do not append Z or reinterpret it in your client timezone. Preserve the raw value and use the returned item status for current validity.

Standard renewal is for personal accounts. Check eligibility, then quote, then confirm with the original operation ID, same idempotency key and empty body. HTTP200 or ok:true alone is not renewal success. payment_state is charged/checking/not_charged for the site wallet; it does not prove the external outcome. Follow the state table below and never create another quote to retry an unresolved renewal.

Examples below come from isolated API responses and use fictional data. Replace YOUR_KEY and :id/:itemId/:reference with current catalog values, quotes and your returned IDs. Legacy Extend is only for session_end items, not standard renewal. Existing reseller login and recharge remain; personal users recharge through the website.

quoted — Quote ready; verify expiry and price, then confirm the original ID/key

submitting — In flight; query and wait without another dispatch

succeeded — Succeeded and charged locally; use the new end_time

needs_review — Needs review; query or contact support without retrying

success_unpaid — Manually verified success without user debit; no later debit, do not retry as a failure

success_unpaid_isolated — Verified success but access material needs review; remains isolated; contact support, do not retry

failed — Determined or manually verified no effect; original operation is closed; review the cause before any new request