批量电话号码查询：同步多号码请求与批量文件任务
比较 CarrierLookup 的同步多号码请求与异步批量文件任务，从输入方式、耗时、输出及适用场景进行对比，助您为列表选择合适的处理路径。
本文对比了 CarrierLookup 的两种批量处理路径——同步多号码请求与异步批量文件任务，并根据列表规模和工作流提供了决策指南。
使用 CarrierLookup 进行批量电话号码查询有两种不同的路径。同步多号码请求可通过 API 一次处理最多 100 个号码，或通过仪表板处理最多 500 个号码，并在同一响应中返回排序后的结果。批量文件任务则针对选定国家/地区，通过 TXT 或 CSV 文件进行异步处理，最终生成一个可下载的 CSV 文件。对于小规模群体和实时工作流，请选择多号码请求；对于大规模列表，请选择文件任务。两者均返回原始归属运营商和号码分配背景信息，而非携号转网后的当前运营商，也不提供可达性信号。
两种批量路径，两种不同的任务
寻求批量电话号码查询的团队通常认为所有批量工具的工作方式都相同。CarrierLookup 特意提供了两种形式，混淆两者是规划中最常见的错误。
同步多号码请求是一种交互式调用。您发送一组 E.164 格式的号码，等待并接收一个有序的答案。组内的号码可以来自不同国家，无需单独选择国家。
批量文件任务是一种作业。您准备一个单列的 TXT 或 CSV 文件，选择一个国家，提交任务，稍后再获取结果。工作在后台进行，输出是一个文件而非响应主体。
| 问题 | 同步多号码请求 | 批量文件任务 |
|---|---|---|
| 运行位置 | API 和仪表板 | API |
| 输入 | E.164 格式号码 | TXT 或 CSV，每行一个号码 |
| 国家/地区 | 允许混合国家 | 选定一个国家 |
| 耗时 | 在同一响应中返回答案 | 提交后轮询 |
| 输出 | 有序结果 | 一个可下载的 CSV |
两种路径均适用各自的产品限制，因此在规划任务规模前，请查阅当前的 API 文档。
同步多号码请求的行为方式
请从受信任的服务器使用 POST /api/v1/batch-check，并在 X-API-Key 标头中发送 API 密钥。仪表板在浏览器中为较大规模的组（最多 500 个号码）提供相同的功能。
每个号码必须以 E.164 格式书写：以加号开头，后跟国家代码和用户号码，中间无空格或分隔符。格式错误的号码会因格式问题被拒绝。这是需要修复的格式问题，而非号码没有运营商的结论。
响应会报告提交的号码数量、成功数量和失败数量，随后按您发送号码的顺序返回结果。顺序非常重要，因为它允许您将每个答案映射回您自己表格中的对应行，而无需连接键。
以下两种行为值得注意：
- 标记为不存在的结果意味着该号码没有返回正常结果。这并非声明该号码无效或已停机。
- 如果整个请求超时，则作为一个整体失败。不会返回部分结果，且全额费用将退回至您的余额。
由于该调用是同步的，除非您已处理超时，否则请勿将其置于用户等待页面加载的路径中。
批量文件任务的行为方式
请使用带有 multipart 主体的 POST /api/v1/bulk-tasks。将国家字段放在文件字段之前，因为在 multipart 提交中顺序很重要。然后使用 GET /api/v1/bulk-tasks/{id} 读取进度。
任务处于以下三种状态之一：processing（处理中）、success（成功）或 failed（失败）。轮询频率请勿超过每 30 秒一次。更频繁的循环只会增加负载而不会加快任务完成速度，且未记录完成时间，因此请根据状态而非时钟进行规划。
在主运行之前，文件会进行预处理。无效行、重复项、缺少国家代码的号码以及超出所选国家范围的号码将被排除，且排除的行不收费。如果文件不符合接受条件，任务也可能在准备阶段失败，此时预留金额将全额退回至您的钱包。
成功后，您将下载一个 CSV 文件，而非 ZIP。其列包括标识符、运营商、底层运营商、号码类型、国家代码、地区和城市。在 CSV 中，标识符是纯数字，包含国家代码且没有加号，因此在将文件连接回数据库之前，请规范化您自己的键。空单元格表示该值不可用。
根据列表规模、国家混合情况和工作流进行选择
请从数据的形态而非原始数量开始考虑。
- 需要立即获得答案的混合国家列表。 使用同步多号码请求。单文件任务会迫使您先按国家拆分列表。
- 本质上属于同一个国家的大规模列表。 使用文件任务。选择国家，提交文件，让预处理程序移除重复项和无关号码。
- 大规模的混合国家列表。 按国家代码拆分，然后为每个国家提交一个文件任务。任何不适合国家文件的内容都可以通过每组最多 100 个号码的多号码请求进行处理。
- 注册或 CRM 条目中的逐条检查。 使用单号码检查，POST /api/v1/check。来自中国大陆、香港和澳门的号码仅支持通过实时单号码检查进行小批量处理，因此请将其路由至该接口，而非多号码请求或文件任务。
批量工作也适用于隔夜或活动间隙运行的批处理作业，因为您可以提交、轮询并收集结果。多号码请求适用于已经在小块数据中处理数据并能将结果直接写回数据库或 CRM 的循环。
两种路径的计费与余额检查
两种路径均使用同一个共享余额，每个已完成的号码按相同的公布费率计费。失败或无法判定的查询不会扣费。已完成但运营商字段均为空的查询仍视为已完成查询，并可能产生费用，因此请勿将空行解读为免费或证明不存在运营商。
文件任务在提交时会预留预估金额，随后仅对返回结果的号码收费。预留金额中未使用的部分，或失败任务的全部预留金额，将退回至同一个钱包。这是您余额内的对账，而非购买退款。
在进行任何大规模提交之前，请使用 GET /api/v1/balance 读取余额。该调用不会产生任何费用，并会告知您预留金额是否足够。将相同的检查添加到计划任务中，以便在余额不足时在运行开始前停止，而不是在管道运行中途失败。
正确读取结果
无论您选择哪种路径，数据的含义都是相同的。运营商是指该号码段最初分配到的运营商。它不是今天为该号码提供服务的网络，因为携号转网可以在不改变原始分配的情况下移动号码。底层运营商和号码类型增加了背景信息，地区和城市描述的是分配地理位置，而非个人或设备当前所在位置。
这使得输出结果可用于分组、路由测试和审核队列。它不是号码可以接收呼叫或消息、号码处于活动状态或号码所有者的证据。
将每个字段存储为原始分配属性，将空值标记为不可用，并避免覆盖您通过其他方式确认的任何字段。将这些字段视为分配背景信息的团队，可以避免日后关于数据承诺内容的争议。
常见问题解答
团队如何决定使用多号码请求还是文件任务？
首先查看列表形态。需要立即获得有序答案的混合国家号码组适合多号码请求。本质上属于同一个国家的大规模列表适合文件任务，该任务在后台运行并最终生成一个 CSV。每种产品都有相应的限制，因此在规划任何路径前，请确认当前的 API 文档。
团队如何处理多号码请求中的结果顺序？
结果返回的顺序与发送号码的顺序一致，因此请保持您自己的列表顺序稳定，并按位置进行匹配。将无法判定（无法判定）的结果视为没有正常结果，而非无效号码，并在修复任何格式问题后仅重试您需要的行。
团队如何避免对批量任务进行无效轮询？
轮询任务状态的频率请勿超过每 30 秒一次，并在状态为 success 或 failed 时停止。未记录完成时间，因此请围绕状态构建作业。成功后，下载单个 CSV 并在将其连接到现有记录之前规范化标识符。
了解更多
选择适合您工作流下一步的产品信息。