[OpenCNPJ Banner]

OpenCNPJ Dart Client #

An unofficial, robust, and pure Dart client library for the OpenCNPJ API. Easily query, validate, and format Brazilian company data (CNPJ) in your Dart and Flutter applications.

🇧🇷 Leia em Português

📋 Table of Contents #

• Features
• Installation
• Usage
  • Basic Query
  • Validation
  • Formatting
• Examples
• Supported Fields
• API Limitations
• Author
• Contributing
• Disclaimer
• License

✨ Features #

• 🚀 Easy to Use: Simple, async API to fetch company details.
• 🛡️ Robust Validation: Validate CNPJ format and check digits locally before hitting the API.
• 🎨 Formatting: Built-in utilities to format CNPJs (XX.XXX.XXX/XXXX-XX).
• 📦 Strongly Typed: Full support for all OpenCNPJ fields, including Partners (QSA) and CNAEs.
• ⚡ Performance: Zero-dependency on Flutter (runs on server, CLI, and web).
• 🔒 Safety: Input sanitization and specific exceptions for predictable error handling.

📦 Installation #

Add this to your pubspec.yaml:

dependencies:
  opencnpj: ^0.2.0

Or run:

dart pub add opencnpj

💻 Usage #

Basic Query #

Import the package and instantiate the client. You can fetch company data using a formatted or unformatted CNPJ string.

import 'package:opencnpj/opencnpj.dart';

void main() async {
  final client = OpenCNPJ();

  try {
    // Fetch company data
    final company = await client.search('06.990.590/0001-23');

    print('🏢 Company: ${company.razaoSocial}');
    print('📍 State: ${company.uf}');
    print('💼 Status: ${company.situacaoCadastral}');
    
    // Access nested data (Partners/QSA)
    if (company.qsa.isNotEmpty) {
      print('👥 Partners:');
      for (final partner in company.qsa) {
        print('   - ${partner.nomeSocio} (${partner.qualificacaoSocio})');
      }
    }
  } on NotFoundException {
    print('❌ Company not found.');
  } on InvalidCNPJException {
    print('❌ Invalid CNPJ format.');
  } catch (e) {
    print('❌ Error: $e');
  }
}

Validation #

Validate a CNPJ locally to avoid unnecessary API calls. Uses strict mathematical validation (check digits).

import 'package:cpf_cnpj_validator/cnpj_validator.dart';

bool isValid = CNPJValidator.isValid('06.990.590/0001-23'); // true
bool isInvalid = CNPJValidator.isValid('11.111.111/1111-11'); // false

Formatting #

Format a raw CNPJ string for display in your UI.

import 'package:opencnpj/opencnpj.dart';

String formatted = OpenCNPJ.formatCnpj('06990590000123');
print(formatted); // 06.990.590/0001-23

📱 Examples #

This repository includes fully functional examples to help you get started:

Flutter Web Example #

A responsive, mobile-first web application that auto-fills company registration forms using CNPJ search.

• Source: example/flutter_example

• Run:

  cd example/flutter_example
  flutter run -d chrome
  

• Demo:

  [Demo]

Shelf Server Example #

A backend REST API built with Dart Shelf that proxies requests to OpenCNPJ and implements a CRUD for widgets.

• Source: example/server
• Run:

  cd example/server
  dart run bin/server.dart
  

• API Limitations
• Author
• Contributing
• Disclaimer
• License

✨ Features #

• 🚀 Easy to Use: Simple, async API to fetch company details.
• 🛡️ Robust Validation: Validate CNPJ format and check digits locally before hitting the API.
• 🎨 Formatting: Built-in utilities to format CNPJs (XX.XXX.XXX/XXXX-XX).
• 📦 Strongly Typed: Full support for all OpenCNPJ fields, including Partners (QSA) and CNAEs.
• ⚡ Performance: Zero-dependency on Flutter (runs on server, CLI, and web).
• 🔒 Safety: Input sanitization and specific exceptions for predictable error handling.

📦 Installation #

Add this to your pubspec.yaml:

dependencies:
  opencnpj: ^0.2.0

Or run:

dart pub add opencnpj

💻 Usage #

Basic Query #

Import the package and instantiate the client. You can fetch company data using a formatted or unformatted CNPJ string.

import 'package:opencnpj/opencnpj.dart';

void main() async {
  final client = OpenCNPJ();

  try {
    // Fetch company data
    final company = await client.search('06.990.590/0001-23');

    print('🏢 Company: ${company.razaoSocial}');
    print('📍 State: ${company.uf}');
    print('💼 Status: ${company.situacaoCadastral}');
    
    // Access nested data (Partners/QSA)
    if (company.qsa.isNotEmpty) {
      print('👥 Partners:');
      for (final partner in company.qsa) {
        print('   - ${partner.nomeSocio} (${partner.qualificacaoSocio})');
      }
    }
  } on NotFoundException {
    print('❌ Company not found.');
  } on InvalidCNPJException {
    print('❌ Invalid CNPJ format.');
  } catch (e) {
    print('❌ Error: $e');
  }
}

Validation #

Validate a CNPJ locally to avoid unnecessary API calls. Uses strict mathematical validation (check digits).

import 'package:cpf_cnpj_validator/cnpj_validator.dart';

bool isValid = CNPJValidator.isValid('06.990.590/0001-23'); // true
bool isInvalid = CNPJValidator.isValid('11.111.111/1111-11'); // false

Formatting #

Format a raw CNPJ string for display in your UI.

import 'package:opencnpj/opencnpj.dart';

String formatted = OpenCNPJ.formatCnpj('06990590000123');
print(formatted); // 06.990.590/0001-23

📊 Supported Fields #

The Company model maps 1:1 with the OpenCNPJ response. Key fields include:

⚠️ API Limitations & Data Source #

• Rate Limit: The official API allows 50 requests per second per IP.
• Data Source: Receita Federal (Brazilian Federal Revenue).
• Update Frequency: Monthly. Data may not reflect real-time changes (e.g., a company opened yesterday).
• Offline/Static: The API serves static files; if a CNPJ isn't in the monthly dump, it returns 404.

👨‍💻 Author #

Cristiano Arêdes Costa Senior Software Engineer specializing in Flutter, Dart, and mobile development with 15+ years of experience.

• 🌐 Portfolio: aredes.me
• 💼 LinkedIn: linkedin.com/in/cristianoaredes
• 📧 Email: cristianoaredes@icloud.com

Other Open Source Projects #

Check out my other open-source contributions:

• MCP DadosBR - Model Context Protocol server for Brazilian public data (CNPJ/CEP validation, Tavily search) with 62+ tools
• MCP Câmara - MCP server for Brazilian Chamber of Deputies legislative data with 62+ tools for bills, deputies, and votes
• Super-App Flutter Sample - Modular Flutter architecture example with GoRouter, GetIt, and BLoC pattern
• MCP Mobile Server - Android/iOS/Flutter build automation and CI/CD tooling via MCP
• AnythingToLLMs.txt - Universal document converter for LLM processing

🤝 Contributing #

Contributions are welcome!

1. Fork this repository.
2. Create your feature branch (git checkout -b feature/amazing-feature).
3. Commit your changes (git commit -m 'Add some amazing feature').
4. Push to the branch (git push origin feature/amazing-feature).
5. Open a Pull Request.

⚖️ Disclaimer #

This library is an unofficial open-source project and is not affiliated with the OpenCNPJ.org team. For official API documentation, visit opencnpj.org.

📄 License #

This project is licensed under the MIT License - see the LICENSE file for details.