brasil-hub

n8n community node for querying Brazilian public data (CNPJ, CEP, CPF, Banks, DDD, Feriados, FIPE, IBGE) with multi-provider fallback

Package Information

Downloads: 0 weekly / 0 monthly
Latest Version: 0.8.0
Author: Luis Barcia

Available Nodes

Brasil Hub icon
Brasil Hub
Query Brazilian public data (CNPJ, CEP, CPF, Banks, DDD, Feriados, FIPE, IBGE) with multi-provider fallback

Documentation

Brasil Hub

Brasil Hub for n8n

Query Brazilian public data (CNPJ, CEP, CPF, Banks, DDD, Feriados, FIPE & IBGE) with automatic multi-provider fallback — zero configuration, zero credentials.

npm version CI Quality Gate Status License: MIT

Development Status: This package is in active development (v0.x). The API is stable but may receive breaking changes in minor versions. Please pin your version in package.json.

Why Brasil Hub?

Most Brazilian public data APIs are free but unreliable. A single provider going down breaks your entire workflow. Brasil Hub solves this:

  • Up to 7 providers per resource — if one fails, the next kicks in automatically
  • Normalized output — same schema regardless of which provider responds
  • No credentials needed — all providers are public APIs
  • AI Agent ready — works as a tool in n8n AI Agent workflows

Installation

In your n8n instance: Settings → Community Nodes → search n8n-nodes-brasil-hub → Install

Or via CLI:

npm install n8n-nodes-brasil-hub

Operations

Resource Operation Description Providers
Bank Query Fetch bank info by COMPE code BrasilAPI → BancosBrasileiros
Bank List List all Brazilian banks BrasilAPI → BancosBrasileiros
CEP Query Fetch address data by CEP number BrasilAPI → ViaCEP → OpenCEP → ApiCEP
CEP Validate Check if CEP format is valid (local, no API) —
CNPJ Query Fetch company data by CNPJ number BrasilAPI → CNPJ.ws → ReceitaWS → MinhaReceita → OpenCNPJ.org → OpenCNPJ.com → CNPJA
CNPJ Validate Check if CNPJ is valid (local checksum, no API) —
CPF Validate Check if CPF is valid (local checksum, no API) —
DDD Query Fetch state and cities by area code BrasilAPI → municipios-brasileiros
Feriado Query Fetch public holidays by year BrasilAPI → Nager.Date
FIPE Brands List vehicle brands by type parallelum
FIPE Models List models for a brand parallelum
FIPE Years List available years for a model parallelum
FIPE Price Get FIPE table price for a vehicle parallelum
IBGE States List all Brazilian states BrasilAPI → IBGE API
IBGE Cities List municipalities by state BrasilAPI → IBGE API

Example Output

CNPJ Query 
{
  "cnpj": "00000000000191",
  "razao_social": "BANCO DO BRASIL SA",
  "nome_fantasia": "DIRECAO GERAL",
  "situacao": "ATIVA",
  "data_abertura": "1966-08-01",
  "porte": "DEMAIS",
  "natureza_juridica": "Sociedade de Economia Mista",
  "capital_social": 120000000000,
  "atividade_principal": {
    "codigo": "6422100",
    "descricao": "Bancos múltiplos, com carteira comercial"
  },
  "endereco": {
    "logradouro": "SAUN QUADRA 5 LOTE B",
    "numero": "S/N",
    "bairro": "ASA NORTE",
    "cep": "70040912",
    "municipio": "BRASILIA",
    "uf": "DF"
  },
  "contato": {
    "telefone": "6134934000",
    "email": ""
  },
  "socios": [
    {
      "nome": "TARCIANA PAULA GOMES MEDEIROS",
      "qualificacao": "Presidente"
    }
  ],
  "_meta": {
    "provider": "brasilapi",
    "strategy": "direct",
    "queried_at": "2026-03-10T12:00:00.000Z"
  }
}
CEP Query 
{
  "cep": "01001000",
  "logradouro": "Praça da Sé",
  "bairro": "Sé",
  "cidade": "São Paulo",
  "uf": "SP",
  "_meta": {
    "provider": "brasilapi",
    "strategy": "direct",
    "queried_at": "2026-03-10T12:00:00.000Z"
  }
}

How Fallback Works

Request → Provider 1 (BrasilAPI)
              ├─ Success → Return normalized data
              └─ Fail → Provider 2 (CNPJ.ws / ViaCEP)
                            ├─ Success → Return normalized data
                            └─ Fail → Provider 3 (ReceitaWS / OpenCEP)
                                          ├─ Success → Return normalized data
                                          └─ Fail → Return error with all failures

Each provider has a 10-second timeout. The _meta.strategy field tells you if the response came from the primary provider (direct) or a fallback.

Compatibility

Version
n8n 1.0+
Node.js 20, 22

Development

git clone https://github.com/luisbarcia/n8n-nodes-brasil-hub.git
cd n8n-nodes-brasil-hub
npm install
npm test          # 709 tests, 99%+ coverage
npm run build
npm run lint

To test locally in n8n:

npm run build && npm link
# In your n8n directory:
npm link n8n-nodes-brasil-hub

See CONTRIBUTING.md for full development guidelines.

Project
Roadmap Planned features (Feriados, more providers)
Changelog Version history
Contributing How to contribute
Security Vulnerability reporting
Governance Decision-making process
Code of Conduct Community standards

License

MIT — Luis Barcia

Discussion