feat: add Natureza Jurídica utilities (#653)

MatheusPaivaa · web-flow · commit c465322986de · 2025-11-08T10:59:17.000-03:00
* commits iniciais

* organizing feature

* organizing init file

* adjusting test names and conflicts
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -10,6 +10,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - Utilitário `convert_name_to_uf`
+- Utilitário `is_valid_legal_nature` [#641](https://github.com/brazilian-utils/python/issues/641)
+- Utilitário `get_legal_nature_description` [#641](https://github.com/brazilian-utils/python/issues/641)
+- Utilitário `list_all_legal_nature` [#641](https://github.com/brazilian-utils/python/issues/641)
 - Utilitário `is_valid_cnh` [#651](https://github.com/brazilian-utils/brutils-python/pull/651)
 - Utilitário `is_valid_renavam` [#652](https://github.com/brazilian-utils/brutils-python/pull/652)
 
diff --git a/README.md b/README.md
@@ -105,6 +105,10 @@ False
 - [Monetário](#monetário)
   - [format\_currency](#format_currency)
   - [convert\_real\_to\_text](#convert_real_to_text)
+- [Natureza Jurídica](#natureza-jurídica)
+  - [is_valid_legal_nature](#is_valid_legal_nature)
+  - [get_legal_nature_description](#get_legal_nature_description)
+  - [list_all_legal_nature](#list_all_legal_nature)
 
 ## CPF
 
@@ -1377,6 +1381,71 @@ Exemplo:
 None
 ```
 
+## Natureza Jurídica
+
+### is_valid_legal_nature
+
+Valida se o código informado existe na tabela oficial. Aceita `NNNN` ou `NNN-N`.  
+O valor é **normalizado** antes da checagem: remove espaços, mantém apenas dígitos e aceita hífen entre o 3º e 4º dígitos.
+
+**Argumentos**
+- `code (str)`: Código de 4 dígitos (ex.: `"2062"` ou `"206-2"`)
+
+**Retorna**
+- `bool`: `True` se existir na tabela, `False` caso contrário.
+
+**Exemplo**
+```python
+>>> from brutils import legal_nature
+>>> legal_nature.is_valid("2062")   
+True
+>>> legal_nature.is_valid("206-2")  
+True
+>>> legal_nature.is_valid("9999")   
+False
+```
+
+### get_legal_nature_description
+
+Retorna a **descrição oficial** do código de Natureza Jurídica. Aceita `NNNN` ou `NNN-N`. Aplica a mesma normalização do `is_valid`.
+
+**Argumentos**
+
+* `code (str)`: Código de 4 dígitos
+
+**Retorna**
+
+* `str | None`: Descrição correspondente ou `None` se o código for inválido ou inexistente.
+
+**Exemplo**
+
+```python
+>>> from brutils import legal_nature
+>>> legal_nature.get_description("2062")   
+'Sociedade Empresária Limitada'
+>>> legal_nature.get_description("101-5")  
+'Órgão Público do Poder Executivo Federal'
+>>> legal_nature.get_description("0000")   
+None
+```
+
+### list_all_legal_nature
+
+Retorna uma cópia do dicionário completo `{codigo: descricao}`.
+
+**Retorna**
+
+* `dict[str, str]`: Mapeamento de todos os códigos para suas descrições.
+
+**Exemplo**
+
+```python
+>>> from brutils import legal_nature 
+>>> data = legal_nature.list_all()
+>>> len(data) > 0               
+True
+>>> data["2062"]                 
+'Sociedade Empresária Limitada'
 ## RENAVAM
 
 ### is_valid_renavam
diff --git a/README_EN.md b/README_EN.md
@@ -104,6 +104,10 @@ False
 - [Monetary](#monetary)
   - [format_currency](#format_currency)
   - [convert\_real\_to\_text](#convert_real_to_text)
+- [Legal Nature](#legal-nature)
+  - [is_valid_legal_nature](#is_valid_legal_nature)
+  - [get_legal_nature_description](#get_legal_nature_description)
+  - [list_all_legal_nature](#list_all_legal_nature)
 
 ## CPF
 
@@ -1381,6 +1385,72 @@ Example:
 None
 ```
 
+## Legal Nature
+
+### is_valid_legal_nature
+
+Validates if the given code exists in the official table. Accepts `NNNN` or `NNN-N`.
+The value is **normalized** before checking: removes spaces, keeps only digits, and accepts a hyphen between the 3rd and 4th digits.
+
+**Arguments**
+- `code (str)`: 4-digit code (e.g.: `"2062"` or `"206-2"`)
+
+**Returns**
+- `bool`: `True` if it exists in the table, `False` otherwise.
+
+**Example**
+```python
+>>> from brutils import legal_nature
+>>> legal_nature.is_valid("2062")
+True
+>>> legal_nature.is_valid("206-2")
+True
+>>> legal_nature.is_valid("9999")
+False
+```
+
+### get_legal_nature_description
+
+Returns the **official description** for the Legal Nature code. Accepts `NNNN` or `NNN-N`. Applies the same normalization as `is_valid`.
+
+**Arguments**
+
+  * `code (str)`: 4-digit code
+
+**Returns**
+
+  * `str | None`: The corresponding description or `None` if the code is invalid or non-existent.
+
+**Example**
+
+```python
+>>> from brutils import legal_nature
+>>> legal_nature.get_description("2062")
+'Sociedade Empresária Limitada'
+>>> legal_nature.get_description("101-5")
+'Órgão Público do Poder Executivo Federal'
+>>> legal_nature.get_description("0000")
+None
+```
+
+### list_all_legal_nature
+
+Returns a copy of the complete dictionary `{code: description}`.
+
+**Returns**
+
+  * `dict[str, str]`: Mapping of all codes to their descriptions.
+
+**Example**
+
+```python
+>>> from brutils import legal_nature
+>>> data = legal_nature.list_all()
+>>> len(data) > 0
+True
+>>> data["2062"]
+'Sociedade Empresária Limitada'
+```
 ## RENAVAM
 
 ### is_valid_renavam
diff --git a/brutils/__init__.py b/brutils/__init__.py
@@ -43,6 +43,11 @@
     convert_uf_to_name,
 )
 
+# Legal Nature imports
+from brutils.legal_nature import get_description as get_natureza_legal_nature
+from brutils.legal_nature import is_valid as is_valid_legal_nature
+from brutils.legal_nature import list_all as list_all_legal_nature
+
 # Legal Process Imports
 from brutils.legal_process import format_legal_process
 from brutils.legal_process import generate as generate_legal_process
@@ -146,4 +151,8 @@
     # Currency
     "format_currency",
     "convert_real_to_text",
+    # Legal Nature
+    "is_valid_legal_nature",
+    "get_natureza_legal_nature",
+    "list_all_legal_nature",
 ]
diff --git a/brutils/legal_nature.py b/brutils/legal_nature.py
@@ -0,0 +1,165 @@
+"""
+brutils.legal_nature
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Utilities for consulting and validating the official
+*Natureza Jurídica* (Legal Nature) codes defined by the
+Receita Federal do Brasil (RFB).
+
+.. note::
+    The codes and descriptions in this module are sourced from the
+    official **Tabela de Natureza Jurídica** (RFB), as provided in the
+    document used by the Cadastro Nacional (e.g., FCN).
+
+    This module offers simple lookups and validation helpers based on
+    the official table. It does not infer the current legal/registration
+    status of any entity.
+
+    Source: https://www.gov.br/empresas-e-negocios/pt-br/drei/links-e-downloads/arquivos/TABELADENATUREZAJURDICA.pdf
+"""
+
+from typing import Dict, Optional
+
+# FORMATTING
+############
+
+
+# Helper to normalize inputs like "101-5" => "1015"
+def _normalize(code: str) -> Optional[str]:
+    if not isinstance(code, str):
+        return None
+
+    digits = "".join(ch for ch in code.strip() if ch.isdigit())
+
+    return digits if len(digits) == 4 else None
+
+
+LEGAL_NATURE: Dict[str, str] = {
+    # 1. ADMINISTRAÇÃO PÚBLICA
+    "1015": "Órgão Público do Poder Executivo Federal",
+    "1023": "Órgão Público do Poder Executivo Estadual ou do Distrito Federal",
+    "1031": "Órgão Público do Poder Executivo Municipal",
+    "1040": "Órgão Público do Poder Legislativo Federal",
+    "1058": "Órgão Público do Poder Legislativo Estadual ou do Distrito Federal",
+    "1066": "Órgão Público do Poder Legislativo Municipal",
+    "1074": "Órgão Público do Poder Judiciário Federal",
+    "1082": "Órgão Público do Poder Judiciário Estadual",
+    "1104": "Autarquia Federal",
+    "1112": "Autarquia Estadual ou do Distrito Federal",
+    "1120": "Autarquia Municipal",
+    "1139": "Fundação Federal",
+    "1147": "Fundação Estadual ou do Distrito Federal",
+    "1155": "Fundação Municipal",
+    "1163": "Órgão Público Autônomo da União",
+    "1171": "Órgão Público Autônomo Estadual ou do Distrito Federal",
+    "1180": "Órgão Público Autônomo Municipal",
+    # 2. ENTIDADES EMPRESARIAIS
+    "2011": "Empresa Pública",
+    "2038": "Sociedade de Economia Mista",
+    "2046": "Sociedade Anônima Aberta",
+    "2054": "Sociedade Anônima Fechada",
+    "2062": "Sociedade Empresária Limitada",
+    "2076": "Sociedade Empresária em Nome Coletivo",
+    "2089": "Sociedade Empresária em Comandita Simples",
+    "2097": "Sociedade Empresária em Comandita por Ações",
+    "2100": "Sociedade Mercantil de Capital e Indústria (extinta pelo NCC/2002)",
+    "2127": "Sociedade Empresária em Conta de Participação",
+    "2135": "Empresário (Individual)",
+    "2143": "Cooperativa",
+    "2151": "Consórcio de Sociedades",
+    "2160": "Grupo de Sociedades",
+    "2178": "Estabelecimento, no Brasil, de Sociedade Estrangeira",
+    "2194": "Estabelecimento, no Brasil, de Empresa Binacional Argentino-Brasileira",
+    "2208": "Entidade Binacional Itaipu",
+    "2216": "Empresa Domiciliada no Exterior",
+    "2224": "Clube/Fundo de Investimento",
+    "2232": "Sociedade Simples Pura",
+    "2240": "Sociedade Simples Limitada",
+    "2259": "Sociedade em Nome Coletivo",
+    "2267": "Sociedade em Comandita Simples",
+    "2275": "Sociedade Simples em Conta de Participação",
+    "2305": "Empresa Individual de Responsabilidade Limitada",
+    # 3. ENTIDADES SEM FINS LUCRATIVOS
+    "3034": "Serviço Notarial e Registral (Cartório)",
+    "3042": "Organização Social",
+    "3050": "Organização da Sociedade Civil de Interesse Público (Oscip)",
+    "3069": "Outras Formas de Fundações Mantidas com Recursos Privados",
+    "3077": "Serviço Social Autônomo",
+    "3085": "Condomínio Edilícios",
+    "3093": "Unidade Executora (Programa Dinheiro Direto na Escola)",
+    "3107": "Comissão de Conciliação Prévia",
+    "3115": "Entidade de Mediação e Arbitragem",
+    "3123": "Partido Político",
+    "3131": "Entidade Sindical",
+    "3204": "Estabelecimento, no Brasil, de Fundação ou Associação Estrangeiras",
+    "3212": "Fundação ou Associação Domiciliada no Exterior",
+    "3999": "Outras Formas de Associação",
+    # 4. PESSOAS FÍSICAS
+    "4014": "Empresa Individual Imobiliária",
+    "4022": "Segurado Especial",
+    "4081": "Contribuinte individual",
+    # 5. ORGANIZAÇÕES INTERNACIONAIS E OUTRAS INSTITUIÇÕES EXTRATERRITORIAIS
+    "5002": "Organização Internacional e Outras Instituições Extraterritoriais",
+}
+
+# OPERATIONS
+############
+
+
+def is_valid(code: str) -> bool:
+    """
+    Check if a string corresponds to a valid *Natureza Jurídica* code.
+
+    Args:
+        code (str): The code to be validated. Accepts either "NNNN" or "NNN-N".
+
+    Returns:
+        bool: True if the normalized code exists in the official table, False otherwise.
+
+    Example:
+        >>> is_valid("2062")
+        True
+        >>> is_valid("206-2")
+        True
+        >>> is_valid("9999")
+        False
+
+    .. note::
+        Validation is based solely on the presence of the code in the
+        official RFB table. It does not verify the current legal status
+        or registration of the entity.
+    """
+    normalized = _normalize(code)
+    return normalized in LEGAL_NATURE if normalized else False
+
+
+def get_description(code: str) -> Optional[str]:
+    """
+    Retrieve the description of a *Natureza Jurídica* code.
+
+    Args:
+        code (str): The code to look up. Accepts either "NNNN" or "NNN-N".
+
+    Returns:
+        str | None: The full description if the code is valid, otherwise None.
+
+    Example:
+        >>> get_description("2062")
+        'Sociedade Empresária Limitada'
+        >>> get_description("101-5")
+        'Órgão Público do Poder Executivo Federal'
+        >>> get_description("0000")
+        None
+    """
+    normalized = _normalize(code)
+    return LEGAL_NATURE.get(normalized) if normalized else None
+
+
+def list_all() -> Dict[str, str]:
+    """
+    Return a copy of the full *Natureza Jurídica* table.
+
+    Returns:
+        dict[str, str]: Mapping from "NNNN" codes to descriptions.
+    """
+    return dict(LEGAL_NATURE)
diff --git a/tests/test_legal_nature.py b/tests/test_legal_nature.py
