Valide números de teléfono y conviértalos a E.164 con una llamada API

Su formulario de registro recopila números de teléfono de 40 países. Los usuarios los escriben en todos los formatos. imaginable: con guiones, espacios, paréntesis, códigos de país, sin códigos de país. necesitas para normalizarlos al formato E.164 antes de almacenarlos en su base de datos. De lo contrario, usted terminará con cinco representaciones diferentes del mismo número y su puerta de enlace de SMS lo rechazará. la mitad de ellos.

La API de validación de teléfonos de botoi analiza cualquier número de teléfono internacional en una respuesta estructurada: una bandera de validez, formato E.164, número nacional, código de país y nombre de país. Una solicitud POST, no se instala libphonenumber, no se alcanza el paquete de 300 KB.

Validar un número de teléfono en una sola solicitud

Enviar un número de teléfono a /v1/phone y obtener un resultado estructurado.

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

Respuesta:

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

La API elimina espacios, guiones y paréntesis de la entrada, identifica el país desde el prefijo de marcación y devuelve tanto el formato E.164 (para almacenamiento) como el formato nacional (para visualización). El valid flag comprueba que el número nacional tenga entre 7 y 15 dígitos, lo que cubre el plan de numeración de cada país.

Ejemplos de formato internacional

La API maneja números de más de 30 países. Los espacios, guiones y paréntesis en la entrada son todo despojado antes del análisis.

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 del Reino Unido con espacios

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

Respuesta:

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

¿Qué sucede con una entrada no válida?

números sin + retorno de prefijo valid: false con una nota explicando lo que espera la API.

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

Respuesta:

{
  "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."
  }
}

Sin excepciones, sin códigos de error crípticos. Controlar data.valid y mostrar al usuario un mensaje claro.

Validación del formulario de registro

El caso de uso más común: validar un número de teléfono al enviar el formulario y luego almacenar el E.164 versión en lugar de lo que el usuario haya escrito. Esto mantiene limpia su base de datos y sus SMS Proveedor 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,
  });
});

La entrada sin procesar va a la API. Vuelve el formato E.164. tu almacenas +14155552671 en lugar de (415) 555-2671 o 415.555.2671 o cualquier otra variación. Todos los sistemas posteriores (Twilio, AWS SNS, Vonage) esperan E.164, por lo que evita la conversión. dolores de cabeza más tarde.

Normalizar un CSV de números de teléfono

Tienes una exportación CSV desde un CRM con 5.000 contactos. La columna del teléfono es un desastre: algunos números tienen códigos de país, algunos no, algunos tienen guiones, otros tienen puntos. Este script lee el CSV, valida cada número y escribe una versión limpia con formato E.164 e información del 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();

El CSV de salida tiene cuatro columnas: el teléfono original, la versión E.164, el país detectado, y una bandera de validez. Puede filtrar filas no válidas y corregirlas manualmente, luego importar el limpiar datos en su sistema.

Para archivos grandes, agregue un pequeño retraso entre solicitudes o agrupelos con Promise.all en grupos de 5 para mantenerse dentro de los límites de tarifa. Los planes pagos admiten un mayor rendimiento.

Middleware exprés para validación telefónica

Este middleware valida el número de teléfono antes de que se ejecute el controlador de ruta. Si el número es no válida, la solicitud obtiene una respuesta 422. Si es válido, el middleware reemplaza la entrada sin formato. con el formato E.164 normalizado para que su controlador siempre reciba datos limpios.

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 });
});

Cada ruta que acepta un número de teléfono recibe la misma lógica de validación. Tu base de datos siempre almacena E.164. Sus controladores de ruta nunca se ocupan del análisis ni del formateo; ellos reciben un número normalizado y un nombre de país.

Por qué es importante E.164

E.164 es el estándar ITU-T para el formato de números de teléfono internacionales. El formato es sencillo: un + signo, el código del país y el número de abonado, sin espacios ni puntuación. Ejemplo: +14155552671.

• Deduplicación. Sin un formato canónico, el mismo número aparece como (415) 555-2671, 415-555-2671, +1 415 555 2671, y 14155552671. E.164 colapsa los cuatro en una sola cadena.
• Entrega de SMS. Twilio, AWS SNS, Vonage, MessageBird y todos los SMS importantes La puerta de enlace requiere E.164. Si almacena números en un formato diferente, necesita una conversión paso antes de cada envío.
• Indexación de bases de datos. Un formato único significa su restricción única en el teléfono trabajos de columna. Los formatos mixtos dejan pasar los duplicados.
• Apoyo internacional. E.164 incluye el código de país, por lo que su sistema maneja Números de EE. UU., Reino Unido, India y Brasil sin lógica de casos especiales.

Puntos clave

• Un punto final cubre la validación y el formato. POST /v1/phone devuelve validez, E.164, formato nacional, código de país y nombre de país en una sola respuesta.
• No se requiere biblioteca. Omita el paquete libphonenumber de 300 KB. Una llamada HTTP reemplaza la dependencia.
• Tienda E.164, display nacional. Escribir e164_format a su base de datos. Espectáculo national_format en la interfaz de usuario con la bandera del país.
• Validar en el límite. Agregue el middleware a sus rutas API y a cada El sistema aguas abajo recibe datos limpios.
• Nivel gratuito disponible. 5 solicitudes por minuto sin clave API. Planes pagados para las cargas de trabajo de producción comienzan en $9/mes.