واجهة API للتحقق عبر SMS

واجهة API للتحقق عبر SMS هي ثلاثة استدعاءات: اشترِ رقمًا، وانتظر الرمز، وحرّر الرقم. تصل إلى 517 خدمة في 225 دولة، وتبدأ الأرقام من ‏٠٫٠٧ €، والتفعيل الذي لا يستقبل شيئًا يُسترد دون تذكرة دعم. المفاتيح محدودة النطاق، والمشتريات لا تتكرر، وعملاء handler_api القدامى يعملون دون تغيير.

افتح مرجع المطوّرين ابدأ بـ €30

الواجهة في كتلة واحدة

آخر تحديث ٢٨‏/٠٨‏/٢٠٢٦

الرابط الأساسي: https://virtualsmsnumbers.com/api/v1
المصادقة: مفتاح Bearer، أو X-Api-Key
حدّ المعدل: 120 في الدقيقة، اندفاع 20 في الثانية
مهلة عدم التكرار: 24 ساعة
الاسترداد التلقائي بعد: 20 دقيقة
أرخص تفعيل: ‏٠٫٠٧ €
الدول المغطاة: ٢٢٥
الصيغة: JSON، سنتات، ISO 8601 UTC

الأسعار والمخزون مأخوذة من مجمّع المشغّلين بحالته في هذه اللحظة، لا من قائمة أسعار منشورة.

مسار الاستدعاءات الثلاثة

كل ما عدا ذلك في المرجع اختياري. هذا هو مسار التحقق كاملًا، ولم يتغير منذ 2019.

1
POST /activations
اطلب خدمة، ودولة إن كانت تهمّك. تحمل الاستجابة الرقم والسعر بالسنتات وطابع الانتهاء الزمني. أرسل ترويسة Idempotency-Key كي لا يشتري طلب معاد إرساله رقمًا ثانيًا، وأرسل max_price_cents إذا كان المستدعي آليًا.
2
GET /activations/{id}?wait=180
استطلاع طويل. يبقى الاتصال مفتوحًا حتى تصل الرسالة أو تنتهي المهلة، فيحل طلب واحد محل حلقة كانت ستجري تسعين طلبًا. وتعود الحالة بـ code_received مع الرمز المحلَّل إلى جانب النص الخام، لأن المرسِلين يصوغونه بطرق مختلفة.
3
POST /activations/{id}/complete
أغلق التفعيل وحرّر الخط. وإذا لم يصل شيء فلا تفعل شيئًا إطلاقًا: تنتهي المهلة من تلقاء نفسها ويُضاف المبلغ إلى الرصيد. والإلغاء المبكر هو الاستدعاء نفسه باسم آخر.

مثال عملي

اضبط VSN_KEY وشغّله. الاستجابات في التعليقات هي الأشكال الحقيقية، بما فيها الحقول التي ستريد تخزينها.

buy-and-wait.sh

# 1. Buy a Telegram number in Portugal
-kw">curl -X POST https://virtualsmsnumbers.com/api/v1/activations \
  -H "Authorization: Bearer $VSN_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"service":"telegram","country":"PT"}'

# {"id":"1043872915","phone_number":"351926114508","status":"waiting",
#  "price_cents":11,"expires_at":"2026-08-26T12:41:07Z"}

# 2. Long-poll until the code lands (blocks up to 120 s)
-kw">curl "https://virtualsmsnumbers.com/api/v1/activations/1043872915?wait=120" \
  -H "Authorization: Bearer $VSN_KEY"

# {"id":"1043872915","status":"code_received",
#  "messages":[{"code":"48219","text":"Telegram code: 48219"}]}

# 3. Release the number
-kw">curl -X POST https://virtualsmsnumbers.com/api/v1/activations/1043872915/complete \
  -H "Authorization: Bearer $VSN_KEY"

حدود المعدل

120 طلبًا في الدقيقة لكل مفتاح، مع اندفاع حتى 20 في الثانية. وكل استجابة تحمل X-RateLimit-Limit وX-RateLimit-Remaining وX-RateLimit-Reset، والرمز 429 يخبرك بمدة الانتظار بدل أن يتركك تخمّن.

نادرًا ما يكون الحدّ هو القيد إذا استُخدمت الواجهة كما ينبغي: استطلاع طويل واحد بدل تسعين استطلاعًا، وويب هوك بدل مؤقّت، وقوائم الدول والخدمات مخزَّنة عند الإقلاع. وإذا كنت تحتاج هامشًا أكبر فعلًا فاطلبه — رفع الحدّ أسهل لنا ولك من تصحيح أسطول من المفاتيح.

عدم التكرار

أرسل ترويسة Idempotency-Key مع POST /activations. وإعادة إرسال المفتاح نفسه خلال 24 ساعة تعيد التفعيل الأصلي بحالته الراهنة، مع ترويسة Idempotent-Replay، بدل شراء رقم ثانٍ وخصم المبلغ مرتين.

المفتاح ليس تجزئة للجسم: فحمولة مختلفة تحت مفتاح مستعمل تعيد التفعيل الأول نفسه. ولّد مفتاحًا واحدًا لكل عملية شراء منطقية — UUID يفي بالغرض — وأعد استخدامه عبر المحاولات المكررة، لا عبر عمليات شراء مختلفة.

عملاء handler_api القدامى

السكربتات المكتوبة لبروتوكول handler_api.php الكلاسيكي تظل تعمل. وجّهها إلى نقطة التوافق، وبدّل api_key، وستعيد الإجراءات نفسها رموز ACCESS_ وSTATUS_ نفسها كما كانت دائمًا.

هي طبقة ترجمة فوق المجمّع نفسه، فالأسعار والمخزون والاسترداد تتصرف بالطريقة نفسها في الحالتين. ومع ذلك ينبغي للكود الجديد أن يستخدم ‎/api/v1‎: فاستجابات JSON تحمل طوابع زمنية ورموز أخطاء وحقول أسعار لا مكان لها في صيغة الرموز النصية.

legacy-compat.sh

# Existing scripts keep working: same actions, same response tokens.
BASE="https://virtualsmsnumbers.com/stubs/handler_api.php"

-kw">curl "$BASE?api_key=$KEY&action=getNumber&service=tg&country=117"
# ACCESS_NUMBER:1043872915:351926114508

-kw">curl "$BASE?api_key=$KEY&action=getStatus&id=1043872915"
# STATUS_WAIT_CODE
# STATUS_OK:48219

-kw">curl "$BASE?api_key=$KEY&action=setStatus&id=1043872915&status=6"
# ACCESS_ACTIVATION

-kw">curl "$BASE?api_key=$KEY&action=getBalance"
# ACCESS_BALANCE:41.87

الوكلاء وMCP والاكتشاف

يوجد خادم MCP مستضاف، ووثيقة OpenAPI 3.1، وفهرس llms.txt، فيستطيع الوكيل اكتشاف الأدوات الثلاث التي يحتاجها دون كود وصل مكتوب يدويًا. وجّه عميلك إلى النقطة أدناه وسيجد الشراء والانتظار والتحرير.

قبل أن تسمح لأي شيء ذاتي التشغيل بالإنفاق من الرصيد: قصر المفتاح على ‎numbers:read‎ و‎numbers:write‎، وضع سقف max_price_cents على كل عملية شراء، وامنحه مفتاحه الخاص كي لا يوقف إلغاؤه تكاملك في الإنتاج.

مخطط OpenAPI 3.1 فهرس llms.txt

mcp.json

{
  "mcpServers": {
    "virtualsmsnumbers": {
      "type": "http",
      "url": "https://virtualsmsnumbers.com/api/mcp",
      "headers": { "Authorization": "Bearer vsn_live_xxxxxxxxxxxx" }
    }
  }
}

قبل الإنتاج

اضبط max_price_cents على كل عملية شراء. الأسعار تتحرك مع المجمّع، والوكيل بلا حدود سيشتري بطيبة خاطر من طرفه الغالي.
تعامل مع المعرّفات كسلاسل نصية مبهمة. معرّفات التفعيل عشر خانات اليوم؛ وهذا ليس وعدًا، ولا طولها كذلك.
تفرّع على رمز الخطأ لا على الرسالة. الرموز ثابتة داخل الإصدار الواحد؛ أما الرسائل فمكتوبة للبشر ويُعاد كتابتها.
اشترك في sms.received وتحقق من التوقيع — HMAC-SHA256 على الجسم الخام، بنافذة إعادة إرسال خمس دقائق — بدل استطلاع حالة يمكن إخبارك بها.
أجرِ الحسابات على حقول السنتات الصحيحة. أما السلاسل المنسّقة بجانبها فللعرض وتعتمد على اللغة والمنطقة.

المرجع الكامل

ست نقاط نهاية، وجداول أخطاء، وحمولات ويب هوك، ونطاقات صلاحيات، وخريطة الرموز القديمة.

افتح مرجع المطوّرين

استقبال رسائل SMS أونلاين رقم مؤقت الأسعار المباشرة

الأسئلة الشائعة

متوسط الوصول أقل من تسع ثوانٍ من لحظة إرسال الخدمة له. والاستطلاع الطويل موجود لأن الذيل طويل: يبقى التفعيل مفتوحًا 20 دقيقة، ثم ينتهي إلى استرداد إن لم يصل شيء.

لا شيء تحتاج للتعامل معه. تنقضي المهلة، ويُضاف المبلغ إلى الرصيد تلقائيًا، وينتهي التفعيل بحالة expired يمكنك قراءتها من API.

نعم، ولا يكلّف ذلك شيئًا. المفاتيح تحمل نطاقات صلاحيات ثابتة، وقائمة IP مسموحة اختيارية، وتاريخ انتهاء يُختار عند الإنشاء، فمفتاح بيئة الاختبار إذا تسرّب لا يستطيع شراء أرقام في الإنتاج.

توجد أغلفة رفيعة بلا اعتماديات، لكن الواجهة ست نقاط نهاية فوق JSON — وfetch أو requests أو curl يكفي فعلًا لمسار الاستدعاءات الثلاثة.

على تفعيل واحد، نعم: تصل الرسائل الإضافية على الرقم نفسه ما دام مفتوحًا. أما عبر جلسات متعددة فتحتاج استئجارًا يحتفظ بالخط من أربع ساعات إلى اثني عشر شهرًا.

لا. هي المجمّع نفسه بالأسعار نفسها؛ والاختلاف في ترميز الاستجابة فقط.