Valide números de telefone e converta para E.164 com uma chamada de API

Seu formulário de inscrição coleta números de telefone de 40 países. Os usuários os digitam em todos os formatos imaginável: com travessões, espaços, parênteses, códigos de país, sem códigos de país. Você precisa para normalizá-los no formato E.164 antes de armazená-los em seu banco de dados. Caso contrário, você acabar com cinco representações diferentes do mesmo número e seu gateway SMS rejeita metade deles.

A API de validação de telefone botoi analisa qualquer número de telefone internacional em uma resposta estruturada: um sinalizador de validade, formato E.164, número nacional, código do país e nome do país. Uma solicitação POST, nenhuma instalação de libphonenumber, nenhum pacote de 300 KB atingido.

Valide um número de telefone em uma solicitação

Envie um número de telefone para /v1/phone e obtenha um resultado estruturado.

curl -X POST https://api.botoi.com/v1/phone \\
  -H "Content-Type: application/json" \\
  -d '{"phone": "+14155552671"}'

Resposta:

{
  "success": true,
  "data": {
    "phone": "+14155552671",
    "valid": true,
    "country_code": "+1",
    "country": "United States / Canada",
    "e164_format": "+14155552671",
    "national_format": "4155552671"
  }
}

A API retira espaços, travessões e parênteses da entrada, identifica o país a partir do prefixo de discagem e retorna o formato E.164 (para armazenamento) e o formato nacional (para exibição). O valid flag verifica se o número nacional tem entre 7 e 15 dígitos, o que cobre o plano de numeração de cada país.

Exemplos de formato internacional

A API lida com números de mais de 30 países. Espaços, travessões e parênteses na entrada são tudo removido antes da análise.

Country              Input                    E.164               Country code
──────────────────   ───────────────────────  ──────────────────  ────────────
United States        +1 (415) 555-2671        +14155552671        +1
United Kingdom       +44 20 7946 0958         +442079460958       +44
India                +91 98765 43210          +919876543210       +91
Germany              +49 30 1234567           +49301234567        +49
Japan                +81 3-1234-5678          +81312345678        +81
Brazil               +55 11 91234-5678        +5511912345678      +55
Australia            +61 2 1234 5678          +61212345678        +61
Singapore            +65 6123 4567            +6561234567         +65

Número do Reino Unido com espaços

curl -X POST https://api.botoi.com/v1/phone \\
  -H "Content-Type: application/json" \\
  -d '{"phone": "+44 20 7946 0958"}'

Resposta:

{
  "success": true,
  "data": {
    "phone": "+44 20 7946 0958",
    "valid": true,
    "country_code": "+44",
    "country": "United Kingdom",
    "e164_format": "+442079460958",
    "national_format": "2079460958"
  }
}

O que acontece com entrada inválida

Números sem + retorno de prefixo valid: false com uma nota explicando o que a API espera.

curl -X POST https://api.botoi.com/v1/phone \\
  -H "Content-Type: application/json" \\
  -d '{"phone": "555-1234"}'

Resposta:

{
  "success": true,
  "data": {
    "phone": "555-1234",
    "valid": false,
    "country_code": null,
    "country": null,
    "e164_format": null,
    "national_format": null,
    "note": "Phone number should start with \\"+\\" followed by a country code for reliable detection."
  }
}

Sem exceções, sem códigos de erro enigmáticos. Verificar data.valid e mostre ao usuário um mensagem clara.

Validação do formulário de inscrição

O caso de uso mais comum: validar um número de telefone no envio do formulário e armazenar o E.164 versão em vez de tudo o que o usuário digitou. Isso mantém seu banco de dados limpo e seu SMS fornecedor feliz.

async function validatePhone(phone) {
  const res = await fetch("https://api.botoi.com/v1/phone", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ phone }),
  });
  return res.json();
}

// Signup form handler
document.querySelector("#signup-form").addEventListener("submit", async (e) => {
  e.preventDefault();
  const phoneInput = document.querySelector("#phone").value.trim();

  const { data } = await validatePhone(phoneInput);

  if (!data.valid) {
    showError("Enter a valid phone number with country code (e.g. +1 415 555 2671)");
    return;
  }

  // Store the E.164 version, not the raw input
  await createAccount({
    phone: data.e164_format,
    country: data.country,
  });
});

A entrada bruta vai para a API. O formato E.164 está de volta. Você armazena +14155552671 em vez de (415) 555-2671 ou 415.555.2671 ou qualquer outra variação. Todo sistema downstream (Twilio, AWS SNS, Vonage) espera E.164, então você evita conversão dores de cabeça mais tarde.

Normalizar um CSV de números de telefone

Você tem uma exportação CSV de um CRM com 5.000 contatos. A coluna do telefone está uma bagunça: alguns números têm códigos de país, alguns não, alguns têm traços, alguns têm pontos. Este script lê o CSV, valida cada número e grava uma versão limpa com formato E.164 e informações do país.

import { readFileSync, writeFileSync } from "fs";
import { parse } from "csv-parse/sync";
import { stringify } from "csv-stringify/sync";

const records = parse(readFileSync("contacts.csv"), { columns: true });

async function normalizePhone(phone) {
  const res = await fetch("https://api.botoi.com/v1/phone", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ phone }),
  });
  const { data } = await res.json();
  return data;
}

async function processContacts() {
  const results = [];

  for (const row of records) {
    const data = await normalizePhone(row.phone);
    results.push({
      name: row.name,
      original_phone: row.phone,
      e164: data.valid ? data.e164_format : "INVALID",
      country: data.country || "Unknown",
      valid: data.valid,
    });
  }

  writeFileSync("contacts_normalized.csv", stringify(results, { header: true }));
  const invalid = results.filter((r) => !r.valid);
  console.log(\`Processed \\\${results.length} contacts. \\\${invalid.length} invalid.\`);
}

processContacts();

O CSV de saída possui quatro colunas: o telefone original, a versão E.164, o país detectado, e um sinalizador de validade. Você pode filtrar linhas inválidas e corrigi-las manualmente e, em seguida, importar o limpe os dados em seu sistema.

Para arquivos grandes, adicione um pequeno atraso entre as solicitações ou coloque-os em lote com Promise.all em grupos de 5 para permanecer dentro dos limites de taxa. Os planos pagos suportam maior rendimento.

Middleware expresso para validação de telefone

Este middleware valida o número de telefone antes que seu manipulador de rota seja executado. Se o número for inválido, a solicitação obtém uma resposta 422. Se for válido, o middleware substitui a entrada bruta com o formato E.164 normalizado para que seu manipulador sempre receba dados limpos.

import express from "express";

const app = express();
app.use(express.json());

async function validatePhoneMiddleware(req, res, next) {
  const phone = req.body.phone;

  if (!phone) {
    return res.status(400).json({ error: "Phone number is required" });
  }

  const apiRes = await fetch("https://api.botoi.com/v1/phone", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ phone }),
  });
  const { data } = await apiRes.json();

  if (!data.valid) {
    return res.status(422).json({
      error: "Invalid phone number",
      detail: "Provide an international number starting with + and a country code",
    });
  }

  // Replace raw input with normalized E.164 format
  req.body.phone = data.e164_format;
  req.body.phoneCountry = data.country;
  next();
}

app.post("/users", validatePhoneMiddleware, async (req, res) => {
  // req.body.phone is now in E.164 format
  const user = await db.users.create({
    email: req.body.email,
    phone: req.body.phone,        // "+14155552671"
    phoneCountry: req.body.phoneCountry, // "United States / Canada"
  });

  res.status(201).json({ id: user.id });
});

Toda rota que aceita um número de telefone obtém a mesma lógica de validação. Seu banco de dados sempre armazena E.164. Seus manipuladores de rotas nunca lidam com análise ou formatação; eles recebem um número normalizado e um nome de país.

Por que E.164 é importante

E.164 é o padrão ITU-T para formatação de números de telefone internacionais. O formato é simples: um + sinal, o código do país e o número do assinante, sem espaços ou pontuação. Exemplo: +14155552671.

• Desduplicação. Sem um formato canônico, o mesmo número aparece como (415) 555-2671, 415-555-2671, +1 415 555 2671, e 14155552671. E.164 reúne todos os quatro em uma string.
• Entrega de SMS. Twilio, AWS SNS, Vonage, MessageBird e todos os principais SMS gateway requer E.164. Se você armazenar números em um formato diferente, precisará de uma conversão passo antes de cada envio.
• Indexação de banco de dados. Um formato único significa sua restrição exclusiva no telefone coluna funciona. Formatos mistos permitem que duplicatas escapem.
• Apoio internacional. E.164 inclui o código do país, então seu sistema lida com Números dos EUA, Reino Unido, Índia e Brasil sem lógica de casos especiais.

Pontos-chave

• Um endpoint cobre validação e formatação. POST /v1/phone retorna validade, E.164, formato nacional, código do país e nome do país em uma única resposta.
• Não é necessária biblioteca. Ignore o pacote libphonenumber de 300 KB. Uma chamada HTTP substitui a dependência.
• Loja E.164, display nacional. Escrever e164_format para seu banco de dados. Mostrar national_format na IU com a bandeira do país.
• Valide no limite. Adicione o middleware às suas rotas de API e cada o sistema downstream recebe dados limpos.
• Nível gratuito disponível. 5 solicitações por minuto sem chave de API. Planos pagos para as cargas de trabalho de produção começam em US$ 9/mês.