Brasil Hub for n8n

Query Brazilian public data (CNPJ, CEP, CPF, Banks, DDD, Holidays, FIPE, IBGE, NCM, PIX, Câmbio, Taxas) + generate fake test data — automatic multi-provider fallback, zero credentials.

v1.4 — 13 resources, 28 operations, 25 providers + local fake data generation. The API is stable and follows semantic versioning.

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

Example Output

{
  "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": "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 configurable timeout (default: 10 seconds, range: 1–60s). The _meta.strategy field tells you if the response came from the primary provider (direct) or a fallback.

FAQ

Do I need API keys or credentials?
No. All data providers used by Brasil Hub are free public APIs. Just install the node and start querying. Zero configuration needed.

What happens when a provider API goes down?
Brasil Hub automatically tries the next provider. For CNPJ queries, there are 7 fallback providers. You can see which provider responded in the _meta.strategy field ("direct" or "fallback").

Can I choose which provider to use first?
Yes. Each resource with multiple providers has a "Primary Provider" dropdown. Pick your preferred provider and it becomes the first one tried.

Does it work with n8n AI Agents?
Yes. Brasil Hub has usableAsTool: true, so you can add it as a tool in any n8n AI Agent workflow. The AI Summary output mode for CNPJ returns flat English fields optimized for LLM consumption.

Can I query exchange rates and interest rates?
Yes. The Câmbio resource fetches exchange rate quotations from the Central Bank (BCB) by currency and date. The Taxas resource queries official interest rates and indices (Selic, CDI, IPCA). Both use BrasilAPI as provider.

Can I generate fake test data?
Yes. The Fake resource generates realistic Brazilian test data locally (no API calls): person profiles with valid CPF, company profiles with valid CNPJ, or standalone CPF/CNPJ numbers. All checksums are correct.

How does Brasil Hub compare to using HTTP Request nodes?
With HTTP Request nodes you need to handle each API individually, normalize different response formats, implement fallback logic, and deal with rate limits. Brasil Hub handles all of this in a single node with consistent output.

What n8n versions are supported?
n8n 1.0+ with Node.js 20 or 22. The node follows semantic versioning -- minor updates add features, patch updates fix bugs, and no breaking changes within a major version.

Compatibility

Development

git clone https://github.com/luisbarcia/n8n-nodes-brasil-hub.git
cd n8n-nodes-brasil-hub
npm install
npm test          # 1626 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

License

MIT — Luis Barcia