CASO DE USO
Valide IDs fiscais no checkout antes de gerar a nota fiscal
A emissao de nota fiscal no Brasil exige um identificador fiscal valido em cada documento — CPF para pessoas fisicas ou CNPJ para pessoas juridicas. Um ID invalido significa que a nota fiscal e rejeitada legalmente. O cliente nao pode deduzi-la. Sua equipe de operacoes trata a correcao manualmente. Validar no checkout — de forma inline, antes do envio — detecta o erro onde e mais barato corrigi-lo: no ponto de entrada.
O PROBLEMA
IDs fiscais invalidos em notas fiscais geram rejeicoes downstream
A rejeicao de notas fiscais por IDs fiscais invalidos exige correcao manual, re-emissao e em alguns casos um processo formal de cancelamento. O custo por rejeicao e desproporcional ao custo de validar na entrada.
CPF e CNPJ tem algoritmos de verificacao diferentes
O CPF (11 digitos) tem dois digitos verificadores sequenciais com pesos especificos. O CNPJ (14 digitos) tem dois digitos verificadores com um conjunto diferente de pesos. Um checkout que implementa um corretamente frequentemente tem bugs no outro.
Erros aparecem apos o passo de pagamento
Se voce valida IDs fiscais na geracao da nota fiscal (nao no envio do formulario), o usuario ja pagou. Entao voce precisa contatalo para corrigir o ID, re-emitir a nota e possivelmente cancelar a original. Isso gera overhead de suporte e reduz a conversao em compras futuras.
IDs com formato correto mas checksum invalido
Um CPF de 11 digitos onde ambos os digitos verificadores estao errados parece valido para um regex. Um CNPJ com o comprimento certo mas um digito verificador errado parece valido para uma verificacao de comprimento. Esses passam pela validacao basica do frontend e falham silenciosamente no passo de emissao da nota fiscal.
POR QUE AS SOLUCOES PADRAO NAO SAO SUFICIENTES
Por que a validacao apenas do lado do frontend e insuficiente
Atributo HTML pattern
Pattern valida a classe de caracteres e o comprimento. Nao pode calcular o duplo digito verificador do CPF. Uma string numerica de 11 digitos passa o pattern independentemente da validade do checksum.
Pacotes npm especificos para Brasil
Bibliotecas como cpf-cnpj-validator funcionam bem para o Brasil. Para um checkout multi-pais voce precisa de pacotes separados por pais, cada um com APIs diferentes e cadencias de atualizacao diferentes.
Validar na geracao da nota fiscal
No momento em que voce gera a nota fiscal, o pagamento ja foi capturado. Corrigir um ID fiscal invalido apos o pagamento exige contato com o cliente, re-emissao e possivelmente um cancelamento formal de nota — nada disso e gratuito.
COMO O NORMADATA AJUDA
Como o Normadata ajuda
Chame o Normadata validate ao perder o foco do campo ou ao enviar o formulario, antes que o checkout avance para o pagamento. Exiba um erro especifico e amigavel ao usuario se valid=false. O usuario corrige o ID antes do passo de pagamento, nao depois.
O Normadata retorna as representacoes normalized e formatted do ID. Pre-popule seu sistema de emissao de notas com a forma canonica — sem necessidade de reformatar depois.
Um endpoint trata CPF/CNPJ (Brasil), CUIT (Argentina), RFC (Mexico), RUT (Chile/Colombia) e mais. Sua logica de validacao no checkout e a mesma para todos os paises.
VEJA EM ACAO
Veja em acao
# Validate the tax ID inline at checkout before the form submits
$ curl -X POST api.normadata.io/v1/validate/tax-ids \
-H "X-API-Key: nd_a8f3b2c1d4e5f6g7h8i9j0k1l2m3n4o5" \
-d '{"items":[{"id":"f","country":"AR","type":"cuit","value":"20-31456789-1"}]}'
{
"results": [
{
"id": "f",
"valid": false,
"error": "invalid_check_digit"
}
]
}
# Show an inline error before the user reaches the payment step
# Correct value: 20-31456789-0
# Same schema for CPF/CNPJ (BR), RUT (CL), NIT (CO) — just change country/typeLIMITACOES
O que o Normadata nao faz aqui
—O Normadata nao confirma que o ID fiscal corresponde a um contribuinte registrado ou que o negocio esta em dia com a Receita Federal.
—O Normadata nao se integra com a Receita Federal, AFIP, SAT ou SII. Valida formato e checksum com base na especificacao publica de cada identificador.
PERGUNTAS FREQUENTES
Perguntas frequentes
Posso usar o Normadata para validacao em tempo real enquanto o usuario digita?
Sim, mas recomendamos validar ao perder o foco do campo (quando o campo perde o focus) em vez de a cada tecla, para evitar disparar chamadas de API antes que o usuario termine de digitar. Use debounce de pelo menos 300ms se validar no input.
O Normadata suporta CNPJ alem de CPF para checkouts B2B?
Sim. Passe country=BR e type=cnpj. O Normadata valida CNPJ (14 digitos, dois digitos verificadores) de forma independente do CPF. Para checkouts que aceitam tanto pessoas fisicas quanto juridicas, chame verify com o tipo apropriado com base no que o usuario seleciona.
Integre o Normadata no seu stack
Acesso antecipado. Entre na lista e daremos acesso à API.