بداية سريعة مع API لاستقبال رموز SMS

الأولى بروتوكول handler_api. هو صيغة الطلبات التي تستخدمها الأدوات المكتوبة لـ SMS-Activate. إذا كانت أداتك تتكلمه، تغيّر عنوان API والمفتاح، وتحتفظ بكودك.

الثانية واجهة JSON API v2. فيها طلبات وإجابات JSON بسيطة، و webhooks، وحالات واضحة. استخدمها لكل ما تكتبه من الصفر.

كل طلب يذهب إلى عنوان واحد، مع مفتاحك واسم إجراء. العنوان موجود في الوثائق. الإجراءات الرئيسية هي التي ترسلها أداتك من قبل.

• getNumber: شراء رقم لخدمة ودولة.
• getStatus: السؤال هل وصل الرمز.
• setStatus: تغيير حالة تفعيل، مثلًا لإلغائه.
• getBalance: قراءة رصيد محفظتك.

مفتاحك موجود في صفحة المطورين في حسابك. أرسله كرمز Bearer في ترويسة Authorization مع كل طلب.

ابدأ بـ GET /catalog. يُرجع العروض التي تستطيع شراءها الآن، مع سعرك، وتستطيع تصفيته بحسب الدولة والخدمة. GET /balance يُرجع رصيد المحفظة بالدولار الأمريكي. تُشحن المحفظة ابتداءً من 3 $.

المسار كله بضعة استدعاءات.

للتفعيل حالة من أربع: waiting أو completed أو expired أو cancelled. الإلغاء ممكن فقط ما دام في حالة waiting.

افتراضيًا ينتظر التفعيل الرمز عشر دقائق، ثم تنتهي مدته. تستطيع تحديد انتظار أقصر أو أطول في استدعاء الشراء، من دقيقتين إلى عشرين دقيقة. GET /activations يعرض تفعيلاتك، الأحدث أولًا.

• POST /activations مع خدمة ودولة يشتري رقمًا.
• GET /activations/:id يُرجع التفعيل. كرّر الاستعلام حتى يظهر الرمز.
• أو مرّر عنوان webhook في استدعاء الشراء، فنستدعي خادمك عند وصول الرمز.
• POST /activations/:id/cancel يلغي تفعيلًا في حالة waiting مع استرداد المبلغ كاملًا.

الشبكات تفشل، واستدعاء الشراء الذي انتهت مهلته قد يكون نُفّذ. أرسل ترويسة Idempotency-Key مع POST /activations. إذا أعدت المحاولة بالمفتاح نفسه، يعود إليك التفعيل الأول، لا عملية شراء ثانية.

لكل نقطة نهاية حد معدل خاص بها، من 30 إلى 120 طلبًا في الدقيقة، والوثائق تذكر كل واحد منها. إذا استخدمت webhook، فلا تكاد تحتاج إلى الاستعلام المتكرر. رسائل webhook موقّعة، فتحقق من التوقيع قبل أن تثق بأي منها.

كل رقم شريحة SIM حقيقية على شبكة جوال، يُباع لتفعيل واحد لخدمة واحدة. يستقبل رسائل SMS فقط، لا المكالمات. لا نعدك بأن التطبيق سيقبل الرقم أو سيرسل رمزًا، فيجب أن يتوقع كودك تفعيلات تنتهي دون رمز.

لا تدفع إلا مقابل رمز يصل. إذا لم يأتِ أي رمز، ألغِ التفعيل أو اتركه حتى تنتهي مدته، وسيعود المبلغ كاملًا إلى محفظتك تلقائيًا. تعامل مع ذلك كفرع عادي، لا كخطأ.

أغلب المشكلات الأولى تأتي من تخطّي هذه الخطوات.

• شغّل تفعيلًا واحدًا يدويًا أولًا، واقرأ كل حقل في الإجابة.
• اترك تفعيلًا واحدًا تنتهي مدته عمدًا، وراقب الرصيد وهو يعود.
• قارن رموز الدول والخدمات لديك بالوثائق. الرمز الخاطئ قد يُرجع رقمًا لم تكن تريده.
• أبقِ المفتاح على خادمك، ولا تضعه أبدًا في تطبيق أو صفحة ويب.