CASO DE USO
Limpeza em massa de bases de dados com tax IDs LATAM malformados
A base de clientes tem 100k linhas. O CPF aparece em cinco formatos: com pontos, com hifen, sem separadores, com espacos, com a mascara da planilha original. Os joins entre tabelas estao quebrados porque a linha '123.456.789-09' nao bate com '12345678909'. Existem duplicados porque o mesmo cliente entrou tres vezes em tres formatos. Um script de cleanup que normalize formato e detecte invalidos arruma a base — mas exige um validador por pais que funcione bem e barato.
O PROBLEMA
A variacao de formato quebra joins e cria duplicados
Antes de qualquer projeto de data quality, BI ou migracao, a base LATAM precisa de uma passada de normalizacao. As ferramentas padrao de ETL nao trazem validadores por pais.
Mesmos dados em formatos diferentes por linha
Um cliente B2C entrou tres vezes: uma pelo checkout (com mascara), uma do CRM importado por planilha (sem mascara), uma de uma integracao legada (com espacos). As tres linhas sao a mesma pessoa, mas nenhuma ferramenta de dedup acha sem normalizar antes.
Joins entre tabelas quebram em silencio
A tabela customers tem CPF com pontos. A tabela payments tem CPF sem separadores. O JOIN customers.cpf = payments.cpf retorna zero matches. O relatorio de BI sai errado. Ninguem nota ate o diretor financeiro perguntar por que as vendas nao fecham.
Tax IDs invalidos que nunca deveriam ter entrado
Algumas linhas tem valores que simplesmente nao sao tax IDs validos — comprimento errado, checksum falho, caracteres estranhos. Esses dados nao sao recuperaveis: precisam ser marcados como invalidos antes do dedup.
POR QUE AS SOLUCOES PADRAO NAO SAO SUFICIENTES
Por que um script caseiro falha
Regex para remover pontuacao
Remover pontos e hifens normaliza formato mas nao detecta tax IDs invalidos (CPF com DV errado, CUIT com prefixo errado). Voce fica com uma base de strings limpos mas alguns nao sao tax IDs reais.
pandas + biblioteca por pais
Funciona para um pais, no maximo dois. Quando sua base tem CPF, CUIT, RFC, RUT e NIT misturados, manter uma stack de validadores por pais num notebook fica fragil.
Ferramentas enterprise de data quality
Talend, Informatica e similares cobrem bem IDs de EU/US (VAT, SSN, IBAN), mas os modelos out-of-the-box nao trazem CUIT, CPF, RFC com checksum implementado corretamente.
COMO O NORMADATA AJUDA
Como o Normadata ajuda
Loop sobre o CSV com verify/tax-id em paralelo (10-20 workers, ~30ms p95 por chamada). O campo normalized da a chave canonical para todas as linhas — joins arrumados, dedup limpo.
Se seu input e ambiguo (nao sabe o pais ou o tipo), use /v1/verify (smart parse) que detecta o tipo automaticamente segundo heuristica do valor.
Linhas com valid=false ficam flagueadas em coluna separada — sao dados nao recuperaveis que o time de data quality decide se manda para recaptura ou marca como fechados.
VEJA EM ACAO
Veja em acao
# Loop over CSV rows — single endpoint, parallelize client-side
# Python pseudocode (requests, no SDK)
# import csv, requests
# for row in csv.reader(open('customers.csv')):
# r = requests.post(url, headers=H, json={...})
# write_to(out, r.json()['valid'], r.json()['normalized'])
# Each row → one verify call
$ curl -X POST api.normadata.io/v1/verify/tax-id \
-H "X-API-Key: nd_a8f3b2c1d4e5f6g7h8i9j0k1l2m3n4o5" \
-d '{"country":"BR","type":"cpf","value":"111.444.777-35"}'
{
"valid": true,
"normalized": "11144477735",
"formatted": "111.444.777-35"
}
# Write normalized to canonical column; mark valid=false for review
# ~30ms p95 → 100k rows in minutes with 10 parallel workersLIMITACOES
O que o Normadata nao faz aqui
—O Normadata nao faz enrichment. Nao retorna razao social, nao retorna nome, nao retorna situacao do contribuinte. So valida formato e devolve a forma canonical.
—O Normadata nao tem endpoint batch. Cada tax ID e uma chamada. Para limpar 100k linhas, paraleliza no client respeitando seus rate limits.
PERGUNTAS FREQUENTES
Perguntas frequentes
Existe endpoint batch para mandar 10k linhas de uma vez?
Nao. A API processa um tax ID por chamada. Para volumes grandes recomendamos paralelizar no client (10-50 workers segundo o plano) respeitando o rate limit. A ~30ms p95, 100k linhas saem em minutos.
Qual velocidade da API?
Latencia interna p95 perto de 30ms para verify/tax-id. A latencia end-to-end depende da sua rede e regiao. Para batch cleanup na mesma regiao cloud, o throughput e dominado pela paralelizacao no client.
Integre o Normadata no seu stack
Acesso antecipado. Entre na lista e daremos acesso à API.