أتمتة التحقق برمز SMS: دليل API الكامل

الموقع يكفي للتسجيل العرضي: تضغط بضع نقرات وتنتظر رسالة واحدة. لكنه يتوقف عن الكفاية عندما تكتب اختبارات آلية، أو سكريبت تسجيل جماعي، أو CI pipeline، أو بوتاً يحتاج لالتقاط رمز التحقق دون أي تدخّل بشري. الموقع لا يستطيع فعل ذلك. الـ API يستطيع. هذا المقال يضمّ كل ما تحتاجه للانتقال من الصفر إلى تدفق عمل فعلي.

الخطوة 1: احصل على مفتاح API

سجّل الدخول وانتقل إلى /account/api-keys لإنشاء واحد. تبدو المفاتيح على هيئة jm_ متبوعة بسلسلة عشوائية. يُعرض النص الصريح مرة واحدة فقط — نحن نخزّن تجزئة (hash) لا المفتاح نفسه، فلا يوجد خيار «استرجاع مفتاحي» إذا ضاع منك. احذفه وأنشئ واحداً جديداً.

كل طلب يستخدم مصادقة Bearer القياسية:

Authorization: Bearer jm_your_key

عامل المفتاح معاملة كلمة السر — لا ترفعه إلى مستودع عام، ولا تلصقه في محادثة ليطّلع عليه شخص آخر يساعدك في تصحيح الأخطاء. إذا اشتبهت في تسرّبه، عد إلى /account/api-keys، احذفه، وأصدر واحداً جديداً؛ القديم يتوقف عن العمل فوراً.

الخطوة 2: اختر خدمة ودولة

تقديم الطلب يحتاج إلى شيئين: service (رمز الخدمة) وcountry (رقم تعريف الدولة). ابدأ بعرض القائمة الكاملة:

curl https://jiema.my/api/v1/services \
  -H "Authorization: Bearer jm_your_key"

كل عنصر يحمل حقل code (بالنسبة لتيليجرام هو tg) — مرّر هذا الحقل مباشرة إلى نقطة نهاية الطلب، فهو أكثر ثباتاً من إعادة بناء slug بنفسك. لمعرفة السعر والمخزون اللحظيين لخدمة معيّنة عبر كل الدول، أضف معامل service:

curl "https://jiema.my/api/v1/prices?service=tg" \
  -H "Authorization: Bearer jm_your_key"

كل عنصر داخل items يحمل countryId / priceCents / count (عدد الأرقام المتاحة حالياً). تحقّق من count قبل تقديم الطلب — الصفر يعني أن الطلب سيفشل، فلا داعي لإهدار طلب لمعرفة ذلك بالطريقة الصعبة.

الخطوة 3: قدّم الطلب

curl -X POST https://jiema.my/api/v1/orders \
  -H "Authorization: Bearer jm_your_key" \
  -H "Content-Type: application/json" \
  -d '{"service":"tg","country":"6"}'

الطلب الناجح يُرجع رقم هاتف وموعد انتهاء الصلاحية:

{
  "ok": true,
  "data": {
    "id": "cm...",
    "status": "WAITING",
    "phone": "62812xxxxxxx",
    "expiresAt": "2026-08-01T12:15:00.000Z",
    "chargedCents": "40"
  }
}

الخصم يحدث في هذه الخطوة — chargedCents هو المبلغ المخصوم فعلياً (بالسنت). سلّم هذا الرقم للتطبيق المستهدف لاستقبال رمز التحقق، ثم انتقل إلى الخطوة التالية.

الخطوة 4: استعلم للحصول على الرمز

لا يوجد WebSocket أو webhook push — تحصل على محتوى الرسالة بالاستعلام المتكرر عن GET /api/v1/orders/:id حتى يتوقف smsBody عن كونه null:

while true; do
  RESP=$(curl -s https://jiema.my/api/v1/orders/$ORDER_ID \
    -H "Authorization: Bearer jm_your_key")
  BODY=$(echo "$RESP" | jq -r '.data.smsBody')
  if [ "$BODY" != "null" ]; then
    echo "Code received: $BODY"
    break
  fi
  sleep 5
done

خمس ثوانٍ نقطة بداية معقولة — الرقم صالح لمدة 15 دقيقة، وحدّ الاستعلامات البالغ 60 طلباً في الدقيقة يترك مساحة كافية. ثلاث ثوانٍ تفي بالغرض أيضاً إن كنت نافد الصبر؛ الاستعلام كل ثانية لا يجلب الرمز أسرع، بل يستهلك حصتك من حدود المعدل فقط.

المزالق

• حدود المعدل تُحسب لكل مستخدم، لا لكل مفتاح. نقاط النهاية الكاتبة (order / cancel / next-sms) محدودة بـ 10 طلبات في الدقيقة لكل مستخدم؛ والاستعلامات بـ 60 في الدقيقة. إنشاء مفاتيح إضافية لا يرفع لك السقف — كلها تتشارك الحد نفسه.
• الأرقام تنتهي صلاحيتها بعد 15 دقيقة. الرقم غير المستخدم الذي تنتهي صلاحيته دون استقبال رمز يُرد ثمنه تلقائياً — لا حاجة لطلب ذلك. لكن إذا أبقى خط أنابيبك الرقم مُعلّقاً طويلاً قبل استخدامه فعلياً (عالقاً في قائمة انتظار، مثلاً)، سيكون قد مات بحلول الوقت الذي تصل إليه.
• الرقم الواحد يمكنه استقبال أكثر من رمز. إذا كان التطبيق المستهدف يرسل الرسائل على خطوتين (تأكيد تسجيل، ثم رمز دخول منفصل)، استدعِ POST /api/v1/orders/:id/next-sms بعد وصول الأولى لتخبرنا «انتهيت من هذه، استمر بالاستماع» — لا حاجة لتقديم طلب جديد للحصول على رقم جديد.
• بعد وصول الرمز، يتوقف الإلغاء عن العمل. POST /api/v1/orders/:id/cancel يرد المبلغ فوراً ما دام الرقم لا يزال في انتظار رمز. بعد أن يصبح smsBody غير فارغ لمرة واحدة، نفس الاستدعاء يُرجع خطأ CODE_RECEIVED بدلاً من ذلك — أنت حصلت على ما دفعت ثمنه، فلا سبيل للتراجع.
• لا تتحقق من الحالة مرة واحدة فقط وتستسلم. status ينتقل من WAITING إلى RECEIVED. إذا بقي على WAITING حتى انتهاء الصلاحية، فهذا عادةً مشكلة في معدّل التسليم لتلك التركيبة المحدّدة من الدولة/الخدمة — تقديم طلب جديد في دولة أخرى غالباً يحلّ المشكلة أسرع من الانتظار.

الخطوات التالية

هذا يغطّي المسار الأساسي من الطلب إلى الرمز. القائمة الكاملة للحقول، وأكواد الأخطاء، والحالات الحدّية لكل نقطة نهاية موجودة في /api-docs. إذا كنت تشغّل هذا على نطاق واسع — مثلاً، تحافظ على تدفقات تحقق نشطة لعشرات الحسابات في الوقت نفسه — وقّت حلقة الاستعلام لكل طلب بشكل مستقل. لا تضعها في طابور عبر حلقة تسلسلية واحدة، وإلا ستنتهي صلاحية الأرقام الأولى بينما لا تزال تنتظر الأولى.