O que é número de documento e como ele funciona na prática
Você já tentou cadastrar um cliente num sistema e recebeu um erro de validação por causa do campo de documento? Aí percebe que o número que ele passou tem treze dígitos, mas o sistema só aceita doze, ou vice-versa. Isso acontece todo dia. O problema é que "número de documento" não é uma coisa só. Depende do país, do tipo de pessoa, do sistema que você tá tentando conectar.
O que é numero de documento no Brasil e em outros países lusófonos
No Brasil, o número de documento mais comum é o CPF para pessoas físicas e o CNPJ para pessoas jurídicas. São formatos diferentes, com lógica de validação diferente, e ambos geram dor de cabeça quando você integra sistemas. O CPF tem onze dígitos, dois pontos, um traço e um dígito verificador. Mas na prática, a maioria dos bancos de dados guarda só os onze números. Ponto e traço são formatação, não parte do dado em si. Em Portugal, o equivalente é o NIF. Pessoas físicas têm NIF de nove dígitos, pessoas jurídicas também. O detalhe importante é que o NIF português não usa dígitos verificadores como o CPF. Ele é puramente sequencial, o que significa que você não consegue validar um NIF sozinho — tem que consultar uma base oficial ou confiar no formato.
Se o documento vier de Angola, Moçambique ou outros países, cada um tem seu próprio sistema. Às vezes o número tem formato alfanumérico. Às vezes começa com zero. Às vezes exige tratamento de texto, não de número inteiro. Tratar como inteiro pode cortar zeros à esquerda e quebrar tudo.
Como validar um número de documento sem perder tempo
A maioria dos desenvolvedores começa errado. Eles criam um campo numérico no banco de dados para CPF e aí se perguntam por que o Zero não aparece nos registros. A solução mais simples é tratar o número de documento como string. Sempre. Formatação e validação são camadas separadas do armazenamento. Para validar CPF no Brasil, você precisa implementar o algoritmo dos dígitos verificadores. Primeiro dígito: multiplique os dez primeiros números pelos pesos de 10 a 2, some, calcule o resto da divisão por 11. Se o resto for menor que 2, o dígito é zero. Senão, subtraia onze do resto. Segundo dígito: repita o processo com os onze primeiros números, usando pesos de 11 a 2. O mesmo regra do resto se aplica.
Isso dá cerca de quinze linhas de código. E resolve 90% dos casos. Mas tem um probleminha que quase ninguém menciona: CPF com dígitos repetidos. CPF 111.111.111-11 existe como formato válido no algoritmo, mas é invalidado pela legislação como CPF irregular. Mesma coisa para 222.222.222-22, 333.333.333-33 e os outros onze padrões conhecidos. Se seu sistema só roda o algoritmo matemático, ele vai aceitar esses documentos como válidos. Você precisa adicionar uma verificação explícita de dígitos repetidos depois do cálculo dos verificadores. Para CNPJ, a lógica é parecida mas mais longa. São doze dígitos na base, dois verificadores. Os pesos começam em 5 e 4 para os primeiros quatro dígitos, depois voltam a contar de 2 para os próximos quatro. Depois repete para o segundo dígito verificador. O site da Receita Federal mantém a tabela oficial de pesos, mas na prática você só precisa hardcoder os dois vetores de pesos e rodar o mesmo algoritmo de resto por 11.
Problemas reais que eu já vi acontecerem
Num projeto de integração financeira, eu me deparei com um cadastro que rejeitava CPFs paulistas com dígito verificador 0. O sistema do partner calculava o dígito corretamente, mas o campo de validação estava fazendo uma comparação estrita contra uma string fixa mal configurada. O problema era tão específico que demorei quase dois dias rastreando. A solução foi desligar a validação do lado deles e validar no meu sistema antes de enviar. Funcionou. Outro caso foi com NIF português em um sistema europeu. O número começava com 1, então ao salvar como inteiro, o zero à esquerda era cortado em algum ponto da pipeline. O resultado era um NIF com oito dígitos em vez de nove. O sistema rejeitava na primeira tentativa. A correção foi tratar todos os campos de documento como string desde a entrada do usuário até o banco de dados.
Tenha isso em mente: quando um documento é maior que 11 dígitos ou contém caracteres além de números, trate como string automaticamente. A suposição de que documento é sempre numérico é a causa raiz da maioria dos bugs nessa área.
👉 Clique no botão abaixo para saber mais sobre o assunto!
Pegadinhas que ninguém conta
Dígito verificador não garante unicidade. CPF e CNPJ validados matematicamente podem ser inventados. A validação matemática só confirma que o dígito final bate com os anteriores. Não confirma se o número existe na base da Receita. Para isso, você precisa consultar a API oficial, que no Brasil é a Receita WS ou similar. Isso é opcional em muitos casos, mas essencial se você precisa evitar fraudes ou duplicidade real. A segunda pegadinha é formato versus valor. Um CPF formatado como "123.456.789-00" e outro como "12345678900" são o mesmo documento. Seu sistema precisa normalizar antes de comparar. O método mais confiável é remover tudo que não for dígito e comparar as strings resultantes.
Uma terceira coisa que passa despercebida: alguns sistemas aceitam documentos estrangeiros no mesmo campo que CPF e CNPJ. Isso quebra validações específicas. Se o campo aceita múltiplos tipos, você precisa detectar o tipo pelo tamanho e prefixo antes de aplicar a validação correta. CPF começa com qualquer dígito e tem 11 números. CNPJ começa com certos prefixos (00.000, 01.001, 02.002, 03.003, 04.004, 05.005 para MT; 06.001, 07.001, 08.001, 09.001 para DF, GO, MS, TO, AM, PA, RR; e 11, 12, 13, 14, 15 para SP; 20 para capital; 60, 61, 62, 63, 64, 65 para exterior) e tem 14 números. Qualquer outra coisa precisa de tratamento diferente ou rejeição.
Quando a validação local não é suficiente
Se o seu sistema precisa de confiabilidade alta — processamento de pagamentos, abertura de contas bancárias, conformidade regulatória — a validação puramente local não basta. Você precisa cruzar com fontes oficiais. No Brasil, a API da Receita Federal permite consulta por CPF e CNPJ e retorna situação cadastral, nome, data de abertura, tipo de pessoa, e outros dados. Leva menos de dois segundos por consulta. O custo é baixo, mas tem limitações. A API não retorna dados completos de todas as empresas. Algumas situações cadastrais retornam apenas "situacao" e não o endereço completo. Além disso, a Receita pode sofrer instabilidade pontualmente. Tenha um fallback: se a consulta cair, permita o cadastro com status pendente de validação e agende uma nova tentativa.
Para NIF português, a consulta oficial é feita pelo site das Finanças. Não há API pública confiável. Muitas empresas usam serviços de terceiros como o InfoCDR ou dados.abril.com.br, mas a cobertura varia e o custo por consulta pode subir rápido se o volume for alto.
O que fazer quando tudo falha
Às vezes o usuário informa um documento que não passa em nenhuma validação. O erro mais comum é digitação errada. O CPF 123.456.789-99 com um dígito trocado vai falhar no verificador. Nesse caso, você pode implementar um algoritmo de correção que tenta modificar cada posição e verifica se o resultado é um CPF válido. Funciona para erros de um dígito. Para erros de dois dígitos, a taxa de falsos positivos sobe demais e não vale a pena automatizar. Se o documento for de um país sem estrutura conhecida no seu sistema, ofereça um campo alternativo de "documento internacional" e permita texto livre. Validação automática não funciona para todos os casos. Forçar validação em documentos estrangeiros gera mais problemas do que resolve.
Documentos governamentais como RG, CTPS e título eleitoral têm formatos diferentes e não são usados como chave primária em sistemas modernos. Se o seu formulário pede "número de documento" e o usuário coloca um RG, provavelmente está no campo errado. RG tem validação própria por estado e não tem dígito verificador padronizado nacionalmente. Não tente generalizar.
Resumo prático
Trate número de documento como string. Remova máscaras antes de validar. Implemente a validação matemática dos dígitos verificadores para CPF e CNPJ. Adicione a verificação de dígitos repetidos. Normalize antes de comparar. Use a API da Receita para consultas de confirmação quando necessário. Tenha fallback para quedas de serviço. Aceite que alguns documentos estrangeiros não se encaixam nos formatos brasileiros e crie campos alternativos. E acima de tudo, não assuma que um documento válido matematicamente é um documento válido legalmente. Esses são dois conceitos diferentes que conflitam com frequência.
