Números de telefone E.164: o que armazenar e o que um validador não consegue saber

O que é

A Recomendação ITU-T E.164 (citada) define o plano internacional de numeração de telecomunicações públicas: um código de país seguido de um número nacional significativo, escrito no formato internacional com um + inicial. O código-fonte da libphonenumber (citado) observa que a ITU fixa o comprimento máximo em 15 dígitos, mas que a biblioteca aceita números nacionais mais longos, porque eles existem na Alemanha. A lista de suposições falsas do projeto (citada) registra outros limites: o sinal de mais faz parte do formato e nem sempre pode ser substituído por 00, pois o prefixo de chamada internacional varia de país para país; na Itália, um zero inicial após o código do país faz parte do número; e o código de país de um número não diz nada sobre onde o titular mora, em que fuso horário está ou que idioma fala.

Por que importa

Números de telefone são identificadores que as pessoas digitam, copiam de telas e leem em voz alta. Um sistema que os "normaliza" removendo zeros, convertendo para inteiro ou presumindo um único país gera números que chegam ao assinante errado, e um validador que rejeita um formato legítimo impede usuários reais de concluir o cadastro ou fluxos de autenticação em dois fatores.

Como aplicar

• Armazene a forma E.164 como string em uma única coluna (por exemplo, +12025550123), junto com a entrada original e a região usada para interpretar um número digitado em formato nacional; nunca use um tipo inteiro, que descarta zeros iniciais significativos em alguns países e não comporta ramais nem outros caracteres discáveis.
• Faça o parsing com uma biblioteca mantida e seus metadados do plano de numeração; os planos de numeração mudam, então atualize-a da mesma forma que você atualiza um banco de dados de fusos horários.
• Distinga "possível" (comprimento e prefixo plausíveis) de "válido" (corresponde a uma faixa conhecida); use a verificação mais branda para armazenar dados de contato e a mais rigorosa só onde for necessária.
• Comprove a titularidade com um código de uso único por SMS ou chamada de voz antes de usar um número para fins de segurança; a sintaxe não prova nada sobre a acessibilidade.
• Exiba no formato nacional ou internacional conforme o leitor, mas transmita e compare a forma E.164.

Armadilhas

Limitar a validação à região do próprio site rejeita residentes com números estrangeiros, que, segundo a lista da libphonenumber, existem por muitos motivos. Short codes, números de emergência e serviços premium não são números E.164 e exigem tratamento próprio. Ramais (ext. 12) não cabem no formato e pertencem a um campo separado. Dois registros com o mesmo número em formatos de exibição diferentes são o mesmo número; deduplique pelo E.164, não pelo texto como foi digitado.