查找可用的手机号码

确认已启用手机号码库存

仅在您的客户账户已启用手机号码库存后再使用此搜索。请通过账户的发现工作流获取当前的单个手机前缀。受支持的路径会为该前缀请求无线库存。它不依赖于匹配的固网路由元数据记录。如果您不确定您的账户或前缀是否已启用，请联系支持团队。

当前的旧版路由并不能可靠地拒绝每一个不符合条件的请求。未启用手机号码库存的账户可能会收到普通库存，而响应中仍显示 info.is_mobile: 1。免费电话前缀也可能带着该标签进入免费电话库存分支。请勿仅凭此标签来判定手机业务，也不要向此端点发送普通前缀或免费电话前缀。请使用账户已确认的手机目录和已启用的工作流。

将每个号码与其自身的价格选项保持对应

对于每个候选号码，请将 number、info.uuid 以及同一条目的 price 列表保持在一起。响应中还包含前缀/区域/国家元数据、合约条款和注册限制。候选号码按其第一个价格选项的月费升序排列；价格相同时不保证顺序稳定。请勿用区域 ID 或前缀 ID 替换返回的号码 ID，也不要将其与其他候选号码的价格 ID 配对。

完整响应可能包含额外的元数据和价格字段。返回的 features、通道值和 restrictions 用于描述候选号码；它们并不保证通话、SMS、MMS 或传真已经可用。账户权限、注册以及所选服务套餐仍然适用。请勿将示例中的占位符视为有效的 ID 或价格。

使用较小的正数数量

请从数量 1 开始。正常的供应商请求会将非正数数量规范化为 1，并将上游值上限设为 300，但后续的结果处理仍使用原始输入。因此数量为零时可能会请求上游库存却不返回任何候选号码。其他旧版分支并不会一致地执行所请求的结果数量。请勿依赖单一的通用最大值，也不要发送负数、小数或非数字值。此路由未记录任何受支持的公共搜索筛选器或价格 ID 请求体参数。

区分无库存与查询失败

404 响应可能表示库存不可用、服务已禁用、供应商查询失败或目录记录无效。请将超时或供应商故障视为可用性未知，而不是已确认的零库存。在适当时刷新选择并采用退避策略重试。避免反复轮询每个交换局。单独的手机库存数量端点只是一个快照提示，不必与此账户候选列表的长度一致。

购买前请重新核查

搜索不会预留库存。经审核的分支会尝试排除已购买的号码，但本地预留查询失败时，此类候选号码仍可能留在结果中。可用性、所有权、已批准的定价和注册必须由购买工作流进行检查。请使用新的选择配合受保护的购买请求，并在任何不确定的购买结果之后、重试之前先核对账户库存。切勿仅因为返回了某个候选号码就进行购买。

请求

请从允许的源 IP 地址通过 HTTPS 使用已启用的 API 账户。客户账户还必须启用手机号码库存；仅有 API 身份验证并不会启用它。

在 URL 路径中携带当前的单个前缀标识符和正整数数量进行 GET 请求。省略时数量默认为 1。请使用数量为 1 的示例；此路由不会一致地验证或强制执行通用的结果上限。

curl --fail-with-body --silent --show-error \
  --user "$API_USER:$API_PASSWORD" \
  "https://api.multitel.net/v3/getmobiles/$PREFIX_ID/1"

响应

除 HTTP 状态外，还请检查 JSON 响应体中的 status.code 和 status.msg。成功时，response 是号码候选列表，status.msg 为 Results: 后跟返回的数量，status.results 是序列化列表的长度。候选号码的价格因账户而异。该示意性的简化示例使用占位符，而非真实库存或资费报价。号码包含不带加号的国家代码；标识符为不透明字符串。

示意性的响应结构；并非实时账户数据或当前报价。

{
  "status": {
    "code": 200,
    "msg": "Results: 1",
    "results": 1
  },
  "response": [
    {
      "number": "12025550123",
      "info": {
        "uuid": "NUMBER_ID",
        "prefix_uuid": "PREFIX_ID",
        "country_iso": "US",
        "is_mobile": 1
      },
      "price": [
        {
          "uuid": "PRICE_ID",
          "monthly_price": "ACCOUNT_MONTHLY_PRICE",
          "setup_price": "ACCOUNT_SETUP_PRICE",
          "per_minute": "ACCOUNT_INCOMING_RATE",
          "channels": "PLAN_CHANNELS"
        }
      ],
      "features": [
        "voice",
        "sms",
        "mms",
        "t38"
      ]
    }
  ]
}

错误

• 404：前缀 ID、国家或区域无效：请刷新单个手机前缀的选择。
• 404：未找到号码：可能表示没有可用库存、服务已禁用、供应商查询失败、选择不受支持或账户受限。这并不能证明权威的库存数量为零。

可用性与副作用

• 搜索不会租用或预留号码，经审核的路径也不会扣除购买金额。它会联系库存供应商，可能需要一些时间。
• 成功的搜索会写入与账户相关的号码和价格缓存条目以及查询日志。重复搜索并不构成预留、价格锁定或购买。
• 必须针对所选账户和号码审核返回的价格、条款、限制和功能。功能标签并不能证明已激活、已获得消息发送批准或服务功能已经过测试。