التكامل عبر API
متاحالتكامل عبر API
هل لديك خطة لبيع شرائح eSIM داخل تطبيقك أو ضمن مسار الحجز لديك؟ يمكنك إخبارنا بما يلزمك.
تتوفر API للشركاء المعتمدين بعد تفعيل الوصول من فريق المبيعات. أنشئ مفتاحًا للقراءة فقط أو لتقديم الطلبات في لوحة الشريك. تستخدم جميع المشتريات محفظتك مسبقة الدفع بالدولار الأمريكي.
البدء السريع مع API
بعد اعتماد حسابك، يحدد فريق المبيعات الأسعار ويفعّل الوصول إلى API. أنشئ مفتاحًا في لوحة الشريك. لا تستطيع مفاتيح القراءة فقط تقديم الطلبات. يجب أيضًا تفعيل الشراء على حسابك.
https://simvoro.com/api/partner/v1استخدم مفتاح bearer من جهة الخادم في كل طلب. لا تضع المفتاح في شيفرة المتصفح أو عناوين URL. يمكنك إلغاؤه من لوحة الشريك.
Authorization: Bearer YOUR_API_KEY| الطريقة | نقطة النهاية | النتيجة |
|---|---|---|
| GET | /products?destination=japan | أسعارك المحددة بالدولار الأمريكي ومعرّفات المنتجات. صفِّ حسب slug الوجهة واستخدم cursor للتنقل بين الصفحات. |
| GET | /balance | رصيد المحفظة والمبالغ المحجوزة والدولارات المتاحة. |
| GET | /transactions | معاملات المحفظة وnextCursor. |
| GET | /orders | ملخصات طلبات الشريك وnextCursor، بحد 50 طلبًا لكل صفحة. |
| POST | /orders | حجز المبلغ وطلب شريحة eSIM واحدة. يلزم مفتاح يسمح بتقديم الطلبات. |
| GET | /orders/{orderId} | حالة الطلب وآخر استهلاك بيانات تمت مزامنته ومعلومات التثبيت بعد التسليم. |
إنشاء طلب
أرسل UUID في Idempotency-Key. أعد استخدام UUID نفسه بعد انتهاء المهلة أو فشل الاتصال. أرسل السعر الذي أكده العميل وأكد أن الجهاز المستلم يدعم eSIM وغير مقفل على مشغّل. تعيد تغيّرات السعر المباشر الرمز 409 PRICE_CHANGED. هذه API فعلية؛ تستخدم المشتريات المقبولة أموالًا حقيقية من المحفظة.
POST /api/partner/v1/orders
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Idempotency-Key: 83c77d9f-395f-4ff0-8ed6-c461bda46559
{"productId":"PRODUCT_ID_FROM_CATALOG","expectedPrice":"2.25","deviceConfirmed":true}تتضمن استجابة 201 الحقلين orderId وesim؛ تحقق من esim.status وesim.failure. استعلم عن الطلب كل 10 ثوانٍ. يُحجز المبلغ أولًا ويُخصم بعد التحقق من التسليم. قد تعيد إعادة الطلب نتيجة طلب فاشل أيضًا. إذا كانت نتيجة المورّد غير مؤكدة، يبقى المبلغ محجوزًا أثناء مطابقة الطلب الأصلي. معلومات التثبيت خاصة ولا تظهر إلا بعد التحقق من التسليم.
المبالغ نصوص عشرية بالدولار الأمريكي. تعيد القوائم items وnextCursor؛ تابع حتى تصبح nextCursor مساوية لـnull. الحدود: 120 طلبًا لكل مفتاح في الدقيقة و10 محاولات شراء لكل مستخدم في الدقيقة. التزم بـRetry-After عند ظهور 429. الأخطاء الشائعة: 401 مفتاح غير صالح، 403 عدم وجود صلاحية، 402 رصيد غير كافٍ، 404 طلب غير متاح، 409 تعارض سعر أو تكرار، 503 الخدمة غير متاحة. استرجع الطلب الأصلي قبل محاولة شراء آخر.
ما ينبغي تضمينه في طلبك
- منصتك ومن هم عملاؤك
- حجم مشترياتك الشهري المتوقع
- الوجهات المراد تقديمها
- ما يحتاج نظامك إلى تنفيذه، على سبيل المثال طلب شريحة eSIM وعرض رمز QR الخاص بها لعميلك
الانضمام كشريك
يمكنك إرسال طلب، وسيتواصل معك فريقنا بشأنه.