虚拟号码 API
适用于经销商
以编程方式提供专用的月度和年度虚拟电话号码，设置自己的转售价格，并构建自己的短信验证品牌 —— 无需拥有任何 SIM 卡。
为什么选择在 VRNUM API 上构建，而不是使用您自己的运营商合作
直接获取真实的移动运营商号码意味着需要处理 SIM 合同、硬件、合规负担，并且在您开始销售任何验证之前需要数月的准备时间。VRNUM API 可以跳过所有这些步骤。
您可以即时访问覆盖 50 多个国家的月度和年度虚拟号码的实时库存，并且每个 API 返回的价格中都包含您自己的利润。您的客户只会看到您的品牌和您的价格。
从 API 密钥到您的首次销售
实现可用的经销商集成的四个步骤。
生成 API 密钥
创建一个免费的 VRNUM 账户，并在开发者选项卡中生成一个密钥。每个账户只允许一个活跃密钥。
为钱包充值
使用加密货币充值。每笔订单会从您的余额中扣除——无需发票，无需手动计费。
阅读目录
调用 GET /catalog 获取实时国家、订阅条款和价格。在显示前添加您的加价。
按需配置
使用 Idempotency-Key 调用 POST /numbers 即可立即分配号码，然后通过轮询或使用 Webhook 获取交付信息。
一次请求配置一个号码
clientReference 是您自己的不透明 ID —— 将其附加以便与您的内部客户记录对账订单。
curl -X POST https://vrnum.com/api/v1/numbers \
-H "Authorization: Bearer vrnum_live_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-8841" \
-d '{
"route": "<from catalog>",
"countryCode": "US",
"subscriptionOption": "month",
"clientReference": "order-8841"
}'运行完整订单生命周期所需的一切
目录、配置、短信检索、续订、自动续订以及 Webhook —— 一个一致的 JSON API。
/api/v1/catalog/api/v1/numbers/api/v1/numbers/api/v1/numbers/:id/api/v1/numbers/:id/sms/api/v1/numbers/:id/renew/api/v1/numbers/:id/autorenew/api/v1/webhook/api/v1/balance完整的请求/响应文档和您的密钥在您登录后可在dashboard中查看。
谁在使用虚拟号码 API
任何需要真实电话号码而无需拥有电信基础设施的企业。
电信经销商
在实时运营商库存之上启动您自己的号码即服务品牌，而无需签订任何 SIM 卡合同。
SaaS 与应用程序创始人
通过几个 API 调用，将电话号码配置添加到您的产品入职或验证流程中。
开发机构
为客户应用程序发布号码配置功能，而无需协商自己的运营商协议。
QA 与自动化团队
按需提供一次性但真实的号码，用于自动注册和验证测试套件。
为生产而建，而非演示
幂等键
在超时情况下安全重试 — 同一个幂等键总是返回原始订单，绝不会产生重复。
签名 Webhook
number.provisioned、number.provisioning_failed 和 sms.received 事件，使用 X-VRNUM-Signature（HMAC-SHA256）签名。
自动重试
失败的 webhook 投递会按照退避计划重试（5 分钟、30 分钟、2 小时、6 小时、24 小时），然后再放弃。
透明的速率限制
每个密钥每分钟 60 次请求，每个响应都带有 X-RateLimit-* 头，因此您可以可预测地进行退避。
钱包资金计费
API 访问无需发票或订阅——订单成功后立即从余额中扣除。
稳定的错误代码
每个错误都返回标准化的 JSON 代码，您的集成可以可靠地进行切换，而不仅仅是 HTTP 状态。
常见问题
我可以以自己的品牌转售 VRNUM 虚拟号码吗？
可以。API 只返回您的转售价格——您的客户永远看不到 VRNUM 的内部成本或底层运营商来源。您可以为每个国家和服务设置自己的加价。
我如何获取虚拟号码 API 的访问权限？
创建一个免费的 VRNUM 账户，打开开发者选项卡，然后生成 API 密钥。无需等待审批，无月度 API 费用——只有在您开通号码时才会从您的钱包余额中扣款。
API 使用什么认证方式？
Bearer 令牌认证。在每个请求中，将您的 API 密钥作为 Authorization: Bearer 头或 X-API-Key 头发送。
如果请求超时，会存在重复订单的风险吗？
不会。每个购买端点都接受 Idempotency-Key 头——使用相同的密钥重试同一请求时，您会收到原始订单，而不会产生重复收费。
如何在号码准备就绪或收到短信时收到通知？
在开发者选项卡中注册 webhook URL。VRNUM 会将签名事件（number.provisioned、number.provisioning_failed、sms.received）POST 到您的端点，并会自动重试失败的发送。
API 的速率限制是多少？
每个密钥每分钟 60 次请求。每个响应都包含 X-RateLimit-Limit、X-RateLimit-Remaining 和 X-RateLimit-Reset 头，以便您能够安全地进行退避。