1 回の API 呼び出しで電話番号を検証し、E.164 に変換します

サインアップ フォームでは 40 か国の電話番号が収集されます。 ユーザーはあらゆる形式で入力します 想像できるもの: ダッシュ、スペース、括弧、国コードあり、国コードなし。 必要です データベースに保存する前に、これらを E.164 形式に正規化します。 そうでなければ、あなたは 同じ番号が 5 つの異なる表現で表現されることになり、SMS ゲートウェイが拒否します。 そのうちの半分。

Botoi 電話検証 API は、国際電話番号を構造化された応答に解析します。 有効フラグ、E.164 形式、国番号、国コード、および国名。 1 つの POST リクエスト、 libphonenumber のインストールも、300KB バンドルもヒットしません。

1 回のリクエストで電話番号を検証する

電話番号を送信してください /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 flag は、国番号が 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,
  });
});

The raw input goes to the API. The E.164 format comes back. あなたが保管します +14155552671 の代わりに (415) 555-2671 または 415.555.2671 またはその他のバリエーション。 すべてのダウンストリーム システム (Twilio、AWS SNS、Vonage) は E.164 を想定しているため、変換を回避できます。 後で頭痛。

電話番号の CSV を正規化する

5,000 件の連絡先を含む CRM からの CSV エクスポートがあります。 電話欄は混乱しています: いくつかの番号 国コードがあるもの、ないもの、ダッシュが付いているもの、ドットが付いているものがあります。 このスクリプトは 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 バージョン、検出された国、 そして有効フラグ。 無効な行をフィルタリングして手動で修正してから、 clean data into your system.

大きなファイルの場合は、リクエスト間にわずかな遅延を追加するか、リクエストをバッチ処理します。 Promise.all in groups of 5 to stay within rate limits. Paid plans support higher throughput.

電話認証用の Express ミドルウェア

このミドルウェアは、ルート ハンドラーを実行する前に電話番号を検証します。 番号が 無効な場合、リクエストは 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 });
});

電話番号を受け入れるすべてのルートは、同じ検証ロジックを受け取ります。 データベースは常に E.164を格納します。 ルート ハンドラーは解析やフォーマットを処理しません。 彼らは 正規化された番号と国名。

E.164 が重要な理由

E.164 は、国際電話番号の形式に関する ITU-T 標準です。 形式はシンプルです: ある + 記号、国番号、加入者番号をスペースや句読点を含めずに入力します。 例： +14155552671。

• 重複排除。 正規形式を使用しないと、同じ数値が次のように表示されます。 (415) 555-2671、 415-555-2671、 +1 415 555 2671、 そして 14155552671。 E.164 では、4 つすべてが 1 つの文字列に折りたたまれます。
• SMS配信。 Twilio、AWS SNS、Vonage、MessageBird、およびすべての主要な SMS ゲートウェイには E.164 が必要です。 数値を別の形式で保存する場合は、変換が必要です すべての送信の前のステップ。
• データベースのインデックス作成。 単一の形式は電話機に対する独自の制約を意味します コラムは機能します。 混合形式では重複がすり抜けてしまいます。
• 国際的なサポート。 E.164 には国コードが含まれているため、システムは 特殊なケースのロジックを使用しない米国、英国、インド、ブラジルの番号。

重要なポイント

• 1 つのエンドポイントは検証とフォーマットをカバーします。 POST /v1/phone 単一の応答で有効性、E.164、国別形式、国コード、および国名を返します。
• ライブラリは必要ありません。 300KB libphonenumber バンドルをスキップします。 1 回の HTTP 呼び出し 依存関係を置き換えます。
• E.164 を保存し、各国を表示します。 書く e164_format データベースに。 見せる national_format UI に国旗が表示されます。
• 境界で検証します。 ミドルウェアを API ルートなどに追加します。 ダウンストリーム システムはクリーン データを受信します。
• 無料利用枠をご利用いただけます。 API キーなしで 1 分あたり 5 リクエスト。 の有料プラン 実稼働ワークロードは月額 9 ドルから始まります。