注册并联系客服，免费领取 100 次检测。免费注册
CarrierLookup
CarrierLookup 工作流示意图：原始归属运营商查询 API：提交文件任务与轮询 CSV 结果
本文所述工作流的示意图（CarrierLookup）。

本文为开发者提供关于 CarrierLookup 批量文件任务的操作指南：包括提交 TXT 或 CSV 文件、指定国家/地区、轮询任务状态以及读取最终的 CSV 结果。

CarrierLookup 批量原始归属运营商查询 API 是一项异步文件任务。请向 POST /api/v1/bulk-tasks 发送多部分（multipart）请求，并将 country 字段置于文件字段之前，随后通过 GET /api/v1/bulk-tasks/{id} 轮询任务状态（频率不得超过每 30 秒一次），直至状态变为 success 或 failed。任务成功后将返回一个可下载的 CSV 文件，其中包含原始运营商、底层运营商、号码类型及分配地信息。该路径适用于针对单一国家/地区的大规模号码列表。产品限制适用，请务必先查阅 API 文档以确认相关限制。

在调用 API 前准备文件

一份整洁的文件比任何重试逻辑都能节省更多时间。批量路径接受单列 TXT 或 CSV 文件，每行包含一个带国家代码的号码。系统不接受 XLSX 格式，请先将电子表格导出为纯文本或 CSV。

请确保每行均为带国家代码的数字。由于任务需选择单一国家/地区，且该范围之外的号码会被排除，因此请确保列表主要属于同一个国家/地区。

简要的准备流程：

  1. 导出单列数据，并删除标题或备注。
  2. 将每一行规范化为带国家代码的数字格式。
  3. 按国家/地区拆分主列表，为每个国家/地区创建一个独立文件。
  4. 根据 API 文档中的当前限制检查文件。文档中记录的默认文件大小上限可能会被实时服务返回的限制所覆盖，因此以实时数值为准。

预处理将排除无效行、重复项、无国家代码的号码以及所选国家/地区之外的号码，这些号码均不计费。提前自行清理数据能让您更清晰地了解实际提交的行数。请保留所提交文件的副本及其行数，以便后续将最终的 CSV 与源列表进行核对，从而查看哪些行被剔除。

通过多部分请求提交任务

请从受信任的服务器通过 POST /api/v1/bulk-tasks 提交任务。使用 X-API-Key 请求头进行身份验证，切勿在浏览器代码中暴露密钥。

请求体为包含两个部分的多部分表单数据：所选国家/地区和文件。顺序非常重要，请务必将国家/地区部分置于文件部分之前。许多 HTTP 客户端根据字典构建请求体，其顺序可能遵循插入顺序，请检查您的客户端如何序列化该数据。

使用 curl 的调用示例：

curl -X POST https://carrierlookup.online/api/v1/bulk-tasks \
  -H "X-API-Key: $CARRIERLOOKUP_API_KEY" \
  -F "country=GB" \
  -F "file=@uk_numbers.csv"

请使用与列表相符的 ISO 国家代码。响应将提供一个用于轮询任务的引用标识，请将其与您的作业记录一并存储。请勿自行添加额外字段、号码 JSON 数组、Webhooks 或取消调用。仅文件提交和状态读取是受支持的操作。

轮询任务状态，避免频繁请求

使用 GET /api/v1/bulk-tasks/{id} 读取状态。任务处于以下三种状态之一：processing、success 或 failed。

轮询频率不得超过每 30 秒一次。更频繁的循环不会加快处理速度。系统未记录常规完成时间，也没有单号码进度反馈，因此请围绕状态构建循环，而不是基于对持续时间的猜测。

import time, requests

def wait_for_task(task_ref, headers):
    while True:
        r = requests.get(f"https://carrierlookup.online/api/v1/bulk-tasks/{task_ref}", headers=headers, timeout=30)
        state = r.json()["data"]["status"]
        if state in ("success", "failed"):
            return state
        time.sleep(30)

请将此示例中的字段名称视为占位符，并以 API 文档中的确切响应格式为准。在生产环境中，请添加符合您作业计划的最大等待时间，存储最后观察到的状态，并在任务处于 processing 状态的时间超过您的容忍度时触发操作员警报。

下载并读取 CSV

当状态为 success 时，即可下载结果。您将收到一个 CSV 文件，而非 ZIP 压缩包。文件中包含已返回结果的号码的标识符、运营商、底层运营商、号码类型、国家代码、地区和城市。

三条读取规则：

  • 标识符不含加号。 它仅为带国家代码的纯数字，且不含空格。在合并数据前，请以相同方式规范化您自己的键值。
  • 空单元格表示无法判定。 请将其保留为无法判定值，切勿将其转换为否定结论。
  • 运营商为原始分配信息。 它并非携号转网后的当前运营商。地区和城市描述的是号码分配的地理位置，而非个人或设备当前所在位置。

请先将文件加载到暂存表中，然后按键值合并到您的联系人记录中。请在暂存表中保留任务引用和运行日期，以便后续审计时能确定哪次运行产生了哪些值。请记住，CSV 中没有列说明号码是否可达，您自己的规则也不应据此进行推断。

失败、预留与余额

批量任务在提交时会预留预估费用，仅对返回结果的号码进行扣费。任务完成后，预留中未使用的部分将退回至同一钱包，失败的任务则会退回全部预留金额。这是余额内的核对过程，并非购买退款。

任务可能会在准备阶段失败，例如当有效的移动号码预估数量过少或未满足其他接受条件时。发生这种情况时，请检查文件是否存在上述排除项，修复列表后提交新任务，而不是盲目重试同一文件。

在提交前请检查 GET /api/v1/balance。它可以在不扣费的情况下读取余额。在定时作业中，请将余额与预期的列表大小进行比较，如果余额不足则提前停止，因为无法满足的预留会导致任务中断。对于国家/地区拆分后剩余的小规模号码组，使用 POST /api/v1/batch-check 进行同步多号码查询可能比再次执行文件任务更为简便。

常见问题解答

开发者如何提交批量任务以避免多部分请求错误？

在多部分请求体中，将 country 字段置于 file 字段之前，以每行一个带国家代码号码的纯 TXT 或 CSV 格式发送文件，并从受信任的服务器通过 X-API-Key 请求头携带 API 密钥。请检查您的 HTTP 客户端如何对表单字段进行排序。

开发者如何选择任务状态的轮询间隔？

轮询状态接口的频率不得超过每 30 秒一次，并在状态变为 success 或 failed 时停止。系统未记录常规完成时间或单号码进度，因此请设置您自己的最大等待时间，并在任务超出该时间时向操作员发出警报。

团队如何处理失败的批量任务？

将失败视为关于文件或接受条件的信号。由于预留金额会全额退回，请检查列表是否存在无效行、重复项、缺失的国家代码以及所选国家/地区之外的号码，修正后提交新任务。

了解更多

选择符合您工作流程下一步的产品信息。

参考来源