البدء السريع مع واجهة API للمطورين

تمنح واجهة API للمطورين من SmsGrab برنامجك الأرقام نفسها الموجودة في التطبيق، عبر واجهة REST تتعامل بصيغة JSON. إنها منتج مدفوع بـ أسعار مطورين خاصة، يُدفع من رصيد SmsGrab المعتاد وتشمله عمليات الاسترداد التلقائية نفسها.

من يمكنه استخدامها

• حساب بريد إلكتروني بعنوان مؤكد. لا يمكن لحسابات الضيوف إنشاء مفاتيح.
• حساب بلا قيود.

1. أنشئ مفتاح API

افتح الحساب > المطوّرون على الموقع، أو الإعدادات > واجهة API للمطورين في التطبيق، وأنشئ مفتاحًا. للأمان تؤكد بكلمة المرور، وبرمز التحقق بخطوتين إذا كان مفعّلًا. اختر النطاق read للأدوات التي تقرأ فقط، أو read وpurchase لشراء الأرقام.

يبدأ المفتاح بـ sgk_ ويُعرض مرة واحدة فقط. احفظه في مخزن الأسرار على خادمك. راجع مفاتيح API والأمان.

2. المصادقة

عنوان URL الأساسي هو https://smsgrab.com/api/dev/v1. أرسل المفتاح كرمز bearer، أو في الترويسة X-Api-Key:

GET /api/dev/v1/balance HTTP/1.1
Host: smsgrab.com
Authorization: Bearer sgk_your_key_here

مكان المفاتيح هو الخوادم. لا تضعها أبدًا في موقع ويب أو إضافة متصفح أو تطبيق توزّعه على الآخرين.

3. تحقّق من رصيدك والأسعار

export SMSGRAB_KEY="sgk_your_key_here"

curl -s https://smsgrab.com/api/dev/v1/balance \
  -H "Authorization: Bearer $SMSGRAB_KEY"

curl -s "https://smsgrab.com/api/dev/v1/prices?service=whatsapp&country=indonesia" \
  -H "Authorization: Bearer $SMSGRAB_KEY"

تُعطى المبالغ دائمًا بالوحدات الصغرى من USD، لذا فإن 18 تعني 0.18 USD. الحقل price_minor هو سعر المطور الخاص بك وretail_price_minor هو سعر التطبيق.

{ "currency": "USD", "markup_percent": 80,
  "items": [ { "service_id": "whatsapp", "country_id": "indonesia", "price_minor": 18,
               "retail_price_minor": 25, "available_numbers": 30412 } ] }

4. اشترِ رقمًا

curl -s -X POST https://smsgrab.com/api/dev/v1/activations \
  -H "Authorization: Bearer $SMSGRAB_KEY" \
  -H "Idempotency-Key: order-7f3c2a" \
  -H "Content-Type: application/json" \
  -d '{"service":"whatsapp","country":"indonesia","max_price_minor":20}'

• يقبل service وcountry معرّفاتنا، مثل whatsapp وindonesia. وتقبل الدول أيضًا رموز ISO مثل ID.
• يحميك max_price_minor: إذا ارتفع السعر، لا يُخصم شيء وتحصل على 409 PRICE_CHANGED.
• يجعل Idempotency-Key إعادة المحاولة آمنة. تكرار الطلب بالمفتاح نفسه يعيد النتيجة الأولى بدلًا من الشراء مرتين.

الرد هو 201 Created مع التفعيل:

{ "id": "5c1d0c2e-8a41-4f7e-9d7a-2f1d9f1b8c11", "compat_id": 100000123, "status": "WAITING_SMS",
  "service_id": "whatsapp", "country_id": "indonesia", "phone_number": "+6281234567890",
  "price_minor": 18, "currency": "USD",
  "created_at": "2026-09-27T10:05:00.000Z", "expires_at": "2026-09-27T10:25:00.000Z",
  "refunded": false, "refund_minor": 0, "sms": [] }

5. انتظر الرسالة

بدلًا من الاستعلام في حلقة متقاربة، دع الواجهة تحتفظ بالطلب حتى 30 ثانية إلى أن يتغير شيء:

curl -s "https://smsgrab.com/api/dev/v1/activations/100000123?wait=25" \
  -H "Authorization: Bearer $SMSGRAB_KEY"

عند وصول رسالة، تصبح status بقيمة CODE_RECEIVED ويحتوي sms على كل الرسائل حتى الآن:

{ "status": "CODE_RECEIVED",
  "sms": [ { "code": "482913", "text": "Your WhatsApp code is 482-913", "sender": "WhatsApp",
             "received_at": "2026-09-27T10:06:12.004Z" } ] }

تفضّل الإشعارات الفورية على الاستعلام؟ اضبط خطافات الويب.

6. أنهِ أو ألغِ

curl -s -X POST https://smsgrab.com/api/dev/v1/activations/100000123/finish \
  -H "Authorization: Bearer $SMSGRAB_KEY"

curl -s -X POST https://smsgrab.com/api/dev/v1/activations/100000123/cancel \
  -H "Authorization: Bearer $SMSGRAB_KEY"

• finish بعد استخدام الرمز. لا يُقبل إلا بعد وصول رمز.
• cancel ما دمت تنتظر الرمز الأول. يُسترد السعر كاملًا.
• إذا لم تفعل شيئًا، ينتهي الرقم الذي لم يصله رمز بعد 20 دقيقة ويُسترد تلقائيًا.

قيم الحالة

الأخطاء

لكل الأخطاء الشكل نفسه. تصرّف بناءً على code وreason، وتجاهل الأسباب التي لا تعرفها بعد:

{ "code": "NO_NUMBERS_AVAILABLE", "message": "No numbers available for this service and country", "reason": "OUT_OF_STOCK" }

الحالات الشائعة هي 402 INSUFFICIENT_BALANCE و409 NO_NUMBERS_AVAILABLE و409 PRICE_CHANGED و422 مع ACTIVATION_LIMIT_REACHED (يمكن أن ينتظر 100 رقم كحد أقصى في وقت واحد لكل حساب) و429 RATE_LIMITED مع الترويسة Retry-After.

المرجع الكامل موجود في وثائق المطورين.