Consulta de Natureza Jurídica de Entidades (Códigos da Receita Federal)

[MatheusPaivaa]

Seu pedido de recurso está relacionado a um problema? Atualmente o brutils não oferece uma forma de validar ou consultar os códigos oficiais de Natureza Jurídica definidos pela Receita Federal. Essa informação é essencial em cadastros empresariais (como CNPJ ou QSA), e usuários precisam buscar manualmente as descrições em fontes externas, o que aumenta a chance de inconsistências e dificulta o uso em aplicações fiscais.

Descreva a solução que você gostaria Implementar um módulo dedicado (brutils/natureza_juridica.py) que contenha:

• Um dicionário estático com os códigos e descrições oficiais, conforme a tabela publicada pela Receita Federal;
• Funções para:
  • get_description(code: str) -> str | None: retorna a descrição correspondente ao código;
  • is_valid(code: str) -> bool: valida se o código existe na tabela;
  • (opcional) list_all() -> dict: retorna a tabela completa como dicionário.

Além disso:

• Adicionar docstrings com referência explícita à fonte oficial:

  Receita Federal do Brasil. Tabela de Natureza Jurídica das Entidades Obrigadas à Apresentação do QSA. Disponível em: https://www.gov.br/empresas-e-negocios/pt-br/drei/links-e-downloads/arquivos/TABELADENATUREZAJURDICA.pdf

Descreva alternativas que você considerou

• Usar uma API externa (BrasilAPI): depende de conexão de rede e não é confiável para ambientes offline.
• Codificar manualmente por projeto: gera redundância e risco de divergência com a tabela oficial.

Contexto adicional

• Arquivo sugerido: brutils/natureza_juridica.py
• Complementa os módulos existentes voltados a dados cadastrais (CPF, CNPJ, PIS etc.).
• Útil para validação de payloads em integrações fiscais, ERPs e sistemas de compliance.

[MatheusPaivaa]

Bora!

[github-actions[bot]]

🇧🇷 Português ✅ Issue #641 atribuída a @MatheusPaivaa. Verifique o guia de contribuição para instruções sobre como submeter sua Pull Request.

🇬🇧 English ✅ Issue #641 assigned to @MatheusPaivaa. Check the contributing guide for instructions on submitting your Pull Request.