المطورون

أربع نقاط نهاية، و2 webhook، وبلا مفاجآت.

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

REST فوق HTTPS على api.orbislo.com، ومصادقة bearer، وJSON داخلا وخارجا. تقرأ الكتالوج، وتنشئ طلبا، وتتابع مهمة التزويد، وتقرأ الاستهلاك. اثنان من webhook يخبرانك متى تفعلت eSIM ومتى قارب رصيدها على النفاد. بيانات بيئة الاختبار تصلك في يوم العمل نفسه. الوصول إلى بيئة الإنتاج اليوم بالتقديم، ونشرح السبب أدناه بدل أن ندعي أن الاستمارة حد استخدام.

لماذا توجد هذه الواجهة

ينبغي أن يجهز الاتصال في اللحظة التي يحجز فيها المسافر، وداخل منتجك أنت. لا ينبغي أن يكتشفه في المطار.

منصة حجز تستطيع أن تلحق باقة بيانات ببرنامج الرحلة. صانع أجهزة يستطيع تفعيل باقة أثناء الإعداد الأول. أداة فريق تستطيع تسليم الموظف الجديد باقته مع حاسوبه المحمول.

الحالات الثلاث كلها أربعة نداءات وwebhook واحد. لا بوابة شركاء تسجل الدخول إليها، ولا ملف CSV ترفعه.

ما الذي يحدث بين طلب POST عندك ومسافر لديه إشارة.

المصادقة

أرسل مفتاحك كرمز bearer مع كل طلب. المفاتيح تبدأ بـ sk_test في بيئة الاختبار وبـ sk_live في الإنتاج.

المفتاح الذي يلصق في البيئة الخطأ يفشل برمز 401 بدل أن ينفق مالا في صمت. للمفاتيح نطاق، فمفتاح القراءة فقط لا ينشئ طلبا، ومفتاح صادر لحساب فريق لا يرى حسابا آخر.

بدل مفتاحك من لوحة التحكم متى شئت. القديم يظل يعمل 24 ساعة، فلن تجبر أبدا على تحويل كل شيء في يوم واحد.

curl https://api.orbislo.com/v1/catalog?country=jp \
  -H "Authorization: Bearer sk_live_9f2c..." \
  -H "Orbislo-Version: 2026-08-01"

عن ترويسة الإصدار

ترويسة الإصدار اختيارية، وتثبت شكل الاستجابة على إصدار مؤرخ. من دونها تحصل على الإصدار الذي أنشئ مفتاحك عليه، وهو لا يتغير من تحتك أبدا.

نضيف الحقول من دون إنذار. لا نحذف حقلا ولا نغير نوعه داخل الإصدار الواحد أبدا.

نقاط نهاية في الواجهة كلها، ومعها حدثا webhook

90 ثانية

الوسيط الزمني من طلب ناجح إلى ملف تعريف مفعل

24 ساعة

المدة التي يرجع فيها المفتاح المكرر الاستجابة الأصلية

نقاط النهاية

الطريقة	المسار	ماذا تفعل	حد الاستخدام
GET	/v1/catalog	كل باقة نبيعها، مع السعر وحجم البيانات والصلاحية والدول المشمولة.	600 في الدقيقة
POST	/v1/orders	تشتري باقة وترجع طلبا مرفقا بمهمة تزويد.	60 في الدقيقة
GET	/v1/provisioning/:id	حالة مهمة تزويد واحدة، من queued حتى activated أو failed.	600 في الدقيقة
GET	/v1/usage/:esim_id	البايتات المستهلكة والمتبقية، والمشغل الذي ترتبط به eSIM واحدة.	300 في الدقيقة

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

الكتالوج

الكتالوج هو المرجع لما هو متاح ولسعره. يغطي 145 وجهة تعمل اليوم.

رشح حسب الدولة أو المنطقة أو عائلة الباقات. الأسعار ترجع بالوحدة النقدية الصغرى، فلا تصل الأعداد العشرية العائمة إلى شيفرة الفوترة عندك.

GET /v1/catalog?country=jp

{
  "object": "list",
  "data": [
    {
      "id": "plan_jp_5gb",
      "name": "Japan 5 GB",
      "countries": ["jp"],
      "data_mb": 5120,
      "price": { "amount": 1150, "currency": "usd" },
      "expires": false,
      "throttle_mbps": null,
      "tethering": true,
      "carriers": ["NTT Docomo", "KDDI", "SoftBank"]
    }
  ],
  "has_more": false
}

حقلان يستحقان قراءة ثانية

الحقل expires قيمته false في كل باقة محسوبة بالحجم نبيعها، لأن بياناتنا لا تنتهي صلاحيتها. إن كنت تبني مقارنة أسعار، فهذا الحقل يغير الحساب أكثر مما يغيره السعر.

الحقل throttle_mbps قيمته null في الباقات المحسوبة بالحجم و1 في تذاكر اليوم غير المحدودة، حيث تستمر السرعة الكاملة حتى 2 GB في اليوم ثم تنزل إلى 1 Mbps.

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

الطلبات

طلب POST واحد يشتري الباقة ويبدأ التزويد. ترويسة Idempotency-Key إلزامية وليست نصيحة.

أسوأ نتيجة في هذه الواجهة هي مهلة تنتهي فتتركك لا تعرف هل خصم من المسافر أم لا. المفتاح الإلزامي يلغي هذه الحالة تماما.

POST /v1/orders
Idempotency-Key: 4f1d0f6e-1c3a-4a2b-9d77-1b6a0e7c9f21
Content-Type: application/json

{
  "plan_id": "plan_jp_5gb",
  "traveller_ref": "user_88213",
  "imei": "356938035643809",
  "activate": "on_first_use"
}

201 Created

{
  "id": "ord_7Kd2mQ",
  "status": "provisioning",
  "esim_id": "esim_2xB9Ln",
  "provisioning_id": "prv_5Ttq81",
  "amount": { "amount": 1150, "currency": "usd" },
  "activation": {
    "type": "universal_link",
    "url": "https://orbislo.com/i/2xB9Ln",
    "lpa": "LPA:1$rsp.orbislo.com$K4-9TT-2XB9LN"
  }
}

فحص الجهاز والتفعيل المؤجل

الحقل imei اختياري لكننا ننصح به بشدة. أرسله ونفحص دعم eSIM وقفل المشغل قبل أن نأخذ المال.

الهاتف الذي لا يستطيع حمل ملف تعريف يحصل على 422 مع device_not_eligible، بدل باقة مباعة ومسافر غاضب.

ضبط activate على on_first_use يجعل أي مدة صلاحية تبدأ حين يهبط المسافر، لا حين نادى خادمك خادمنا.

حالة التزويد

التزويد غير متزامن، لأن على الطرف الآخر منصة مشغل. اسأل هذه النقطة، أو خذ الـ webhook واستغن عن السؤال المتكرر.

الوسيط الزمني من queued إلى activated أقل من 90 ثانية. وكل ما بقي في queued بعد 10 دقائق يعد فشلا، ويرد ثمنه تلقائيا.

GET /v1/provisioning/prv_5Ttq81

{
  "id": "prv_5Ttq81",
  "status": "activated",
  "states": [
    { "state": "queued",       "at": "2026-08-24T09:14:02Z" },
    { "state": "provisioning", "at": "2026-08-24T09:14:04Z" },
    { "state": "installed",    "at": "2026-08-24T09:14:41Z" },
    { "state": "activated",    "at": "2026-08-24T09:15:07Z" }
  ],
  "carrier": "KDDI",
  "failure_reason": null
}

Webhook

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

أحداث webhook

الحدث	متى ينطلق	ماذا تفعل به
esim.activated	حين يرتبط ملف التعريف بشبكة لأول مرة.	أخبر المسافر أنه صار متصلا. هذه هي اللحظة التي يصبح فيها الشراء حقيقيا عنده.
esim.depleted	حين يتجاوز الاستهلاك عتبة، عند 80 بالمئة ثم عند 100 بالمئة.	اعرض عليه شحنا قبل أن ينقطع، لا بعده.

POST https://your-app.example/hooks/orbislo
Orbislo-Signature: t=1756032907,v1=6c1b...
Content-Type: application/json

{
  "id": "evt_9pQ4rz",
  "type": "esim.depleted",
  "created": "2026-08-24T11:41:33Z",
  "data": {
    "esim_id": "esim_2xB9Ln",
    "threshold": 80,
    "used_mb": 4096,
    "remaining_mb": 1024,
    "country": "jp"
  }
}

التحقق من التسليم

احسب HMAC SHA-256 على الطابع الزمني ثم نقطة ثم جسم الطلب الخام، مستخدما السر الخاص بنقطتك. وقارن بزمن ثابت.

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

رموز الأخطاء

HTTP	الرمز	ماذا يعني	ماذا تفعل
400	invalid_request	حقل ناقص أو نوعه خطأ. والجسم يسمي الحقل.	أصلح الطلب. إعادة المحاولة لن تفيد.
401	invalid_token	رمز bearer خطأ أو ملغى أو من البيئة الأخرى.	تأكد أنك لا ترسل مفتاح اختبار إلى مضيف الإنتاج.
402	insufficient_balance	رصيد حسابك لا يغطي الطلب.	اشحن ثم أعد المحاولة بالمفتاح نفسه.
404	not_found	لا يوجد عنصر بهذا المعرف في هذه البيئة.	معرفات بيئة الاختبار ومعرفات الإنتاج غير متبادلة.
409	idempotency_conflict	استخدم المفتاح نفسه مرة أخرى مع جسم مختلف.	استخدم مفتاحا جديدا، أو أعد إرسال الجسم الأصلي حرفا بحرف.
422	device_not_eligible	الجهاز لا يدعم eSIM، أو أنه مقفل على مشغل.	شغل فحص الجهاز قبل أن تأخذ المال.
429	rate_limited	تجاوزت سقف تلك النقطة.	تراجع بحسب مهلة إعادة المحاولة في الترويسة. ولا تكرر بلا توقف.
500	internal_error	الخطأ منا. وهو أصلا في نظام التنبيه عندنا.	أعد المحاولة بالمفتاح نفسه بعد ثانيتين.
503	provider_unavailable	منصة مشغل أعلى السلسلة متوقفة.	أعد المحاولة حتى 10 دقائق. ننتقل تلقائيا حيث يوجد مشغل ثان.

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

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

بيئة الاختبار مقابل الإنتاج

المضيف نفسه، والمسارات نفسها، وأشكال الاستجابة نفسها. المفتاح الذي يبدأ بـ sk_test لا يمس المال ولا ينشئ ملف تعريف لدى مشغل.

مهام التزويد تعبر آلة الحالات كاملة في نحو 4 ثوان، فلا تنام اختباراتك 90 ثانية لكل واحدة.

اطلب الباقة plan_test_fail لتحصل على مهمة فاشلة مع سببها. واطلب plan_test_slow لتحصل على مهمة تبقى في provisioning لمدة 11 دقيقة، فتجرب مسار المهلة عندك.

تنطلق رسائل webhook في بيئة الاختبار أيضا، إلى عنوان URL تضبطه لكل بيئة.

إن كنت تفضل ألا تبني شيئا

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

نقطة MCP تفتح مجموعة بيانات التغطية ومؤشر الأسعار لمساعد ذكاء اصطناعي بسطر إعداد واحد ومن دون شيفرة.

الباقات التي ستبيعها، وبيانات السرعة المقاسة خلف الكتالوج، وقائمة الدول كاملة، كلها منشورة علنا على هذا الموقع.

أسئلة يطرحها المطورون

هل أحصل على مفتاح اليوم؟

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

كم تستغرق الموافقة؟

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

ما الفرق بين بيئة الاختبار والإنتاج؟

بيئة الاختبار تستخدم المضيف نفسه بمفتاح يبدأ بـ sk_test. ترجع الكتالوج الحقيقي، وتقبل الطلبات، وتنقل مهمة التزويد عبر queued وprovisioning وactivated على خط زمني مضغوط في نحو 4 ثوان. لا مال يتحرك ولا ملف تعريف ينشأ لدى مشغل. وتستطيع فرض أي حالة فشل بطلب الباقة plan_test_fail. مفاتيح الإنتاج تبدأ بـ sk_live وكل شيء فيها حقيقي.

هل أحتاج مفاتيح التكرار الآمن؟

عند إنشاء الطلب نعم، والنقطة ترفض الطلب من دونها. انتهاء المهلة على طلب هو أغلى غموض في هذه الواجهة، لأن إعادة المحاولة على عمياها تشتري الباقة مرتين. أرسل UUID في ترويسة Idempotency-Key. نحفظ المفتاح إلى جانب الاستجابة 24 ساعة، فتعيد المحاولة داخل هذه المدة فترجع النتيجة الأصلية بدل إنشاء طلب ثان.

ما حدود الاستخدام؟

600 طلب في الدقيقة على نقاط القراءة، و300 في الدقيقة على الاستهلاك، و60 في الدقيقة على إنشاء الطلبات، لكل مفتاح، ضمن نافذة متحركة. كل استجابة تحمل العدد المتبقي ووقت إعادة الضبط. ورمز 429 يحمل مهلة إعادة المحاولة بالثواني. وإن كانت حالتك تحتاج فعلا أكثر، فاطلب، لأن رفع السقف تغيير في الإعدادات وليس مفاوضة.

ما مدى موثوقية webhook؟

نعيد المحاولة على أي استجابة ليست 2xx ثماني مرات على مدى 24 ساعة بتباعد أسي يبدأ من 10 ثوان. كل تسليم موقع بـ HMAC SHA-256 على الجسم الخام بالسر الخاص بنقطتك، ومعه طابع زمني ينبغي أن تفحصه ضمن نافذة 5 دقائق لتوقف إعادة الإرسال. التسليم يقع مرة على الأقل، فاجعل معالجك محصنا ضد التكرار بمعرف الحدث.

هل توجد حزمة تطوير؟

يوجد عميل بلغة TypeScript وعميل بلغة Python، وكلاهما غلاف رفيع فوق نقاط النهاية الأربع نفسها. ولا يخفي أي منهما شيئا. صيغة النقل ثابتة بما يكفي ليكون curl عميل إنتاج معقولا. نفضل توثيق صيغة النقل جيدا على صيانة إحدى عشرة حزمة تطوير بشكل رديء.

ماذا يحدث حين يفشل التزويد؟

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

ابدأ من بيئة الاختبار، أو تخط الشيفرة كليا

بيانات بيئة الاختبار تصلك في يوم العمل نفسه. وإن كنت تفضل ألا تكتب تكاملا، فلا مسار العمولة ولا نقطة MCP يحتاجان بناء أي شيء.

تصفح المتجر اطلع على كل الأسعار اطلع على السرعات المقاسة تصفح الوجهات