Проверка телефонных номеров и преобразование в E.164 с помощью одного вызова API

В вашей регистрационной форме собраны номера телефонов из 40 стран. Пользователи вводят их в любом формате. мыслимые: с тире, пробелами, круглыми скобками, кодами стран, без кодов стран. Вам нужно чтобы нормализовать их в формат E.164 перед сохранением в базе данных. В противном случае вы в конечном итоге вы получите пять разных представлений одного и того же номера, и ваш SMS-шлюз отклонит половина из них.

API проверки телефона botoi анализирует любой международный номер телефона в структурированный ответ: флаг действительности, формат E.164, национальный номер, код страны и название страны. Один POST-запрос, нет установки libphonenumber, нет пакета размером 300 КБ.

Подтвердить номер телефона одним запросом

Отправьте номер телефона на /v1/phone и получите структурированный результат.

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

Ответ:

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

API удаляет пробелы, тире и круглые скобки из входных данных, определяет страну из префикс набора номера и возвращает как формат E.164 (для хранения), так и национальный формат (для отображения). valid флаг проверяет, что национальный номер содержит от 7 до 15 цифр, что охватывает план нумерации каждой страны.

Примеры международного формата

API обрабатывает номера из более чем 30 стран. Пробелы, тире и круглые скобки во входных данных все зачищено перед разбором.

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

Номер Великобритании с пробелами

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

Ответ:

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

Что происходит при неверном вводе

Числа без + возврат префикса valid: false с поясняющей запиской что ожидает API.

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

Ответ:

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

Никаких исключений, никаких загадочных кодов ошибок. Проверять data.valid и показать пользователю ясное сообщение.

Проверка формы регистрации

Наиболее распространенный вариант использования: проверка номера телефона при отправке формы, затем сохранение E.164. версию вместо того, что набрал пользователь. Это сохранит вашу базу данных в чистоте и ваши SMS-сообщения. провайдер доволен.

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

Необработанный ввод поступает в API. Формат E.164 возвращается. Вы храните +14155552671 вместо (415) 555-2671 или 415.555.2671 или любой другой вариант. Каждая нижестоящая система (Twilio, AWS SNS, Vonage) ожидает E.164, поэтому вы избегаете преобразования головные боли позже.

Нормализовать CSV телефонных номеров

У вас есть экспорт CSV из CRM с 5000 контактами. В телефонной колонке беспорядок: какие-то цифры есть коды стран, у некоторых нет, у некоторых есть тире, у некоторых есть точки. Этот скрипт читает CSV, проверяет каждое число и записывает чистую версию с форматом E.164 и информацией о стране.

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

Выходной CSV-файл имеет четыре столбца: исходный телефон, версия E.164, обнаруженная страна, и флаг достоверности. Вы можете отфильтровать недопустимые строки и исправить их вручную, а затем импортировать очистите данные в вашей системе.

Для больших файлов добавьте небольшую задержку между запросами или группируйте их с помощью Promise.all в группах по 5 человек, чтобы оставаться в пределах нормы. Платные планы поддерживают более высокую пропускную способность.

Экспресс-промежуточное программное обеспечение для проверки телефона

Это промежуточное программное обеспечение проверяет номер телефона перед запуском обработчика маршрута. Если число недействителен, запрос получает ответ 422. Если это действительно так, промежуточное программное обеспечение заменяет необработанные входные данные. с нормализованным форматом E.164, чтобы ваш обработчик всегда получал чистые данные.

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

Каждый маршрут, принимающий номер телефона, получает одну и ту же логику проверки. Ваша база данных всегда хранит Е.164. Ваши обработчики маршрутов никогда не занимаются анализом или форматированием; они получают нормализованный номер и название страны.

Почему E.164 имеет значение

E.164 — это стандарт ITU-T для форматирования международных телефонных номеров. Формат прост: а + знак, код страны и номер абонента без пробелов и знаков препинания. Пример: +14155552671.

• Дедупликация. Без канонического формата то же число отображается как (415) 555-2671, 415-555-2671, +1 415 555 2671, и 14155552671. E.164 объединяет все четыре в одну строку.
• Доставка СМС. Twilio, AWS SNS, Vonage, MessageBird и все основные SMS-сообщения. шлюз требует E.164. Если вы храните числа в другом формате, вам потребуется преобразование шаг перед каждой отправкой.
• Индексация базы данных. Единый формат означает ваши уникальные ограничения на телефоне. колонка работает. Смешанные форматы позволяют избежать дублирования.
• Международная поддержка. E.164 включает код страны, поэтому ваша система обрабатывает Числа США, Великобритании, Индии и Бразилии без специальной логики.

Ключевые моменты

• Одна конечная точка охватывает проверку и форматирование. POST /v1/phone возвращает действительность, E.164, национальный формат, код страны и название страны в одном ответе.
• Библиотека не требуется. Пропустите пакет libphonenumber размером 300 КБ. Один HTTP-вызов заменяет зависимость.
• Магазин E.164, дисплей национальный. Писать e164_format в вашу базу данных. Показывать national_format в пользовательском интерфейсе с флагом страны.
• Подтвердить на границе. Добавьте промежуточное программное обеспечение в свои маршруты API и все Последующая система получает чистые данные.
• Доступен бесплатный уровень. 5 запросов в минуту без ключа API. Платные планы для производственные нагрузки начинаются от 9 долларов в месяц.