列出覆盖区域的号码前缀

开始之前

使用 getareas 选择覆盖区域。从其响应或返回的 next_function 中复制区域 ID。对于美国或加拿大的覆盖区域，可使用 getstates 将结果限定为某个州或省。

解读结果

检查 JSON 响应体中的 status.code，同时检查 HTTP 状态。成功的结果位于 response 数组中。默认响应按名称排序。available 是估算值，目录标志不能代替对所选号码实际功能和注册要求的核查。

选择下一步操作

使用未分组的结果。当 returns_numbers 为 1 时，返回的 next_function 指向号码搜索。当该值为 0 时，号码在订购时分配，路径指向订购操作。发送请求前，请检查该操作及其要求：订购请求可能会从您的账户扣费。不要自动向每个返回的路径发送请求。

此处不包含价格。购买前，请查看相关报价、所需文件和订购说明。请保留返回的单个前缀 ID 和报价 ID，不要根据显示的电话号码前缀自行构造这些 ID。

高级显示选项

compact=1 返回随机打乱顺序的样本，最多包含 100 行，并非更大结果集中的一页。分组会生成汇总行和合成 ID；选择单个前缀时，请使用常规的未分组响应。不要根据抽样或分组结果声称已列出全部库存或确定了准确的功能。

请求

通过 HTTPS 使用已启用的 API 账户凭据。支持 Basic 身份验证和已启用的 API 账户 bearer 令牌；仍受账户限制约束。

使用 GET，并通过查询字符串发送可选参数。不要依赖以表单请求体传参的回退机制。

curl --fail-with-body --silent --show-error \
  --user "$API_USER:$API_PASSWORD" \
  "https://api.multitel.net/v3/getprefixes/$AREA_ID?state=NY"

路径参数
名称	类型	是否必填	说明
`area_id`	string	是	从 getareas 或其 next_function 中复制区域标识符。请将其视为不透明值；不要自行构造该值或对其进行哈希运算。

查询参数
名称	类型	是否必填	说明
`state`	string	否	仅适用于 US 和 CA 的覆盖区域。使用 getstates 返回的州或省代码，或该州或省的全名。代码不区分大小写；名称匹配会忽略大小写和重复的空白字符。用于其他国家或传入无法识别的非空值时，会返回 API 错误。
`compact`	string	否	可选的抽样模式：1、true 或 on。结果顺序随机打乱，最多包含 100 行。如需完整结果列表，请省略此参数；此端点不提供分页或游标。
`group`	integer	否	高级显示汇总：取值 1 至 6 会合并结果行，并返回经掩码处理的显示前缀。分组 UUID 是合成值，不能与单个前缀 ID 互换使用。在选择用于号码搜索或订购的前缀之前，请先发起未分组的请求。常规流程中请省略此参数。
`pid`	string	否	由 MultiTEL 提供的可选库存选择器，采用数字形式或受支持的 32 字符十六进制形式。常规使用时请省略。无法识别的值会被静默忽略。该值不是电话号码前缀，也不是资费方案 ID。

响应

采用标准的 status/response JSON 封装结构。status.results 统计返回的行数，包括抽样或分组后的行数。response 包含前缀对象。不返回价格字段。在常规的未分组响应中，uuid 是前缀 ID；area_uuid 和 country_uuid 是返回的标识符；prefix 和 name 是显示信息；available 是可用情况的估算值，并不表示已预留；needs_registration 和 restrictions 描述注册信息；sms_coverage、is_mobile 和 number_type 是目录中的提示信息，不保证某个具体号码具备相应功能。number_type 可能为空，也可能是其他目录字符串，因此不要要求其必须属于固定的枚举集合。state 是字符串，可能为空或采用目录中的格式。latitude 和 longitude 可能为空。metered 和 overflow 是目录标志，并非金额。returns_numbers 用于选择号码列表路由 (1) 或订购时分配号码的路由 (0)。next_function 标识该下一步路由。分组响应还包含合并后的功能信息，其中包括回退功能值；不要将这些信息理解为每个号码都经过验证具备的功能。

此响应结构仅供示例，并非实时账户数据或当前报价。

{
  "status": {
    "code": 200,
    "msg": "",
    "results": 1
  },
  "response": [
    {
      "uuid": "PREFIX_ID_FROM_RESPONSE",
      "area_uuid": "AREA_ID_FROM_RESPONSE",
      "country_uuid": "COUNTRY_ID_FROM_RESPONSE",
      "prefix": "+1212",
      "name": "Example area",
      "metered": 0,
      "overflow": 0,
      "needs_registration": 0,
      "restrictions": "",
      "state": "NY",
      "country_iso": "US",
      "is_mobile": 0,
      "number_type": "local",
      "latitude": "",
      "longitude": "",
      "available": 12,
      "sms_coverage": 1,
      "returns_numbers": 1,
      "next_function": "v3/getnumbers/PREFIX_ID_FROM_RESPONSE"
    }
  ]
}

错误

404: Invalid area ID: 请通过查询获取当前有效的区域 ID。
404: State filter is only available for US and CA: 对于其他国家，请省略 state。
404: Invalid state: 请使用 getstates 为该国家返回的州或省。
404: No prefixes found: 未返回匹配的目录行。这并不证明某个具体号码永远无法订购。
500: 错误：'Failed loading prefixes'：目录查询失败。请稍后重试；如果问题持续存在，请联系支持团队。

可用情况与副作用

这是查询步骤，并非订单确认。系统可能通过进一步查询目录来刷新可用情况，因此响应延迟可能有所不同。
不返回价格。下单前，请获取适用的号码报价或订单报价，并查看注册要求。
不要将 available 视为精确的库存数量，不要将零值理解为在所有情况下都禁止订购，也不要将查询成功视为已预留号码。可用情况可能在订购前发生变化。