企业税号CNPJ与个人税号CPF在线校验:BrasilAPI商业数据API快速接入教程
企业税号CNPJ与个人税号CPF在线校验:BrasilAPI商业数据API快速接入教程
如果你需要在线校验巴西的企业税号 CNPJ 或个人税号 CPF,开源项目 BrasilAPI 是一个理想选择:它免费聚合巴西公共数据,提供开箱即用的 RESTful 接口,几行代码即可完成税号校验与企业工商信息查询,无需自己对接官方数据源。
为什么选择 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:
- 格式检查:必须为 11 位纯数字,否则返回
400 BadRequestError; - 校验位验算:用两个模 11 权重算法验证最后两位,全部相同数字(如
00000000000)一律判为无效; - 地域映射:根据第 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 为例:
- 路由层:pages/api/cnpj/v1/[cnpj].js、pages/api/cpf/v1/[cpf].js
- 业务层:services/cnpj.js、services/cpf/cpf.js
- 文档层:pages/docs/doc/cnpj.json、pages/docs/doc/cpf.json
- 测试层:tests/cnpj-v1.test.js、tests/cpf-v1.test.js
掌握这个规律后,你扩展或理解 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 都能帮你省下自建数据源的麻烦 🚀
