巴西 CNPJ 批量查询脚本

数据采集实战 · Excel 批处理 · BrasilAPI

从 Excel 提取 CNPJ 列表，调用 BrasilAPI 查询企业注册信息，批量导出 CSV 与 JSON 结果。

200

输入记录

199

成功查询

汇总字段

失败记录

01项目简介

这个项目是一个面向巴西企业 CNPJ 税号的批量查询脚本。脚本从 CNPJ-100.xlsx 的指定工作表读取企业记录，提取公司名、CNPJ、经营活动和预计资本等原始字段；随后通过 requests.Session 调用 BrasilAPI 的 CNPJ 接口，补充企业注册状态、法律性质、CNAE 主营业务、开业日期、注册资本、企业规模、地址、联系方式、Simples/MEI 选项等结构化信息。

项目定位是接口批处理与数据清洗脚本，重点在于把 Excel 中不规则排布的线索数据清洗成可复用的企业信息数据集，并保留完整 JSON 原文用于复核。

对应实现包含 cnpj_batch_query_v2.py、CNPJ-100.xlsx 和 cnpj_results/ 导出目录。

02处理流程

Excel 工作表 ↓ 按每 5 行提取一条企业记录字段：序号 / 公司名 / CNPJ / 经营活动 / 预计资本 ↓ CNPJ 清洗 - 去掉 . - / 等分隔符 - 统一为数字串 ↓ BrasilAPI 查询 - GET /api/cnpj/v1/{cnpj} - requests.Session 复用连接 - 20 秒超时 ↓ 字段映射与汇总 - 合并 Excel 原始字段 - 补充 API 返回字段 ↓ 导出结果 - 单企业 JSON - 汇总 CSV - 失败列表 CSV - 完整批次 JSON

03核心功能

Excel 批量读取
使用 pandas.read_excel 读取指定 sheet，并按每 5 行一组解析企业记录。

CNPJ 标准化
通过正则清理 .、-、/，兼容带分隔符的税号格式。

BrasilAPI 查询
调用 https://brasilapi.com.br/api/cnpj/v1/{cnpj}，获取企业注册与经营信息。

节流控制
每次查询后短暂停顿，每 10 条额外等待，降低连续请求对公共接口的压力。

结果留痕
每个成功 CNPJ 单独保存 JSON，便于后续排查、复跑和字段扩展。

失败记录
HTTP 404、超时或异常不会中断批次，会写入失败列表方便人工复核。

04导出成果

脚本运行后在 cnpj_results 目录生成多种结果文件。当前样本中共处理 200 条输入记录，其中 199 条成功查询，1 条因为 BrasilAPI 返回 404 被写入失败列表。

CNPJ_汇总结果.csv第一批查询的结构化结果，共 99 条成功记录。

CNPJ_汇总结果_100-200.csv第二批查询的结构化结果，共 100 条成功记录。

199 个单企业 JSON每条成功查询保存一份原始 BrasilAPI JSON，保留 QSA、CNAE、地址等完整字段。

查询失败列表.csv记录未查到或异常的 CNPJ、原始公司信息与错误原因。

05字段样例

汇总 CSV 会同时保留 Excel 原始字段与 API 补充字段，适合继续做清洗、筛选或人工核验。

字段组	代表字段
Excel 输入	序号、Excel公司名、Excel_CNPJ、Excel经营活动、Excel预计资本
企业身份	CNPJ、API公司全名、商业名称、企业规模、矩阵/分支
注册信息	注册状态、注册状态代码、注册状态日期、法律性质、开业日期
经营信息	主营业务代码、主营业务描述、资本额(BRL)、MEI选项、Simples选项
联系地址	州(UF)、城市、街道、编号、补充地址、街区、邮政编码、电话、邮箱

06关键代码

def clean_cnpj(cnpj):
    return re.sub(r'[.\-/]', '', cnpj)

def query_cnpj(cnpj_raw, session):
    cnpj_num = clean_cnpj(cnpj_raw)
    url = f'https://brasilapi.com.br/api/cnpj/v1/{cnpj_num}'
    r = session.get(url, headers=headers, timeout=20)
    if r.status_code == 200:
        return r.json(), None
    return None, f'HTTP {r.status_code}: {r.text[:200]}'

07技术选型

模块	技术
Excel 读取	Pandas · openpyxl
接口请求	requests · BrasilAPI REST
数据清洗	re 正则 · Python dict 字段映射
导出	csv.DictWriter · json.dump · UTF-8 BOM CSV
运行控制	requests.Session · timeout · time.sleep 节流

08技术难点

Excel 行块解析
源表不是标准一行一条记录，而是每 5 行组成一条企业数据，需要按固定步长抽取。

接口失败不中断
单个 CNPJ 查询失败时记录错误并继续处理后续记录，保证批任务能完整跑完。

字段对齐
将葡语 API 字段转成中文表头，同时保留原始 CNPJ 和 Excel 公司名，方便核对差异。

编码兼容
CSV 使用 utf-8-sig 写入，减少中文 Windows Excel 打开时的乱码概率。