Validasi nomor telepon dan konversikan ke E.164 dengan satu panggilan API

Formulir pendaftaran Anda mengumpulkan nomor telepon dari 40 negara. Pengguna mengetiknya dalam setiap format bisa dibayangkan: dengan tanda hubung, spasi, tanda kurung, kode negara, tanpa kode negara. Anda membutuhkan untuk menormalkannya ke dalam format E.164 sebelum menyimpannya di database Anda. Jika tidak, kamu berakhir dengan lima representasi berbeda dari nomor yang sama, dan gateway SMS Anda ditolak setengah dari mereka.

API validasi telepon botoi menguraikan nomor telepon internasional apa pun menjadi respons terstruktur: bendera validitas, format E.164, nomor nasional, kode negara, dan nama negara. Satu permintaan POST, tidak ada instalasi libphonenumber, tidak ada bundel 300KB yang tercapai.

Validasi nomor telepon dalam satu permintaan

Kirim nomor telepon ke /v1/phone dan mendapatkan kembali hasil terstruktur.

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

Tanggapan:

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

API menghapus spasi, tanda hubung, dan tanda kurung dari masukan, mengidentifikasi negara dari masukan tersebut awalan panggilan, dan mengembalikan format E.164 (untuk penyimpanan) dan format nasional (untuk tampilan). Itu valid bendera memeriksa apakah nomor nasional memiliki antara 7 dan 15 digit, yang mana mencakup rencana penomoran setiap negara.

Contoh format internasional

API menangani nomor dari 30+ negara. Spasi, tanda hubung, dan tanda kurung pada masukan adalah semua dilucuti sebelum diurai.

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

Nomor Inggris dengan spasi

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

Tanggapan:

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

Apa yang terjadi jika masukan tidak valid

Angka tanpa a + awalan kembali valid: false dengan catatan yang menjelaskan apa yang diharapkan API.

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

Tanggapan:

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

Tidak ada pengecualian, tidak ada kode kesalahan yang samar. Memeriksa data.valid dan tunjukkan kepada pengguna a pesan yang jelas.

Validasi formulir pendaftaran

Kasus penggunaan yang paling umum: validasi nomor telepon pada pengiriman formulir, lalu simpan E.164 versi, bukan apa pun yang diketik pengguna. Ini menjaga database Anda tetap bersih dan SMS Anda penyedia senang.

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

Masukan mentah masuk ke API. Format E.164 kembali hadir. Anda menyimpan +14155552671 alih-alih (415) 555-2671 atau 415.555.2671 atau variasi lainnya. Setiap sistem hilir (Twilio, AWS SNS, Vonage) mengharapkan E.164, sehingga Anda menghindari konversi sakit kepala nanti.

Normalisasikan CSV nomor telepon

Anda memiliki ekspor CSV dari CRM dengan 5.000 kontak. Kolom telepon berantakan: beberapa nomor ada yang punya kode negara, ada yang tidak, ada yang punya tanda hubung, ada yang punya titik. Skrip ini membaca CSV, memvalidasi setiap nomor, dan menulis versi bersih dengan format E.164 dan info negara.

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 keluaran memiliki empat kolom: telepon asli, versi E.164, negara yang terdeteksi, dan tanda validitas. Anda dapat memfilter baris yang tidak valid dan memperbaikinya secara manual, lalu mengimpornya membersihkan data ke dalam sistem Anda.

Untuk file besar, tambahkan sedikit jeda antar permintaan atau batch dengan Promise.all dalam kelompok 5 orang untuk tetap dalam batas tarif. Paket berbayar mendukung throughput yang lebih tinggi.

Middleware ekspres untuk validasi telepon

Middleware ini memvalidasi nomor telepon sebelum pengendali rute Anda berjalan. Jika nomornya tidak valid, permintaan mendapat respons 422. Jika valid, middleware akan menggantikan input mentah dengan format E.164 yang dinormalisasi sehingga handler Anda selalu menerima data yang bersih.

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

Setiap rute yang menerima nomor telepon mendapatkan logika validasi yang sama. Basis data Anda selalu toko E.164. Penangan rute Anda tidak pernah berurusan dengan penguraian atau pemformatan; mereka menerima a nomor yang dinormalisasi dan nama negara.

Mengapa E.164 penting

E.164 adalah standar ITU-T untuk pemformatan nomor telepon internasional. Formatnya sederhana: sebuah + tanda tangan, kode negara, dan nomor pelanggan, tanpa spasi atau tanda baca. Contoh: +14155552671.

• Deduplikasi. Tanpa format kanonik, nomor yang sama akan muncul sebagai (415) 555-2671, 415-555-2671, +1 415 555 2671, Dan 14155552671. E.164 meruntuhkan keempatnya menjadi satu string.
• Pengiriman SMS. Twilio, AWS SNS, Vonage, MessageBird, dan setiap SMS utama gateway memerlukan E.164. Jika Anda menyimpan angka dalam format berbeda, Anda memerlukan konversi langkah sebelum setiap pengiriman.
• Pengindeksan basis data. Format tunggal berarti batasan unik Anda pada ponsel kolom berfungsi. Format campuran membiarkan duplikat lolos.
• Dukungan internasional. E.164 menyertakan kode negara, sehingga sistem Anda akan menanganinya Nomor AS, Inggris, India, dan Brasil tanpa logika kasus khusus.

Poin-poin penting

• Satu titik akhir mencakup validasi dan pemformatan. POST /v1/phone validitas pengembalian, E.164, format nasional, kode negara, dan nama negara dalam satu tanggapan.
• Tidak diperlukan perpustakaan. Lewati bundel libphonenumber 300KB. Satu panggilan HTTP menggantikan ketergantungan.
• Simpan E.164, tampilan nasional. Menulis e164_format ke basis data Anda. Menunjukkan national_format di UI dengan bendera negara.
• Validasi di batas. Tambahkan middleware ke rute API Anda dan semuanya sistem hilir menerima data bersih.
• Tersedia tingkat gratis. 5 permintaan per menit tanpa kunci API. Paket berbayar untuk beban kerja produksi mulai dari $9/bulan.