企业税号CNPJ与个人税号CPF在线校验:BrasilAPI商业数据API快速接入教程

原创2026-09-21 20:46:221,616 阅读
文章标签:后端

企业税号CNPJ与个人税号CPF在线校验:BrasilAPI商业数据API快速接入教程

如果你需要在线校验巴西的企业税号 CNPJ 或个人税号 CPF,开源项目 BrasilAPI 是一个理想选择:它免费聚合巴西公共数据,提供开箱即用的 RESTful 接口,几行代码即可完成税号校验与企业工商信息查询,无需自己对接官方数据源。

BrasilAPI 开源项目标志:巴西公共数据 RESTful API 聚合服务

为什么选择 BrasilAPI 做税号校验?

BrasilAPI(口号是"Vamos transformar o Brasil em uma API?")把巴西的各类公共数据统一封装成低延迟的 API 端点,核心优势对新手非常友好:

  • 免费开源:基于 Next.js 构建,MIT 协议,可在线调用也可本地部署;
  • 零配置:CNPJ、CPF 等端点已内置缓存、CORS、防火墙与统一错误处理,直接 GET 请求即可;
  • 错误语义清晰:使用 400(格式错误)、404(查无此号)等标准状态码,便于程序化判断。

CNPJ 企业税号查询:一个接口拿到工商全貌

CNPJ 是巴西联邦税务局为全国法人(Pessoa Jurídica)分配的唯一识别号。BrasilAPI 的查询入口为:

GET /api/cnpj/v1/{cnpj}

示例:/api/cnpj/v1/19131243000197(测试用例中使用的真实企业号,见 tests/cnpj-v1.test.js)。

该接口由 pages/api/cnpj/v1/[cnpj].js](pages/api/cnpj/v1/%5Bcnpj%5D.js) 路由处理,底层通过 [services/cnpj.js 调用"Minha Receita"数据源,返回的 JSON 字段相当丰富:

字段 含义
razao_social / nome_fantasia 企业名称 / 商业名称
situacao_cadastral、descricao_situacao_cadastral 登记状态(如 ATIVA 活跃、BAIXADA 注销)
qsa 股东与管理层名单(含年龄区间、持股比例等)
cnae_fiscal_descricao 主营业务描述
logradouro、municipio、uf 注册地址信息
opcao_pelo_simples、opcao_pelo_mei 是否适用简易税制 / 微型个体户

完整字段定义(含示例响应)可查阅 OpenAPI 文档 pages/docs/doc/cnpj.json。

CPF 个人税号校验:本地验算,秒级返回

CPF(Cadastro de Pessoas Físicas)是巴西个人税号。校验接口为:

GET /api/cpf/v1/{cpf}

例如 /api/cpf/v1/54083180013(也接受带格式的点号与短横线写法)。其核心逻辑在 services/cpf/cpf.js:

  1. 格式检查:必须为 11 位纯数字,否则返回 400 BadRequestError;
  2. 校验位验算:用两个模 11 权重算法验证最后两位,全部相同数字(如 00000000000)一律判为无效;
  3. 地域映射:根据第 9 位数字推断税务局辖区(rf)及对应州(ufs)。

有效时返回:

{
  "cpf": "540.831.800-13",
  "isValid": true,
  "rf": 0,
  "ufs": ["RS"]
}

💡 注意:CPF 校验是纯算法验算,只验证号码数学上是否成立,并不代表该号真实存在;而 CNPJ 查询是真实数据库检索,能反映企业实际状态。

错误处理速查表

两个端点的错误响应都遵循统一结构(name / message / type),由 errors/ 目录下的错误类与 middlewares/errorHandler.js 统一格式化:

场景 状态码 示例 message
CNPJ 位数/格式错误 400 CNPJ 123 inválido.
CNPJ 格式正确但不存在 404 CNPJ 00.000.000/0000-00 não encontrado.
CPF 位数错误或校验位不符 400 CPF 123 inválido.

对应测试用例分别见 tests/cnpj-v1.test.js 与 tests/cpf-v1.test.js,可直接照抄作为接入自测脚本。

本地部署:三步跑起自己的税号校验服务

如果希望把接口部署在自己服务器上,只需三步:

第一步:克隆仓库

git clone https://gitcode.com/gh_mirrors/br/BrasilAPI.git

第二步:安装依赖(要求 Node.js 24.x,见 package.json 的 engines 字段)

npm install

第三步:启动开发服务器

npm run dev

启动后访问 http://localhost:3000/api/cnpj/v1/19131243000197 即可得到完整企业数据。运行测试套件可用 npm run test:unit。

项目结构导读:看懂接口是怎么组织的

BrasilAPI 的每个 API 领域都遵循四件套结构(详见 docs/ENDPOINT_GUIDE.md),以 CPF/CNPJ 为例:

掌握这个规律后,你扩展或理解 CEP、DDU、银行等其他端点都会非常轻松。

常见问题(FAQ)

Q:接口收费吗? A:开源免费。项目方仅提醒不要做大规模爬虫式请求,保持真人查询量级即可(见 README.md 使用条款)。

Q:CNPJ 查不到企业是什么情况? A:会返回 404 与 NotFoundError,说明该号在数据源中不存在——这本身就是一次有效的"企业真实性"校验。

Q:能在浏览器前端直接调用吗? A:可以。所有端点都开启了 CORS(access-control-allow-origin: *),前端 JS 可直接 fetch。

小结

用 BrasilAPI 接入税号校验非常轻量:CNPJ 一个 GET 请求拿齐企业登记、股东、税务信息,CPF 一个 GET 请求完成格式与校验位验证。无论是做风控、表单校验还是对账系统,这套免费 API 都能帮你省下自建数据源的麻烦 🚀

登录后查看全文
BrasilAPI