Vozira SMS 开发者接口

认证与余额

登录普通 Vozira 账户 → API Access → 生成并妥善保存密钥。现有有效密钥可直接用于 v1。在自己的服务端通过 HTTPS 的 X-Api-Key 请求头调用，不要放在网址、公开代码或浏览器前端中。轮换密钥会撤销旧密钥。充值使用网站现有充值入口；v1 不创建收款账单。

长期号

先读取 /apps 和 /limits，使用目录返回的 app_id、cate_id、quantity、expiry 和 expected_total 购买。目前新购仅支持 type=1。首次提交前保存唯一的 16–128 字符 Idempotency-Key。只有 status=completed 且 request_status=completed 才表示购买完成；用返回的 order_reference 和号码 item ID 查询订单、收码。金额为美元，最多四位小数；库存可能在下单前变化。

临时号

使用普通账户 API 密钥，分别搜索项目与国家；初始目录是常用项，不代表全部可售项目。选择组合后获取报价，核对价格与报价到期时间，再用 quote_id 和保存好的 Idempotency-Key 购买。同一键换另一个报价会返回 IDEMPOTENCY_CONFLICT。订单返回短信、能否取消及退款状态。订单列表最多返回最近100笔，更早订单请保存 ID 后逐笔查询。

取消与退款

临时号有效期20分钟，以 expires_at 为准。满2分钟且未收码可申请取消；取消处理中不代表已退款。到期时本站仍未收码，按原购买金额退本站余额；已收码不按未收码规则退款。确认 refund.status=refunded 并核对 refund.amount，同一笔最多退款一次。购买失败并退回已扣金额也可能返回 refunded。review_required 表示该单仍需核对。

重试、状态与频率

超时、5xx、processing 或扣款结果不明时，查询原幂等键或原订单，不要换键重新购买。HTTP 200/202、ok:true 本身不证明已交付。超时后立即查不到记录可能是原请求仍在进行，继续查询，持续不明请联系支持。收码轮询至少间隔5秒，无短信可放慢到10–15秒；429 遵守 Retry-After，也受全站和网络限制。v1 暂不提供开发者回调，通过订单查询短信和退款。暂无公开沙箱，成功购买使用真实站内余额。

有效期与续费

expiry：0=随机，1=5–30天，2=10–30天，3=15–30天，4=30–60天，5=60–80天，6=80天以上（+10%）。分类4、5只接受0。区间是选号条件，实际到期以订单为准。普通账户符合条件的号码按 eligibility → quote → confirm 续费，确认时提交空 JSON 和已保存的幂等键。正常续费成功为 state=succeeded；quoted 待确认，submitting/needs_review 继续查询，success_unpaid 类状态需联系支持，不要按失败重新购买；failed 为原操作结束。price_cents 是美元分，quote_expires_at 是 Unix 毫秒。end_time 可能为 Unix 秒/毫秒或时间文本，无时区文本按 UTC+08:00 解释，不要补 Z；purchased_at、recorded_at 为 UTC。

错误处理

错误返回 error.code、固定说明和用于联系客服的 error.request_id。错误追踪号与持久化购买 request_id 不同。价格错误可带 unit_price、total_price。charge_status=unknown 表示应查询原单，不能当作未扣款。网站/CDN 拦截的响应格式可能不同，也应检查 HTTP 状态。

兼容说明

原 /api/reseller 长期号接口和旧账户继续保留；产品元数据收敛为客户字段。新接入推荐 v1。临时号、钱包流水和标准续费要求普通账户；旧 Reseller 充值仍走原入口。目录编号仅作为不透明选择值使用，不要推断其含义。

调用示例（所有示例编号与价格都需替换）

export VOZIRA_API_KEY='YOUR_VOZIRA_API_KEY'
curl https://vozirasms.com/api/v1/balance \
  -H "X-Api-Key: $VOZIRA_API_KEY"
curl 'https://vozirasms.com/api/v1/apps?type=1&expiry=0&search=Telegram' \
  -H "X-Api-Key: $VOZIRA_API_KEY"
# Use IDs and price returned by the live catalog; save the key before sending.
curl https://vozirasms.com/api/v1/buy \
  -H "X-Api-Key: $VOZIRA_API_KEY" -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: YOUR_SAVED_UNIQUE_KEY_0001' \
  --data '{"app_id":123,"cate_id":2,"type":1,"quantity":1,"expiry":0,"expected_total":"0.5000"}'
# After timeout: query, do not use a new purchase key.
curl https://vozirasms.com/api/v1/requests/by-key \
  -H "X-Api-Key: $VOZIRA_API_KEY" \
  -H 'Idempotency-Key: YOUR_SAVED_UNIQUE_KEY_0001'

# Search each selection list, then quote the selected pair.
curl 'https://vozirasms.com/api/v1/one-time/catalog?service=Telegram' -H "X-Api-Key: $VOZIRA_API_KEY"
curl 'https://vozirasms.com/api/v1/one-time/catalog?country=United%20States' -H "X-Api-Key: $VOZIRA_API_KEY"
curl https://vozirasms.com/api/v1/one-time/quote \
  -H "X-Api-Key: $VOZIRA_API_KEY" -H 'Content-Type: application/json' \
  --data '{"service_code":"CATALOG_CODE","country_id":1}'
# Review quote.price and expires_at. Save this different key before sending.
curl https://vozirasms.com/api/v1/one-time/buy \
  -H "X-Api-Key: $VOZIRA_API_KEY" -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: YOUR_SAVED_UNIQUE_KEY_0002' \
  --data '{"quote_id":"QUOTE_UUID_FROM_RESPONSE"}'
curl https://vozirasms.com/api/v1/one-time/requests/by-key \
  -H "X-Api-Key: $VOZIRA_API_KEY" -H 'Idempotency-Key: YOUR_SAVED_UNIQUE_KEY_0002'
curl https://vozirasms.com/api/v1/one-time/orders/OT_REPLACE_WITH_ORDER_ID \
  -H "X-Api-Key: $VOZIRA_API_KEY"

Python example · Node.js example

接口目录

OpenAPI: request and response schemas

GET /balance — 账户余额

{
  "parameters": []
}

GET /recharge — 本站充值入口

{
  "parameters": []
}

GET /limits — 长期号额度及请求频率

{
  "parameters": []
}

GET /apps — 长期号目录

{
  "parameters": [
    {
      "name": "type",
      "in": "query",
      "required": false,
      "schema": {
        "type": "integer",
        "enum": [
          1
        ],
        "default": 1
      },
      "description": ""
    },
    {
      "name": "expiry",
      "in": "query",
      "required": false,
      "schema": {
        "type": "integer",
        "minimum": 0,
        "maximum": 6,
        "default": 0
      },
      "description": ""
    },
    {
      "name": "search",
      "in": "query",
      "required": false,
      "schema": {
        "type": "string",
        "maxLength": 80
      },
      "description": ""
    },
    {
      "name": "cate_id",
      "in": "query",
      "required": false,
      "schema": {
        "type": "integer",
        "minimum": 1
      },
      "description": ""
    }
  ]
}

POST /buy — 购买长期号

{
  "parameters": [
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": true,
      "schema": {
        "type": "string",
        "minLength": 16,
        "maxLength": 128,
        "pattern": "^[A-Za-z0-9._~:+/=\\-]{16,128}$"
      },
      "description": "Save before sending. Reuse only for the exact original operation; never rotate after an unknown outcome."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "app_id": {
              "type": "integer",
              "minimum": 1
            },
            "cate_id": {
              "type": "integer",
              "minimum": 1
            },
            "type": {
              "type": "integer",
              "enum": [
                1
              ],
              "default": 1
            },
            "quantity": {
              "type": "integer",
              "minimum": 1
            },
            "expiry": {
              "type": "integer",
              "minimum": 0,
              "maximum": 6,
              "default": 0
            },
            "expected_total": {
              "type": "string",
              "pattern": "^(0|[1-9]\\d{0,5})(\\.\\d{1,4})?$"
            },
            "prefix": {
              "type": "string"
            }
          },
          "required": [
            "app_id",
            "cate_id",
            "quantity",
            "expected_total"
          ],
          "additionalProperties": false
        }
      }
    }
  }
}

GET /requests/by-key — 按幂等键找回长期号购买

{
  "parameters": [
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": true,
      "schema": {
        "type": "string",
        "minLength": 16,
        "maxLength": 128,
        "pattern": "^[A-Za-z0-9._~:+/=\\-]{16,128}$"
      },
      "description": "Save before sending. Reuse only for the exact original operation; never rotate after an unknown outcome."
    }
  ]
}

GET /requests/{id} — 长期号购买结果

{
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      }
    }
  ]
}

GET /orders — 长期号订单列表

{
  "parameters": [
    {
      "name": "limit",
      "in": "query",
      "required": false,
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 100,
        "default": 20
      },
      "description": ""
    },
    {
      "name": "before_id",
      "in": "query",
      "required": false,
      "schema": {
        "type": "integer",
        "minimum": 1
      },
      "description": ""
    }
  ]
}

GET /orders/{reference} — 长期号订单详情

{
  "parameters": [
    {
      "name": "reference",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "pattern": "^VZ-\\d+$"
      }
    }
  ]
}

GET /sms/{item_id} — 读取长期号短信

{
  "parameters": [
    {
      "name": "item_id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "integer",
        "minimum": 1
      }
    }
  ]
}

GET /sms-history — 短信历史

{
  "parameters": [
    {
      "name": "limit",
      "in": "query",
      "required": false,
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 100,
        "default": 20
      },
      "description": ""
    },
    {
      "name": "before_id",
      "in": "query",
      "required": false,
      "schema": {
        "type": "integer",
        "minimum": 1
      },
      "description": ""
    },
    {
      "name": "item_id",
      "in": "query",
      "required": false,
      "schema": {
        "type": "integer",
        "minimum": 1
      },
      "description": ""
    }
  ]
}

GET /transactions — 本站钱包流水

Regular accounts only. Includes website and API wallet transactions.

{
  "parameters": [
    {
      "name": "limit",
      "in": "query",
      "required": false,
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 100,
        "default": 20
      },
      "description": ""
    },
    {
      "name": "before_id",
      "in": "query",
      "required": false,
      "schema": {
        "type": "integer",
        "minimum": 1
      },
      "description": ""
    }
  ]
}

GET /renewal/eligibility/{itemId} — 检查续费资格