Normadata API vs. bibliotecas open source (python-stdnum, cpf-cnpj-validator, etc.)
Quando vale a pena usar uma biblioteca OSS e quando uma API hospedada faz mais sentido?
python-stdnum, cpf-cnpj-validator (npm), brvalidator e projetos similares são sólidos, maduros, gratuitos e auto-hospedados. Não estamos dizendo que o Normadata os substitui em todos os casos — seria desonesto. Este guia explica com critério técnico quando cada opção ganha e quando a API agrega valor real sobre as bibliotecas.
Comparação rápida
| Aspecto | Bibliotecas OSS | Normadata API |
|---|---|---|
| Custo | Gratuito (MIT/LGPL) | Gratuito em beta; precificação futura não anunciada |
| Auto-hospedado? | Sim — roda na sua infra, sem rede externa | Não — API hospedada em normadata.io |
| Multi-linguagem? | Depende: python-stdnum é Python, cpf-cnpj-validator é Node.js; cada linguagem tem sua própria biblioteca | Sim — HTTP, qualquer linguagem |
| Normalização inclusa? | Parcial (depende da biblioteca) | Sim — forma canônica em cada resposta |
| Correspondência / deduplicação? | Não — você precisa construir por cima | Não — mas devolve a forma canônica normalizada, então você roda dedup/match sobre um dado já consistente |
| Atualizações de especificação? | Depende do mantenedor do projeto OSS | Responsabilidade do Normadata |
| Latência? | ~0 ms (in-process) | <50 ms (rede) |
| Privacidade / dados (LGPD)? | Controle total — dados não saem da sua infraestrutura | Dados enviados ao Normadata para processamento |
Quando usar cada um?
- Monolito Python puro, você já tem python-stdnum instalado e valida CPF e CNPJ sem problemas.
- Requisito de zero chamadas de rede: compliance interno, ambiente air-gapped, ou latência crítica abaixo do milissegundo.
- Privacidade estrita por LGPD: dados pessoais não podem sair da sua infraestrutura sob nenhum contrato de processamento.
- Validação pura apenas, sem necessidade de normalização nem de uma forma canônica como base para sua própria deduplicação.
- O identificador que você precisa já está bem coberto por uma biblioteca estável (ex. cpf-cnpj-validator para CPF/CNPJ em Node.js).
- Stack multi-linguagem: você tem microsserviços em Python, Go e JavaScript — uma API em vez de três implementações diferentes da mesma lógica de CPF/CNPJ.
- Multi-país LATAM: você precisa de CPF, CNPJ, CUIT, RFC, RUT, NIT, RUC em uma única integração consistente.
- Normalização automática: que '123.456.789-09', '12345678909' e '123456789-09' retornem a mesma forma canônica.
- Base limpa para deduplicação: a forma canônica que o Normadata devolve permite comparar de forma confiável dois registros do mesmo contribuinte apesar de variações de formato (o dedup/match você roda sobre esse valor normalizado).
- Manutenção delegada: quando a Receita Federal atualiza as regras do CNPJ ou adiciona novos prefixos, o Normadata atualiza.
- Resposta JSON consistente: mesmo schema de resposta para todos os tipos de identificador, simplificando o tratamento de erros.
Cobertura real: o que o Normadata valida vs. python-stdnum e cpf-cnpj-validator
python-stdnum é um projeto excelente com cobertura ampla — mas sua força está em identificadores globais e europeus. Para o Brasil, cobre CPF e CNPJ, mas a API é diferente por país (from stdnum.br import cpf, cnpj). O cpf-cnpj-validator (npm) cobre bem CPF e CNPJ para Node.js, mas não tem equivalente para CUIT, RFC ou RUT. O Normadata é construído com foco exclusivo em LATAM: os identificadores disponíveis no catálogo incluem CPF, CNPJ (Brasil), CUIT, CUIL, DNI, CBU (Argentina), RFC, CURP (México), RUT (Chile), NIT (Colômbia), RUC (Peru), SSN, EIN, ITIN (EUA), SIN, BN (Canadá) e IBAN. Todos com o mesmo schema de resposta.
O problema do stack multi-linguagem
Uma arquitetura comum em startups brasileiras: um backend Python (Django/FastAPI) para a lógica de negócio, um frontend Next.js para validação de formulários no cliente, e workers Go ou Node.js para processamento em lote. Com bibliotecas OSS, você precisa de três implementações distintas do mesmo algoritmo de CPF/CNPJ — python-stdnum, cpf-cnpj-validator e uma biblioteca Go — e precisa reconciliar os casos em que divergem. Com uma API HTTP, há uma única implementação que todos os serviços consomem de forma idêntica.
Trade-off honesto: OSS é gratuito e auto-hospedado, Normadata é hospedado
Não vamos vender algo que você não precisa. Se você tem um stack homogêneo em Python, já usa python-stdnum ou cpf-cnpj-validator, só precisa validar CPF e CNPJ, e os dados não podem sair da sua infra por requisitos de LGPD — a resposta correta é continuar com a biblioteca OSS. O Normadata agrega valor quando o problema é multi-linguagem, multi-país, ou quando você precisa de uma forma canônica consistente como base para seu próprio dedupe/match. O custo pós-beta não está anunciado, então se o orçamento é zero, OSS é a opção correta hoje.
Exemplos de código
from stdnum.ar import cuit
from stdnum.br import cpf, cnpj
from stdnum.mx import rfc
cuit.is_valid("20-12345678-9") # True
cpf.is_valid("111.444.777-35") # True
rfc.is_valid("XAXX010101000") # True
# But: no normalization, no consistent error schema,
# no match/dedupe, different API per country module.import httpx
def validate(items: list[dict]) -> list[dict]:
r = httpx.post(
"https://api.normadata.io/v1/validate/tax-ids",
headers={"X-API-Key": "nd_your_key"},
json={"items": items},
)
return r.json()["results"]
# Same schema for all countries — mix them in one batch (up to 1000 items)
validate([
{"id": "1", "value": "20-12345678-9", "country": "AR"}, # {"valid": true, "normalized": "20123456789", ...}
{"id": "2", "value": "111.444.777-35", "country": "BR"}, # {"valid": true, "normalized": "11144477735", ...}
{"id": "3", "value": "XAXX010101000", "country": "MX"}, # {"valid": true, "normalized": "XAXX010101000", ...}
])
# One endpoint, one schema for every country. Same call for 1 or N items.O Normadata é uma API hospedada — os dados passam pela nossa infraestrutura. Em beta, sem SLA formal. O custo pós-beta não está anunciado. Para casos com requisitos estritos de privacidade de dados por LGPD, ambiente air-gapped, ou orçamento zero, as bibliotecas OSS continuam sendo a opção correta. O Normadata não tem SDK proprietário — é HTTP puro, o que é bom para portabilidade, mas significa que você depende da disponibilidade de rede.
Perguntas frequentes
O python-stdnum cobre todos os identificadores do Brasil?
Parcialmente. Tem suporte para CPF e CNPJ do Brasil, entre outros. Mas os módulos são organizados por país com APIs ligeiramente diferentes entre si (from stdnum.br import cpf vs. from stdnum.ar import cuit). Alguns identificadores menos comuns podem ter cobertura incompleta.
O Normadata tem SDK?
Ainda não. A integração é HTTP + JSON diretamente. Isso significa que funciona com qualquer linguagem sem dependências adicionais, mas também que não há helpers de tipos ou autocomplete oficial. Durante a beta estamos avaliando se publicamos SDKs leves.
E o libphonenumber para telefones?
O libphonenumber do Google é o padrão de facto para telefones e está muito bem mantido. Se sua necessidade é exclusivamente validação de números de telefone, libphonenumber é provavelmente a melhor opção. O Normadata foca em identificadores fiscais, pessoas, contas financeiras e endereços da LATAM; para validação de telefones hoje o libphonenumber é mais maduro para esse caso específico.
Posso combinar python-stdnum com o Normadata?
Sim, não são excludentes. Um padrão comum durante migrações: usar python-stdnum para os identificadores que você já valida corretamente (CPF, CNPJ), e adicionar o Normadata para novos países ou tipos de identificador. Você pode migrar progressivamente sem quebrar o que já funciona.
O que significa o Normadata estar em beta privada?
Que o acesso requer inscrição na lista de espera, não há SLA formal, e a precificação pós-beta não está definida. A API funciona em produção e a validamos com carga real, mas ainda não há garantias contratuais de uptime nem SLA de resposta.