按前缀订购电话号码

按前缀订购

当前缀目录指示您按前缀订购指定数量的号码，而不是逐个选择可用号码时，请使用此操作。请先查看国家、地区或州，以及前缀。请保留同一份最新结果中的前缀标识符和资费方案。如果要购买从可用号码列表中选定的某个号码，请使用购买选定的电话号码。

此请求可能购买号码并产生费用。它不是询价、预留或模拟执行请求。提交前，请查看开通费、月费、呼入每分钟费率、包含的分钟数、通道数、登记要求以及账户的购买限制。目录结果不会预留库存或锁定价格。履行订单前可能会进行账户资金检查；仅凭错误本身，无法证明未发生购买或账户充值。

提交购买请求

请从获准的源 IP 地址，通过 HTTPS 使用已启用的 API 账户。根据当前在目录中的选择以及已获批准的接收配置来设置变量。以下命令会购买一个号码。

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --data-urlencode 'quantity=1' \
  --data-urlencode "price_id=$PRICE_ID" \
  --data-urlencode "channels=$CHANNELS" \
  --data-urlencode "reference=$ORDER_REFERENCE" \
  --data-urlencode "uri=$VOICE_URI" \
  "https://api.multitel.net/v3/order/$PREFIX_ID"

上面展示的是表单 POST 请求。当 Content-Type 为 application/json 时，协调处理程序也会读取 JSON 对象。JSON 字段会覆盖同名的表单或请求字段。请始终使用同一种编码方式，不要在查询参数和请求体中发送相互冲突的值。

接收和续费设置

请选择与您在门户中为该号码使用的设置相同的接收设置。这些是高级配置值，并非创建托管 PBX 或呼入中继的指令。请复用已知可用的账户配置，并在购买后核查已保存的号码。仅仅购买获受理，并不能证明语音或短信接收功能正常。

这些字段会经过规范化处理并传递给结账流程，但不同库存处理路径保存这些字段的方式有所不同。当前订单路由并未提供《购买选定的电话号码》指南中的严格报价上限字段作为同等的保护措施。请使用账户的购买权限和价格限制，并检查最终生成的号码配置。

读取完整结果

即使 HTTP 请求成功，也请解析 JSON 响应体并检查 status.code 和 status.msg。此路由会自行写入 JSON 响应，共用的响应辅助程序也不一定会将应用状态码映射为 HTTP 状态。应用状态码可能是 JSON 数字，也可能是数字字符串。不要要求响应必须包含 status.results；正常的订单结果中没有此字段。

{
  "status": {"code": "200", "msg": ""},
  "response": {
    "id": "o_fictional_example",
    "numbers": ["12025550123"],
    "price": {
      "per_minute": "0.01",
      "free_minutes": 0,
      "setup_price": "1.25",
      "monthly_price": "2.50",
      "channels": 2
    },
    "features": ["voice"],
    "needs_registration": 0,
    "restrictions": "",
    "registration_requirements": null
  }
}

上面的标识符、号码和价格均为虚构示例。请将订单 ID 视为不透明标识符，不要解读其内部结构。numbers 列出了此响应报告已购买的号码；请将列表长度与您请求的数量进行比较。价格金额为字符串，此响应会将金额费率四舍五入到小数点后两位，包括 per_minute；要获取原始精度的费率，请使用最新目录。包含的分钟数和通道数可能以数值或数字字符串的形式返回。

价格数据块描述的是用于构建响应的所选方案，并非每个号码的详细账单，也不是订单总额。多个候选库存号码可能对应不同的方案。请逐一核对已购号码和账户交易，不要直接将此数据块中的价格乘以数量，就认为可以据此确认最终总额。

部分购买和不确定的结果

应用状态码为 200 时，也可能伴随警告，且返回的号码数量少于请求数量。后续失败不会撤销已购买的号码。请保留返回的订单 ID、号码和消息。请在号码库存和账户交易中核对这些号码，再决定是否订购剩余数量。

提交后出现超时、请求连接中断、响应格式错误或其他错误，并不能证明未发生任何操作。即使使用相同的参考标识，也不要自动再次提交购买请求。请保留原始请求、参考标识以及任何返回的订单 ID，检查号码库存和账户交易；如果结果仍不确定，请联系支持团队。

尚未确认的订单可能返回应用状态码 400，并提示订单仍在确认中。请保留返回的订单 ID 并核对此次购买；这并不是要求您再次提交。已记录订单的恢复机制会在内部跟踪原始订单。向此操作发送新请求会创建一次独立的购买尝试，而不是根据您的参考标识继续处理原订单，因此可能购买更多号码并产生费用。不要通过重复提交购买请求来查询状态或搜索库存。

登记和激活

已购买或已分配的号码仍可能需要登记或激活。如果 needs_registration 为 1，请检查 restrictions 和 registration_requirements。后者可能指明需使用的接口 v3/get_requirements，并提供 country 和 number_type 的值。请完成适用的身份或地址验证流程，并确认号码状态后，再依赖其接听来电或接收消息。

features 描述的是对外宣称的功能；它并不能验证实际路由、短信营销活动审批、短信送达或传真接收情况。请检查已保存的接收设置，并在号码激活后进行适当的服务测试。

订单回调

回调通过 POST 发送包含订单状态和响应的 JSON；如果您提供了参考标识，其中也会包含该标识。对于报告为已购买的结果，系统会发送回调，包括部分购买的结果。回调失败不会回滚购买。回调发送可能会重试，因此请按订单 ID 处理重复通知并核对号码，不要再次发起购买。

此路由不会添加基于密码学的回调签名。请将回调视为提醒您与通过身份验证后获取的号码库存进行核对的通知，而非可独立用于收费、开通服务或授予访问权限的授权。不要在回调 URL 中放置 API 凭据。使用不同的回调 URL 再次提交购买请求不会更新原始订单，而是会创建一次独立的购买尝试。请求支持团队调查回调时，请保留原始订单 ID。

需要处理的失败情况