通过一次 API 调用验证电话号码并转换为 E.164

您的注册表单收集了来自 40 个国家/地区的电话号码。 用户以各种格式输入它们 可想象的：带破折号、空格、括号、国家/地区代码、不带国家/地区代码。 你需要 在将它们存储到数据库之前将它们标准化为 E.164 格式。 否则，你 最终同一号码有五种不同的表示形式，并且您的 SMS 网关会拒绝 其中一半。

botoi 电话验证 API 将任何国际电话号码解析为结构化响应： 有效性标志、E.164 格式、国家编号、国家代码和国家名称。 一个 POST 请求， 没有安装 libphonenumber，没有 300KB 捆绑包。

在一次请求中验证电话号码

发送电话号码至 /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 版本而不是用户输入的任何内容。 这可以保持您的数据库和短信的干净 提供商高兴。

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 电话号码

您从包含 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 版本、检测到的国家/地区、 和有效性标志。 您可以过滤无效行并手动修复它们，然后导入 将数据清理到您的系统中。

对于大文件，在请求之间添加一个小的延迟或使用 Promise.all 以 5 人为一组，以保持在速率限制之内。 付费计划支持更高的吞吐量。

用于电话验证的 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 将所有四个压缩为一根字符串。
• 短信发送。 Twilio、AWS SNS、Vonage、MessageBird 以及所有主要 SMS 网关需要 E.164。 如果您以不同的格式存储数字，则需要转换 每次发送之前的步骤。
• 数据库索引。 单一格式意味着您对手机的独特限制 专栏作品。 混合格式可以让重复的内容漏掉。
• 国际支持。 E.164 包含国家/地区代码，因此您的系统可以处理 美国、英国、印度和巴西的数字，没有特殊情况逻辑。

要点

• 一个端点涵盖验证和格式化。 POST /v1/phone 在单个响应中返回有效性、E.164、国家格式、国家代码和国家名称。
• 无需图书馆。 跳过 300KB libphonenumber 捆绑包。 一次 HTTP 调用 取代依赖。
• 存储E.164，显示国家。 写 e164_format 到您的数据库。 展示 national_format 在带有国旗的 UI 中。
• 在边界处验证。 将中间件添加到您的 API 路由和每个 下游系统接收干净的数据。
• 提供免费套餐。 每分钟 5 个请求，无需 API 密钥。 付费计划 生产工作负载起价为 9 美元/月。