واجهة برمجة التطبيقات للتحقق من صحة وتنسيق أرقام الهاتف

واجهة برمجة التطبيقات للتحقق من رقم الهاتف مدعومة في 242 دولة.

تتيح لك واجهة برمجة التطبيقات للتحقق من صحة وتنسيق أرقام الهاتف معالجة أرقام الهاتف التي يدخلها المستخدمون بسهولة، بغض النظر عن تنسيقها. سواء كانت الصيغة غير منتظمة مثل 1(212)-867-53-09 أو +1 212 8675309 أو 001-212.867.5309 أو حتى 2128675309 فقط، فإن واجهتنا تكتشف الهيكل بذكاء وتُرجع إصدارًا موحدًا.

تقوم هذه الأداة تلقائيًا بتحويل الإدخال إلى تنسيق E.164، وهو التنسيق المعترف به عالميًا لأرقام الهاتف الدولية. على سبيل المثال، +1 212 867 5309 يتم إرجاعه كـ +12128675309، مما يجعله مناسبًا لأنظمة الاتصال الدولية والتكاملات المختلفة.

بالإضافة إلى التنسيق، توفر الواجهة قدرات تفصيلية لـالتحقق من صحة الرقم. تتحقق مما إذا كان الرقم isValid: true — أي أنه رقم صالح حسب خطط الترقيم الوطنية. كما تقدم تحققًا من isPossible: true، والذي يشير إلى ما إذا كان الرقم يمكن أن يوجد نظريًا حتى لو لم يتم تخصيصه حاليًا. هذا مفيد للتحقق المسبق قبل الحفظ أو المعالجة.

تساعدك الخاصية numberType على تحديد ما إذا كان الرقم جوالًا أو أرضيًا أو VoIP. هذا مفيد بشكل خاص في الحالات التي تريد فيها السماح فقط بالأرقام الجوالة للتحقق عبر الرسائل النصية القصيرة أو بالأرقام الأرضية للاتصالات المكتبية.

مع دعم التعرف على رمز المنطقة، يمكن للواجهة أيضًا اكتشاف الأصل الجغرافي للرقم. على سبيل المثال، الرقم الذي يبدأ برمز المنطقة 212 يتم تعيينه تلقائيًا إلى مدينة نيويورك (مانهاتن). هذه الميزة مثالية للتطبيقات التي تتطلب تجزئة أو تحليلًا جغرافيًا.

يرتبط كل رقم أيضًا ببيانات وصفية تفصيلية على مستوى الدولة، مثل رمز المنطقة ISO (مثل US) ورمز الدولة الرقمي (مثل 1)، مما يتيح منطقًا وتنسيقات عرض خاصة بالمنطقة في تطبيقاتك.

✅ استجابة واجهة برمجة التطبيقات

مثال على استجابة JSON:

{
  "status": true,
  "remaining_credits": 15709,
  "expires": 0,
  "duration": "18ms",
  "regionCode": "US",
  "countryCode": 1,
  "country":"Unites States",
  "national": "(212) 867-5309",
  "international": "+1 212-867-5309",
  "e164": "+12128675309",
  "isValid": true,
  "isPossible": true,
  "numberType": "FIXED_LINE_OR_MOBILE",
  "nationalSignificantNumber": "2128675309",
  "rawInput": "+1 212 867 5309",
  "isGeographical": true,
  "areaCode": "212",
  "location": "New York City (Manhattan)"
}

جرّب واجهة التحقق من أرقام الهاتف بنفسك

الاستخدام الأساسي

أرسل رقم الهاتف إلى نقطة النهاية التالية:

https://api.genderapi.io/api/phone?key=YOUR_API_KEY&number=12128675309

يمكنك الحصول على مفتاح API مجاني يوميًا يحتوي على 200 رصيد من هذا الرابط.

معامل العنوان (Address)

تدعم الواجهة أيضًا المعامل الاختياري address، والذي يكون مفيدًا بشكل خاص في الحالات التي يتم فيها تقديم رقم الهاتف بدون رمز الدولة الدولي. يساعد هذا الحقل النظام في تحديد المنطقة المقصودة وتحليل الرقم بشكل صحيح. على سبيل المثال، إذا كان الرقم المُدخل هو 2128675309 ولم يتم تحديد رمز الدولة، فإن تعيين address=US أو address=United States أو حتى address=New York يمكن أن يساعد الواجهة في تحديد أن الرقم يعود إلى الولايات المتحدة.

يقبل معامل address إدخالاً بعدة تنسيقات، بما في ذلك:

• رموز ISO 3166-1 alpha-2 مثل US، DE، أو TR
• أسماء الدول مثل Germany، Turkey، أو America
• أسماء المدن أو المناطق مثل Berlin، Istanbul، أو New York

بالرغم من كونه اختياريًا، يصبح address إلزاميًا إذا لم يبدأ رقم الهاتف برمز زائد ورمز الاتصال الدولي (مثل +1، +44، +90). بدون هذه المعلومات السياقية، قد لا تتمكن الواجهة من تفسير تنسيق الرقم بشكل صحيح.

مثال باستخدام معامل address:

https://api.genderapi.io/api/phone?key=YOUR_API_KEY&number=12128675309&address=US

حقول الاستجابة

قيم أنواع الأرقام

curl "https://api.genderapi.io/api/phone?number=+49 151 12345678&address=United States&key=YOUR_API_KEY"

curl "https://api.genderapi.io/api/phone?number=%2B49%20151%2012345678&address=United%20States&key=YOUR_API_KEY"

التحقق من رقم الهاتف عبر طلب POST

يمكنك استخدام طريقة POST للتحقق من رقم هاتف في الولايات المتحدة. فقط قدم رقم الهاتف بتنسيق E.164 أو التنسيق الوطني أو الدولي إلى جانب اسم الدولة أو العنوان. يجب إرسال مفتاح API كرمز Bearer.

مثال باستخدام cURL

curl -X POST "https://api.genderapi.io/api/phone" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"number": "+12128675309", "address": "US"}'

مثال PHP باستخدام cURL

<?php
$url = "https://api.genderapi.io/api/phone";

$data = array(
    "number" => "+12128675309",
    "address" => "US"
);

$payload = json_encode($data);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    "Content-Type: application/json",
    "Authorization: Bearer YOUR_API_KEY"
));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

مثال JavaScript باستخدام fetch

fetch("https://api.genderapi.io/api/phone", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
  },
  body: JSON.stringify({
    number: "+12128675309",
    address: "United States"
  })
})
.then(response => response.json())
.then(data => console.log(data));

مثال Python باستخدام requests

import requests

url = "https://api.genderapi.io/api/phone"

payload = {
    "number": "+12128675309",
    "address": "United States"
}

headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
}

response = requests.post(url, headers=headers, json=payload)

print(response.json())

مكتبات العملاء (Client Libraries)

لتسهيل التكامل بشكل أكبر، نقدم مجموعة من المكتبات الرسمية والمكتبات المدعومة من المجتمع لعدة لغات برمجة. تتيح لك هذه المكتبات التفاعل مع نقاط نهاية GenderAPI — مثل واجهة التحقق من أرقام الهاتف — دون الحاجة إلى التعامل يدويًا مع طلبات HTTP أو تحليل JSON. كل ما عليك هو اختيار المكتبة المناسبة لبيئتك، تثبيتها، والبدء في إرسال الطلبات بأقل إعداد ممكن.

يمكنك العثور على المكتبات المتوفرة وتعليمات التثبيت على الصفحة التالية:
https://www.genderapi.io/ar/docs-client-libraries

الأسئلة الشائعة (FAQ)

1. ما هي واجهة التحقق من صحة وتنسيق أرقام الهاتف؟

هي أداة تتيح لك التحقق من صحة، وتنسيق، وتحليل أرقام الهاتف من جميع أنحاء العالم. يمكنها تحويل الأرقام إلى تنسيق E.164 المعياري وتحديد بيانات مثل المنطقة، النوع (جوال/أرضي)، الصلاحية، وغير ذلك.

2. ما هو الغرض من التحقق من رقم الهاتف؟

يُستخدم للتحقق مما إذا كان الرقم صالحًا، وتنسيقه للاستخدام الدولي، وتحديد نوع الرقم (مثل جوال أو VoIP)، واكتشاف البيانات الجغرافية، وضمان إدخال نظيف وموحد للأرقام في أدوات إدارة العملاء أو أدوات التسويق أو نماذج التسجيل.

3. كم عدد الدول المدعومة؟

تدعم الواجهة أرقام الهاتف من 242 دولة وإقليمًا حول العالم، مما يضمن تغطية عالمية لأي تطبيق دولي أو إقليمي.

4. ما هي التنسيقات المدعومة؟

تقبل الواجهة الأرقام بتنسيقات مختلفة مثل التنسيق الوطني، الدولي، أو تنسيق E.164. يتم اكتشافها وتنسيقها تلقائيًا.

5. ماذا يحدث إذا لم أُدرج معلمة الدولة أو العنوان؟

إذا لم يبدأ الرقم بـ '+' ولم يتم تقديم الدولة أو العنوان، فقد لا تتمكن الواجهة من تفسير الرقم بشكل صحيح. يُوصى بإضافة معلمة address (مثل US أو United States أو New York).

6. هل يمكن للواجهة اكتشاف نوع الرقم؟

نعم، تُرجع الواجهة الحقل numberType والذي يُشير إلى ما إذا كان الرقم MOBILE أو FIXED_LINE أو VOIP، إلخ.

7. ما الفرق بين isValid و isPossible؟

isValid تعني أن الرقم مخصص رسميًا ويتوافق مع جميع القواعد المحلية، بينما isPossible تتحقق مما إذا كان من الممكن أن يوجد الرقم من الناحية الهيكلية حتى لو لم يتم تخصيصه بعد.

8. ما نوع الاستجابة التي تُرجعها الواجهة؟

تتضمن الاستجابة الناجحة الحالة، تنسيقات الأرقام المختلفة (وطني، دولي، E.164)، بيانات المنطقة، نوع الرقم، استخدام الرصيد، والمزيد. راجع قسم "مثال على استجابة API" للحصول على نموذج الإخراج الكامل.

9. كيف يجب أن أرسل مفتاح API الخاص بي؟

لطلبات GET، أضف المفتاح كالتالي: ?key=YOUR_API_KEY. لطلبات POST، استخدم رمز Bearer في الترويسة كما يلي:
"Authorization: Bearer YOUR_API_KEY".

10. ماذا يعني ظهور status: false؟

هذا يعني أن الطلب قد فشل. سيحتوي حقل message على السبب التفصيلي للخطأ، مثل نقص المعلمات أو رقم غير صالح أو عدم كفاية الرصيد.

11. هل يُسمح بالرموز الخاصة أو المسافات في المُدخلات؟

نعم، لكن يجب ترميزها باستخدام URL في طلبات GET. على سبيل المثال، استخدم %20 بدلًا من المسافة. راجع قسم التحذير أعلاه للاستخدام الصحيح.

12. هل يمكنني استخدام العناوين بتنسيقات أو لغات مختلفة؟

نعم. بالإضافة إلى رموز ISO 3166-1 alpha-2 (مثل US، DE، TR)، يقبل معلم address أيضًا أسماء الدول أو المدن — حتى بلغات مختلفة. تستخدم الواجهة ذكاءً اصطناعيًا مدمجًا لاكتشاف وتفسير الدولة أو المنطقة الصحيحة. على سبيل المثال:

address=Deutschland
address=États-Unis
address=İstanbul
address=New York
address=Estados Unidos

سيتم تعيين جميع هذه الإدخالات بشكل صحيح إلى بلدانها أو مناطقها المقابلة من قبل الواجهة بدون أي مشاكل.