التحقق من صحة أرقام الهواتف وتحويلها إلى E.164 من خلال استدعاء API واحد

يجمع نموذج الاشتراك الخاص بك أرقام هواتف من 40 دولة. يقوم المستخدمون بكتابتها بكل تنسيق يمكن تخيله: بشرطات، ومسافات، وأقواس، ورموز البلدان، بدون رموز البلدان. تحتاج لتطبيعها إلى تنسيق E.164 قبل تخزينها في قاعدة البيانات الخاصة بك. وإلا أنت ينتهي بك الأمر بخمسة تمثيلات مختلفة لنفس الرقم، وترفض بوابة الرسائل القصيرة الخاصة بك نصفهم.

تقوم واجهة برمجة التطبيقات للتحقق من صحة هاتف botoi بتوزيع أي رقم هاتف دولي في استجابة منظمة: علامة الصلاحية وتنسيق E.164 والرقم الوطني ورمز البلد واسم البلد. طلب مشاركة واحدة، لم يتم تثبيت 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 مع ملاحظة توضح ما تتوقعه واجهة برمجة التطبيقات.

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 لأرقام الهواتف

لديك تصدير 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 });
});

يحصل كل مسار يقبل رقم هاتف على نفس منطق التحقق من الصحة. قاعدة البيانات الخاصة بك دائما مخازن 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، وجميع الرسائل النصية القصيرة الرئيسية تتطلب البوابة E.164. إذا قمت بتخزين الأرقام بتنسيق مختلف، فستحتاج إلى تحويل خطوة قبل كل إرسال.
• فهرسة قاعدة البيانات. التنسيق الفردي يعني القيد الفريد الخاص بك على الهاتف يعمل العمود. تسمح التنسيقات المختلطة للنسخ المكررة بالمرور.
• الدعم الدولي. يتضمن E.164 رمز البلد، حتى يتمكن نظامك من التعامل معه أرقام الولايات المتحدة والمملكة المتحدة والهند والبرازيل بدون منطق الحالة الخاصة.

النقاط الرئيسية

• نقطة نهاية واحدة تغطي التحقق من الصحة والتنسيق. POST /v1/phone إرجاع الصلاحية، E.164، والتنسيق الوطني، ورمز البلد، واسم البلد في استجابة واحدة.
• لا توجد مكتبة مطلوبة. تخطي حزمة libphonenumber التي يبلغ حجمها 300 كيلو بايت. مكالمة HTTP واحدة يحل محل التبعية.
• مخزن E.164 عرض وطني. يكتب e164_format إلى قاعدة البيانات الخاصة بك. يعرض national_format في واجهة المستخدم مع علم الدولة.
• التحقق من صحة على الحدود. أضف البرامج الوسيطة إلى مسارات API الخاصة بك وكل يتلقى النظام المصب البيانات النظيفة.
• الطبقة المجانية متاحة. 5 طلبات في الدقيقة بدون مفتاح API. الخطط المدفوعة ل تبدأ أعباء عمل الإنتاج بسعر 9 دولارات شهريًا.