Telefone para Formato E.164 com Python

Como resolver o problema na inconsistência nos formatos de números de telefone


Autor: Réulison Silva Publicado em: Julho 28, 2025

Contexto: O desafio dos dados inconsistentes

Profissionais de marketing que trabalham com campanhas de SMS e WhatsApp Business enfrentam um desafio recorrente: a inconsistência nos formatos de números de telefone.

Ao importar uma base de contatos de diferentes fontes (landing pages, CRM, cadastros manuais, etc.), é comum encontrar números em formatos variados como:

  • 27981275377
  • (21) 98549-4299
  • 5519991772715

Esse cenário impede que ferramentas de automação reconheçam corretamente os números — o que compromete a entrega das mensagens e os resultados das campanhas.

Para resolver esse problema, o código abaixo padroniza todos os números para o formato internacional E.164, exigido por plataformas como Twilio, Bird, Zenvia, 360Dialog (WhatsApp API), entre outras.

O que é o formato E.164?

O formato E.164 é o padrão internacional para formatação de números de telefone. Ele garante que o número:

  • Comece com um sinal de +
  • Seja seguido do DDI (código do país), como 55 para o Brasil
  • Inclua o DDD e o número local

Exemplo: Número local: 21 98599-4299 → Formato E.164: +5521985994299

Código explicado passo a passo

import pandas as pd
import re

Importa as bibliotecas necessárias:

  • pandas: para criar e exportar a planilha
  • re: para manipular e limpar os números usando expressões regulares

1. Entrada dos dados

numeros_raw = """
27981275377
(21) 98599-4299
5519991772715
"""

Simula uma base de dados com números em formatos diferentes.

⚠️ Em um uso real, esses dados poderiam vir de um CSV, planilha, banco de dados, formulário etc.

2. Preparação da lista

numeros = [linha.strip() for linha in numeros_raw.strip().splitlines() if linha.strip()]

Essa linha faz a limpeza dos dados:

  • Remove espaços em branco antes/depois de cada número
  • Descarta linhas vazias

3. Função de formatação

def formatar_e164(numero):
    # Remove tudo que não for dígito
    numero_limpo = re.sub(r'\D', '', numero)

    # Remove DDI se já tiver
    if numero_limpo.startswith("55"):
        numero_limpo = numero_limpo[2:]

    # Garantir que o número tenha pelo menos DDD + número
    if len(numero_limpo) >= 10:
        return f'+55{numero_limpo}'
    else:
        return f'Número inválido: {numero}'

Essa função:

  • Remove tudo que não é número, como parênteses, traços, espaços, etc.
  • Remove o DDI “55”, caso o número já tenha
  • Valida se tem pelo menos 10 dígitos (DDD + número)
  • Retorna o número formatado no padrão +55xxxxxxxxxx
  • Caso contrário, sinaliza que o número é inválido

4. Aplicação da função

numeros_formatados = [formatar_e164(n) for n in numeros]

Aplica a formatação em todos os números da lista.

5. Exportar para Excel

df = pd.DataFrame({'Telefone': numeros_formatados})
df.to_excel('numeros_formatados.xlsx', index=False)

Cria uma planilha chamada numeros_formatados.xlsx com os números já prontos para uso em ferramentas de disparo.

Resultado final (exemplo da planilha)

Telefone
+5527981275377
+5521985994299
+5519991772715

Conclusão

Esse pequeno script em Python ajuda times de marketing a economizar tempo e evitar erros ao padronizar seus contatos para campanhas de WhatsApp e SMS.

Ele garante que os números estejam no formato exigido pelas plataformas de disparo, evitando bloqueios, rejeições e melhorando a taxa de entrega das mensagens.

Você pode adaptar esse código para:

  • Ler direto de um .csv ou .xlsx
  • Validar números por DDD
  • Enviar relatórios com números inválidos
  • Rodar como parte de uma automação (ex: via Airflow ou cron job)

No meu caso, eu copiei a coluna de números de telefones de uma planilha enviada a mim com vários números em formatos diferentes, apliquei na função e depois colei de volta na planilha já com os números no formato E.164 na mesma ordem.

Essa é uma das pequenas situações onde profissionais de marketing que sabem programar se destacam. Segue código completo no meu Github.

FAQ – Padronização de Números para Formato E.164 com Python

1. O que é o formato E.164 e por que ele é importante?

O formato E.164 é o padrão internacional para números de telefone. Ele começa com +, seguido do código do país (DDI), DDD e o número local.

Por exemplo, um número do Rio de Janeiro (21) seria formatado como: +5521987654321. Esse padrão é exigido por APIs e plataformas de envio de mensagens como WhatsApp Business, Twilio, Zenvia, entre outras.

2. Por que preciso padronizar os números da minha base?

Bases de dados costumam ter números em diversos formatos, como com parênteses, traços, espaços, ou até com DDI duplicado. Isso pode causar falhas nos envios de mensagens em campanhas de SMS ou WhatsApp. Padronizar para o formato E.164 garante a entrega correta das mensagens.

3. Esse código funciona com números internacionais também?

Atualmente, o código está configurado para números brasileiros (DDI +55). Para adaptá-lo a outros países, seria necessário identificar e tratar diferentes DDIs dinamicamente, além de considerar regras específicas de cada país.

4. E se o número não tiver DDD?

A função só formata números com pelo menos 10 dígitos (DDD + número). Se o número tiver apenas 8 ou 9 dígitos, ele será marcado como inválido. Nesse caso, você pode revisar a base ou criar regras adicionais para inserir DDDs padrão, se fizer sentido para o seu caso.

5. Como posso usar esse código com uma planilha Excel real?

Você pode substituir a entrada numeros_raw por uma leitura direta de um arquivo .xlsx com a biblioteca pandas:

df = pd.read_excel('sua_planilha.xlsx')
numeros = df['coluna_com_telefone'].astype(str).tolist()

Assim, você automatiza todo o processo desde a leitura da base até a exportação dos números formatados.

6. Posso validar se os números são reais ou ativos?

Não. Esse script apenas formata os números. Para validar se um número está ativo ou é válido para WhatsApp, você precisaria usar APIs específicas, como a WhatsApp Business API ou serviços de verificação de número (HLR Lookup), que podem ter custo.

7. Como posso adaptar esse código para uso contínuo ou em larga escala?

Você pode:

  • Integrar esse script a um processo automatizado (via agendador, como cron ou Airflow)
  • Ler arquivos CSV diretamente de uma pasta monitorada
  • Gerar relatórios com erros ou números inválidos
  • Adaptar para rodar como uma aplicação web (com Flask, por exemplo)

8. O código funciona em qualquer computador?

Sim, desde que você tenha o Python instalado e as bibliotecas pandas e openpyxl (para salvar em Excel). Você pode instalá-las com:

pip install pandas openpyxl
Leia também