n8n-nodes-cnpj-hub 🇧🇷

> Language: English | Português

Custom n8n node for querying Brazilian CNPJ data through public APIs.

🇧🇷 What is CNPJ?

CNPJ (Cadastro Nacional da Pessoa Jurídica) is the Brazilian national registry of legal entities. It's a unique 14-digit identifier assigned to every company, organization, and legal entity operating in Brazil.

- Format: XX.XXX.XXX/XXXX-XX (e.g., 11.222.333/0001-81)
- Purpose: Official business identification for tax, legal, and regulatory purposes
- Equivalent to: EIN (USA), VAT number (EU), or Company Registration Number in other countries
- Contains: Company registration data, address, business activities, partners, and legal status

This node allows you to easily retrieve comprehensive company information using just the CNPJ number.

🚀 Features

- 🔄 Automatic Fallback: If one API fails, automatically tries others
- ⏱️ Rate Limiting: Configurable delay between requests to avoid blocking
- 📊 5 Public APIs: CNPJ.ws, CNPJA, MinhaReceita, BrasilAPI and ReceitaWS
- 🔍 Smart Validation: Accepts CNPJ with or without formatting
- 🛡️ Robust Error Handling: Advanced error management
- 📝 Detailed Metadata: Information about APIs used and attempts
- 🔄 Data Normalization: Standardized output format across all APIs for consistent workflows

📋 Supported APIs

$3

- URL: https://publica.cnpj.ws/cnpj/{cnpj}
- Features: Most comprehensive API with detailed information about partners, activities and establishments

$3

- URL: https://open.cnpja.com/office/{cnpj}
- Features: Well-structured and organized data

$3

- URL: https://minhareceita.org/{cnpj}
- Features: Detailed data with tax regime information

$3

- URL: https://brasilapi.com.br/api/cnpj/v1/{cnpj}
- Features: Official Brazilian government API

$3

- URL: https://receitaws.com.br/v1/cnpj/{cnpj}
- Features: Simple and fast API for basic queries

💻 How to Use

$3

1. Clone this repository:
``bash
git clone https://github.com/douglassiqueira/n8n-nodes-cnpj-hub.git
cd n8n-nodes-cnpj-hub
`

2. Install dependencies:
`bash
npm install
`

3. Build the project:
`bash
npm run build
`

4. Install the node in n8n:
`bash
npm link
`

$3

1. Add the "CNPJ HUB" node to your workflow
2. Choose strategy:
- Automatic Fallback (recommended): Tries all APIs until success
- Specific API: Uses only one chosen API
3. Choose data format:
- Normalized (recommended): Standardized format across all APIs
- Original: Raw data from the API as received
4. Configure delay between requests (accepts expressions, default: 1000ms)
5. Enter the CNPJ (with or without formatting)
6. Execute the workflow

$3

#### Automatic Fallback (Recommended)
`json
{
"operation": "consultarCnpj",
"apiStrategy": "fallback",
"rateLimitDelay": "1000",
"cnpj": "11.222.333/0001-81"
}
`

#### Specific API
`json
{
"operation": "consultarCnpj",
"apiStrategy": "specific",
"api": "cnpjws",
"rateLimitDelay": "500",
"cnpj": "11222333000181"
}
`

#### With Dynamic Expression
`json
{
"operation": "consultarCnpj",
"apiStrategy": "fallback",
"rateLimitDelay": "={{$json.customDelay || 1000}}",
"cnpj": "={{$json.cnpj}}"
}
`

🎨 Dynamic Expressions

The Delay field accepts n8n expressions, allowing dynamic values:

$3

- Fixed value: "1000"
- From previous item: "={{$json.delay}}"
- With fallback: "={{$json.customDelay || 2000}}"
- Condition-based: "={{$json.isPriority ? 500 : 2000}}"
- Dynamic calculation: "={{Math.min($json.requestCount * 100, 5000)}}"

$3

- Minimum: 0ms (no delay)
- Maximum: 60000ms (60 seconds)
- Default: 1000ms

📊 Normalized Data Structure

When using Normalized format, all APIs return data in this standardized structure:

`json
{
"cnpj": "11.222.333/0001-81",
"razao_social": "Company Name",
"nome_fantasia": "Trade Name",
"situacao": "Active",
"data_abertura": "2009-09-02",
"porte": "Small",
"natureza_juridica": "Private Association",
"capital_social": "0.00",
"atividade_principal": {
"codigo": "8550301",
"descricao": "School fund administration"
},
"endereco": {
"logradouro": "Rua Garibaldi",
"numero": "070",
"complemento": "",
"bairro": "Vila Rica",
"cep": "95760000",
"municipio": "São Sebastião do Caí",
"uf": "RS"
},
"contato": {
"telefone": "(51) 3635-4333 / (51) 3635-1603",
"email": "example@company.com"
},
"socios": [
{
"nome": "Partner Name",
"cpf_cnpj": "*123456",
"qualificacao": "President",
"data_entrada": "2016-09-29"
}
],
"atividades_secundarias": [],
"simples": {
"optante": false,
"data_opcao": null,
"data_exclusao": null
},
"_meta": {
"api_utilizada": "brasilapi",
"cnpj_consultado": "11222333000181",
"data_consulta": "2025-08-13T03:41:00.000Z",
"estrategia": "fallback",
"data_format": "normalized",
"original_data": { / Raw API response / }
}
}
`

$3


- Consistent field names across all APIs
- Predictable data structure for reliable workflows
- Standardized data types and formats
- Original data preserved in _meta.original_data
- Easy integration with other n8n nodes

📊 Response Structure

All responses include detailed metadata:

$3

`json
{
"...company_data...",
"_meta": {
"api_utilizada": "cnpjws",
"cnpj_consultado": "11222333000181",
"data_consulta": "2025-08-12T23:47:59.000Z",
"estrategia": "fallback",
"apis_tentadas": ["ReceitaWS: CNPJ não encontrado"]
}
}
`

$3

`json
{
"error": "All APIs failed: cnpjws: timeout; cnpja: 500 error; receitaws: not found",
"_meta": {
"api_utilizada": "erro",
"cnpj_consultado": "11222333000181",
"data_consulta": "2025-08-12T23:47:59.000Z",
"status": "erro",
"estrategia": "fallback"
}
}
`

$3

- api_utilizada: API that successfully returned data
- cnpj_consultado: Clean CNPJ (numbers only) that was queried
- data_consulta: Query timestamp
- estrategia: "fallback" or "specific"
- apis_tentadas: List of errors from failed APIs (fallback mode only)
- status: "erro" when query fails completely

🔧 Development

$3

- npm run build - Build the project
- npm run dev - Development mode with watch
- npm run lint - Check linting errors
- npm run lintfix - Fix linting errors automatically

$3

`
n8n-nodes-cnpj-hub/
├── nodes/
│ └── CNPJHUB/
│ ├── CNPJHUB.node.ts # Main node logic
│ ├── CNPJHUB.node.json # Node configuration
│ └── CNPJHUB.svg # Node icon
├── docs/
│ └── README-pt.md # Portuguese documentation
├── package.json
└── README.md
`

⚠️ Limitations

- Public APIs may have rate limits
- Some APIs may be temporarily unavailable
- Not all CNPJs may be available in all APIs

🤝 Contributing

Contributions are welcome! Feel free to:

1. Fork the project
2. Create a feature branch (git checkout -b feature/new-feature)
3. Commit your changes (git commit -am 'Add new feature')
4. Push to the branch (git push origin feature/new-feature`)
5. Create a Pull Request

📝 License

MIT - see LICENSE.md file for details.

📞 Contact

- Author: Douglassiqueira
- Email: douglassiqueira@gmail.com
- GitHub: douglassiqueira

---

Note: This project is not affiliated with the Brazilian Federal Revenue Service or any government agency. It only uses publicly available APIs.