````markdown
# validador-cnpj
[](https://pypi.org/project/validador-cnpj/)
[](https://pypi.org/project/validador-cnpj/)
[](LICENSE)
UDFs **PySpark** para **limpeza, reparo, normalização e validação** de CNPJ (numérico e alfanumérico).
**Distribuição (PyPI):** `validador-cnpj` • **Import (Python):** `validador_cnpj`
---
## Instalação
```bash
pip install validador-cnpj
````
---
## Uso rápido (Spark)
```python
from validador_cnpj import padronizar_cnpj
df = spark.createDataFrame(
[("12.345.678/0001-95",), ("12.ABC.345/01DE-35",), ("123456780001",)],
["cnpj_bruto"]
)
out = padronizar_cnpj(df, "cnpj_bruto", com_mascara=True)
display(out)
```
**Colunas geradas**:
* `cnpj14` — 14 chars (12 base + 2 DV)
* `f_eh_valido` — boolean
* `f_tipo` — `"numerico"` | `"alfanumerico"` | `"desconhecido"`
* `cnpj_mascara` — `AA.AAA.AAA/AAAA-DV` (quando válido e `com_mascara=True`)
* `bruto_limpo` — entrada higienizada (apenas A–Z/0–9, maiúsculo)
---
## Principais recursos
* Aceita entradas **sujas** (máscaras, espaços, símbolos, caixa mista).
* **Repara** casos com **falta**/**excesso** de caracteres (configurável por estratégia).
* **Valida DV** (módulo 11) para CNPJ **numérico e alfanumérico**.
* UDFs prontas para **PySpark** e função pura para uso em Python/driver.
---
## API (Python)
```python
from validador_cnpj import (
padronizar_cnpj,
normalizar_cnpj_udf,
cnpj_eh_valido_udf,
tipo_cnpj_udf,
mascarar_cnpj_udf,
)
```
### `padronizar_cnpj(df, coluna, *, coluna_saida="cnpj14", com_mascara=True, estrategia="flex_pad_esquerda") -> DataFrame`
Aplica limpeza/reparo/validação em lote e devolve colunas utilitárias.
Parâmetros:
* `coluna` — nome da coluna de entrada.
* `coluna_saida` — nome da coluna com o CNPJ normalizado (14 chars).
* `com_mascara` — adiciona `cnpj_mascara` quando válido.
* `estrategia` — `"rigorosa" | "flex_pad_esquerda" | "corte_direita"`.
### UDFs
* `normalizar_cnpj_udf(string) -> struct(cnpj14, eh_valido, tipo, mascarado)`
* `cnpj_eh_valido_udf(string) -> boolean`
* `tipo_cnpj_udf(string) -> string`
* `mascarar_cnpj_udf(string) -> string | null`
> Dica: use as UDFs quando quiser compor sua própria transformação; use `padronizar_cnpj` para o caminho mais simples.
---
## Estratégias de reparo
* **`rigorosa`** — aceita apenas 12 ou 14 caracteres válidos, senão retorna `None`.
* **`flex_pad_esquerda`** *(padrão)* — cobre truncamentos/legados comuns (completa à esquerda, recalcula DV quando necessário).
* **`corte_direita`** — prioriza cortar à direita (12 primeiros como base, tenta usar os 2 últimos como DV).
---
## Casos de uso práticos
1. Limpeza e validação em lote
2. Apenas checar se é válido
3. Identificar tipo (numérico x alfanumérico)
4. Aplicar máscara oficial somente se válido
5. Usar estratégia **rigorosa**
6. Preferir cortes à direita
7. Compor manualmente com `normalizar_cnpj_udf`
8. **Exemplo em SQL (Databricks)**
```sql
-- Exemplo SQL
SELECT
normalizar_cnpj(cnpj_bruto).cnpj14 AS cnpj14,
normalizar_cnpj(cnpj_bruto).eh_valido AS f_eh_valido,
normalizar_cnpj(cnpj_bruto).tipo AS f_tipo,
normalizar_cnpj(cnpj_bruto).mascarado AS cnpj_mascara
FROM tabela;
```
---
## Exemplos detalhados de entradas → saídas
| Entrada (`cnpj_bruto`) | Estratégia | `cnpj14` (normalizado) | `f_eh_valido` | `f_tipo` | Observação |
| ---------------------------- | ------------------- | ---------------------: | :------------------------: | :------------- | -------------------------------------------- |
| `12.345.678/0001-95` | qualquer | `12345678000195` | :white\_check\_mark: | `numerico` | Formato clássico com máscara |
| `12.ABC.345/01DE-35` | qualquer | `12ABC34501DE35` | :white\_check\_mark: | `alfanumerico` | Alfanumérico com máscara mista |
| `123456780001` | flex\_pad\_esquerda | `123456780001??` | :white\_check\_mark:/ \:x: | `numerico` | Faltam DVs → calculados |
| `123` | flex\_pad\_esquerda | `000000000123??` | :white\_check\_mark:/ \:x: | `numerico` | Completa à esquerda até 12 e calcula DV |
| `00012345678000195` | flex\_pad\_esquerda | `12345678000195` | :white\_check\_mark: | `numerico` | Excesso à esquerda → usa 12 anteriores ao DV |
| `12ABC34501DEXX` | flex\_pad\_esquerda | `12ABC34501DE??` | :white\_check\_mark:/ \:x: | `alfanumerico` | Lixo no fim, sem DV confiável → recalcula |
| `12abc345/01de-35` | qualquer | `12ABC34501DE35` | :white\_check\_mark: | `alfanumerico` | Caixa/símbolos higienizados |
| `foo 12.ABC.345/01DE-35 bar` | flex\_pad\_esquerda | `12ABC34501DE35` | :white\_check\_mark: | `alfanumerico` | Texto ao redor ignorado |
| `A2345678000195` | rigorosa | `None` | :x: | `desconhecido` | 14 chars mas DV não numérico → rejeita |
| `None` / vazio | qualquer | `None` | :x: | `desconhecido` | Valor nulo |
---
## Boas práticas de performance
* Prefira `padronizar_cnpj` (uma passada) e **reutilize** as colunas derivadas.
* Filtre válidos após normalizar.
* Ajuste `estrategia` conforme a qualidade do dado.
---
## Tratamento de erros & decisões de negócio
A biblioteca **não** toma decisões de negócio (ex.: descartar registros inválidos).
Ela fornece sinais (`f_eh_valido`, `f_tipo`, `cnpj14`, `bruto_limpo`) para que **você** defina as regras.
---
## Compatibilidade
* **Python**: 3.8+
* **PySpark**: 3.3 – 3.x
* **Databricks**: testado em clusters 10.x/11.x/12.x (Spark 3.x)
---
## Alterações recentes
Veja o [CHANGELOG.md](CHANGELOG.md).
---
## Licença
MIT
---
## Detalhes técnicos
* Cálculo de DV (módulo 11) aplicável a CNPJ **numérico** e **alfanumérico**.
* Máscara padrão: `AA.AAA.AAA/AAAA-DV`.
```
Raw data
{
"_id": null,
"home_page": null,
"name": "validador-cnpj",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "brasil, cnpj, data-quality, databricks, pyspark, spark",
"author": null,
"author_email": "Yuri Arthur Ferreira Santana <yuriarthurf@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/7f/54/67c56386012f5f60292b30f0d86dd1f47b6d283fd7c7ec909a9706c804b2/validador_cnpj-0.2.1.tar.gz",
"platform": null,
"description": "````markdown\n# validador-cnpj\n\n[](https://pypi.org/project/validador-cnpj/)\n[](https://pypi.org/project/validador-cnpj/)\n[](LICENSE)\n\nUDFs **PySpark** para **limpeza, reparo, normaliza\u00e7\u00e3o e valida\u00e7\u00e3o** de CNPJ (num\u00e9rico e alfanum\u00e9rico). \n**Distribui\u00e7\u00e3o (PyPI):** `validador-cnpj` \u2022 **Import (Python):** `validador_cnpj`\n\n---\n\n## Instala\u00e7\u00e3o\n\n```bash\npip install validador-cnpj\n````\n\n---\n\n## Uso r\u00e1pido (Spark)\n\n```python\nfrom validador_cnpj import padronizar_cnpj\n\ndf = spark.createDataFrame(\n [(\"12.345.678/0001-95\",), (\"12.ABC.345/01DE-35\",), (\"123456780001\",)],\n [\"cnpj_bruto\"]\n)\n\nout = padronizar_cnpj(df, \"cnpj_bruto\", com_mascara=True)\ndisplay(out)\n```\n\n**Colunas geradas**:\n\n* `cnpj14` \u2014 14 chars (12 base + 2 DV)\n* `f_eh_valido` \u2014 boolean\n* `f_tipo` \u2014 `\"numerico\"` | `\"alfanumerico\"` | `\"desconhecido\"`\n* `cnpj_mascara` \u2014 `AA.AAA.AAA/AAAA-DV` (quando v\u00e1lido e `com_mascara=True`)\n* `bruto_limpo` \u2014 entrada higienizada (apenas A\u2013Z/0\u20139, mai\u00fasculo)\n\n---\n\n## Principais recursos\n\n* Aceita entradas **sujas** (m\u00e1scaras, espa\u00e7os, s\u00edmbolos, caixa mista).\n* **Repara** casos com **falta**/**excesso** de caracteres (configur\u00e1vel por estrat\u00e9gia).\n* **Valida DV** (m\u00f3dulo 11) para CNPJ **num\u00e9rico e alfanum\u00e9rico**.\n* UDFs prontas para **PySpark** e fun\u00e7\u00e3o pura para uso em Python/driver.\n\n---\n\n## API (Python)\n\n```python\nfrom validador_cnpj import (\n padronizar_cnpj,\n normalizar_cnpj_udf,\n cnpj_eh_valido_udf,\n tipo_cnpj_udf,\n mascarar_cnpj_udf,\n)\n```\n\n### `padronizar_cnpj(df, coluna, *, coluna_saida=\"cnpj14\", com_mascara=True, estrategia=\"flex_pad_esquerda\") -> DataFrame`\n\nAplica limpeza/reparo/valida\u00e7\u00e3o em lote e devolve colunas utilit\u00e1rias.\n\nPar\u00e2metros:\n\n* `coluna` \u2014 nome da coluna de entrada.\n* `coluna_saida` \u2014 nome da coluna com o CNPJ normalizado (14 chars).\n* `com_mascara` \u2014 adiciona `cnpj_mascara` quando v\u00e1lido.\n* `estrategia` \u2014 `\"rigorosa\" | \"flex_pad_esquerda\" | \"corte_direita\"`.\n\n### UDFs\n\n* `normalizar_cnpj_udf(string) -> struct(cnpj14, eh_valido, tipo, mascarado)`\n* `cnpj_eh_valido_udf(string) -> boolean`\n* `tipo_cnpj_udf(string) -> string`\n* `mascarar_cnpj_udf(string) -> string | null`\n\n> Dica: use as UDFs quando quiser compor sua pr\u00f3pria transforma\u00e7\u00e3o; use `padronizar_cnpj` para o caminho mais simples.\n\n---\n\n## Estrat\u00e9gias de reparo\n\n* **`rigorosa`** \u2014 aceita apenas 12 ou 14 caracteres v\u00e1lidos, sen\u00e3o retorna `None`.\n* **`flex_pad_esquerda`** *(padr\u00e3o)* \u2014 cobre truncamentos/legados comuns (completa \u00e0 esquerda, recalcula DV quando necess\u00e1rio).\n* **`corte_direita`** \u2014 prioriza cortar \u00e0 direita (12 primeiros como base, tenta usar os 2 \u00faltimos como DV).\n\n---\n\n## Casos de uso pr\u00e1ticos\n\n1. Limpeza e valida\u00e7\u00e3o em lote\n2. Apenas checar se \u00e9 v\u00e1lido\n3. Identificar tipo (num\u00e9rico x alfanum\u00e9rico)\n4. Aplicar m\u00e1scara oficial somente se v\u00e1lido\n5. Usar estrat\u00e9gia **rigorosa**\n6. Preferir cortes \u00e0 direita\n7. Compor manualmente com `normalizar_cnpj_udf`\n8. **Exemplo em SQL (Databricks)**\n\n```sql\n-- Exemplo SQL\nSELECT\n normalizar_cnpj(cnpj_bruto).cnpj14 AS cnpj14,\n normalizar_cnpj(cnpj_bruto).eh_valido AS f_eh_valido,\n normalizar_cnpj(cnpj_bruto).tipo AS f_tipo,\n normalizar_cnpj(cnpj_bruto).mascarado AS cnpj_mascara\nFROM tabela;\n```\n\n---\n\n## Exemplos detalhados de entradas \u2192 sa\u00eddas\n\n| Entrada (`cnpj_bruto`) | Estrat\u00e9gia | `cnpj14` (normalizado) | `f_eh_valido` | `f_tipo` | Observa\u00e7\u00e3o |\n| ---------------------------- | ------------------- | ---------------------: | :------------------------: | :------------- | -------------------------------------------- |\n| `12.345.678/0001-95` | qualquer | `12345678000195` | :white\\_check\\_mark: | `numerico` | Formato cl\u00e1ssico com m\u00e1scara |\n| `12.ABC.345/01DE-35` | qualquer | `12ABC34501DE35` | :white\\_check\\_mark: | `alfanumerico` | Alfanum\u00e9rico com m\u00e1scara mista |\n| `123456780001` | flex\\_pad\\_esquerda | `123456780001??` | :white\\_check\\_mark:/ \\:x: | `numerico` | Faltam DVs \u2192 calculados |\n| `123` | flex\\_pad\\_esquerda | `000000000123??` | :white\\_check\\_mark:/ \\:x: | `numerico` | Completa \u00e0 esquerda at\u00e9 12 e calcula DV |\n| `00012345678000195` | flex\\_pad\\_esquerda | `12345678000195` | :white\\_check\\_mark: | `numerico` | Excesso \u00e0 esquerda \u2192 usa 12 anteriores ao DV |\n| `12ABC34501DEXX` | flex\\_pad\\_esquerda | `12ABC34501DE??` | :white\\_check\\_mark:/ \\:x: | `alfanumerico` | Lixo no fim, sem DV confi\u00e1vel \u2192 recalcula |\n| `12abc345/01de-35` | qualquer | `12ABC34501DE35` | :white\\_check\\_mark: | `alfanumerico` | Caixa/s\u00edmbolos higienizados |\n| `foo 12.ABC.345/01DE-35 bar` | flex\\_pad\\_esquerda | `12ABC34501DE35` | :white\\_check\\_mark: | `alfanumerico` | Texto ao redor ignorado |\n| `A2345678000195` | rigorosa | `None` | :x: | `desconhecido` | 14 chars mas DV n\u00e3o num\u00e9rico \u2192 rejeita |\n| `None` / vazio | qualquer | `None` | :x: | `desconhecido` | Valor nulo |\n\n---\n\n## Boas pr\u00e1ticas de performance\n\n* Prefira `padronizar_cnpj` (uma passada) e **reutilize** as colunas derivadas.\n* Filtre v\u00e1lidos ap\u00f3s normalizar.\n* Ajuste `estrategia` conforme a qualidade do dado.\n\n---\n\n## Tratamento de erros & decis\u00f5es de neg\u00f3cio\n\nA biblioteca **n\u00e3o** toma decis\u00f5es de neg\u00f3cio (ex.: descartar registros inv\u00e1lidos).\nEla fornece sinais (`f_eh_valido`, `f_tipo`, `cnpj14`, `bruto_limpo`) para que **voc\u00ea** defina as regras.\n\n---\n\n## Compatibilidade\n\n* **Python**: 3.8+\n* **PySpark**: 3.3 \u2013 3.x\n* **Databricks**: testado em clusters 10.x/11.x/12.x (Spark 3.x)\n\n---\n\n## Altera\u00e7\u00f5es recentes\n\nVeja o [CHANGELOG.md](CHANGELOG.md).\n\n---\n\n## Licen\u00e7a\n\nMIT\n\n---\n\n## Detalhes t\u00e9cnicos\n\n* C\u00e1lculo de DV (m\u00f3dulo 11) aplic\u00e1vel a CNPJ **num\u00e9rico** e **alfanum\u00e9rico**.\n* M\u00e1scara padr\u00e3o: `AA.AAA.AAA/AAAA-DV`.\n\n```",
"bugtrack_url": null,
"license": "MIT",
"summary": "UDFs PySpark para limpeza, reparo, normaliza\u00e7\u00e3o e valida\u00e7\u00e3o de CNPJ (num\u00e9rico e alfanum\u00e9rico).",
"version": "0.2.1",
"project_urls": {
"Homepage": "https://github.com/data-engineering-bp/validador-cnpj",
"Issues": "https://github.com/data-engineering-bp/validador-cnpj/issues"
},
"split_keywords": [
"brasil",
" cnpj",
" data-quality",
" databricks",
" pyspark",
" spark"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4e26db8a8922244f79a0a992e91ecb2cfec333048eb826c1cc2cd48eebede38d",
"md5": "bf8f91c878671f51fab8504d1b041b0a",
"sha256": "b981105175d0fad21b123855b8117e26dfef58ce49795a7f2e6a7d1139110609"
},
"downloads": -1,
"filename": "validador_cnpj-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bf8f91c878671f51fab8504d1b041b0a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 7267,
"upload_time": "2025-09-04T19:30:31",
"upload_time_iso_8601": "2025-09-04T19:30:31.402858Z",
"url": "https://files.pythonhosted.org/packages/4e/26/db8a8922244f79a0a992e91ecb2cfec333048eb826c1cc2cd48eebede38d/validador_cnpj-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "7f5467c56386012f5f60292b30f0d86dd1f47b6d283fd7c7ec909a9706c804b2",
"md5": "6b5a0faf3ddc11c61131887f8c50f6c4",
"sha256": "3e66dc9428068a590cb83f2e399bb59125668ca45fb6cf87059ad59254f03033"
},
"downloads": -1,
"filename": "validador_cnpj-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "6b5a0faf3ddc11c61131887f8c50f6c4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 7029,
"upload_time": "2025-09-04T19:30:34",
"upload_time_iso_8601": "2025-09-04T19:30:34.680966Z",
"url": "https://files.pythonhosted.org/packages/7f/54/67c56386012f5f60292b30f0d86dd1f47b6d283fd7c7ec909a9706c804b2/validador_cnpj-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-04 19:30:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "data-engineering-bp",
"github_project": "validador-cnpj",
"github_not_found": true,
"lcname": "validador-cnpj"
}
JSON
