قائمة مراجعة eSIM API (2026): 12 ميزة يجب أن تتوفر في eSIM API الخاص بالسفر — وكيفية اختبار كل منها

إجابة سريعة

يجب أن توفر واجهة برمجة تطبيقات (API) لـ eSIM السفر الجاهزة للإنتاج مصادقة آمنة باستخدام الرموز (tokens)، ومفاتيح تكرار العمليات (idempotency keys) لضمان عدم تكرار الخصم عند إعادة المحاولة، وعروض أسعار تثبت السعر، وwebhooks موقعة لكل حدث من أحداث eSIM، وبيئة تجريبية (sandbox) يمكنها محاكاة دورة حياة eSIM كاملة والأخطاء، وعمليات الشحن (top-ups)، وبيانات الاستخدام، والتعليق/الاستئناف، وتغذية كتالوج تتضمن تفاصيل التغطية والاستخدام العادل. اختبر كل واحدة من هذه الميزات في البيئة التجريبية قبل الإطلاق الفعلي.

إن ربط API لـ eSIM بتطبيقك أو منصة السفر أو محرك الحجز ليس أمراً صعباً. الصعب هو أن تكتشف بعد الإطلاق أن الـ API يقوم بخصم المبلغ مرتين عند حدوث مهلة زمنية (timeout)، أو أنه لا يستطيع إخبارك متى تنفد بيانات العميل، أو أنه لا يوفر لك وسيلة لاختبار حالات الفشل.

تغطي هذه القائمة 12 ميزة تهمك في مرحلة الإنتاج، ولكل ميزة، سنوضح كيفية اختبارها قبل الاشتراك. نحن نستخدم TripoSIM Partner API كمثال عملي، ولكن يمكنك استخدام نفس القائمة لمقارنة أي مزود آخر.

1. مصادقة الرموز الآمنة (Secure token authentication)

ما الذي يجب البحث عنه: اعتماد OAuth 2.0 client credentials: حيث تقوم باستبدال معرف العميل (client ID) والسر (secret) برمز وصول (access token) قصير المدى. لا يتم إرسال الأسرار مع كل طلب.

كيفية الاختبار: اطلب رمزاً، ثم تحقق من انتهاء صلاحيته. في TripoSIM API، تعيد عملية POST /auth/token رمز وصول صالح لمدة 15 minutes. تأكد من أن الكود الخاص بك يقوم بتحديثه تلقائياً قبل انتهاء صلاحيته.

2. مفاتيح تكرار العمليات (Idempotency keys) (لا لخصم المبلغ مرتين)

ما الذي يجب البحث عنه: وجود رأس Idempotency-Key في كل طلب شراء أو عملية شحن. إذا انتهت مهلة طلبك وأعدت المحاولة باستخدام نفس المفتاح، يجب أن يعيد الـ API النتيجة الأصلية بدلاً من إنشاء eSIM ثانية مدفوعة.

كيفية الاختبار: أرسل نفس الطلب مرتين بنفس المفتاح وتأكد من حصولك على طلب واحد فقط. ثم أرسل نفس المفتاح مع محتوى (body) مختلف — الـ API الجيد سيرفض ذلك. يتطلب TripoSIM المفتاح في طلبات الإنتاج وعمليات الشحن ويعيد 409 IDEMPOTENCY_KEY_REUSED إذا تم استخدام مفتاح مع طلب مختلف.

3. عروض أسعار تثبت السعر (Price quotes that lock the price)

ما الذي يجب البحث عنه: طريقة لجلب السعر والاحتفاظ به لفترة قصيرة، بحيث يدفع عميلك بالضبط ما عرضته عليه.

كيفية الاختبار: أنشئ عرض سعر، انتظر، ثم اطلب باستخدام هذا العرض. عروض TripoSIM صالحة لمدة 10 minutes؛ العرض المنتهي الصلاحية يعيد 409 QUOTE_EXPIRED حتى تتمكن من تقديم عرض سعر جديد بدلاً من فرض سعر مفاجئ.

4. تغذية كتالوج نظيفة (A clean catalog feed)

ما الذي يجب البحث عنه: نقطة نهاية (endpoint) واحدة تسرد كل خطة مع السعر، والبيانات، والصلاحية، ودول التغطية، و5G، ودعم الشحن — وبالنسبة للخطط غير المحدودة، حد السرعة اليومي الكامل.

كيفية الاختبار: اسحب الكتالوج لدولة واحدة وقارنه بالموقع الإلكتروني الخاص بالمزود. تعيد نقطة النهاية TripoSIM /catalog بيانات بتنسيق JSON أو CSV، وتتضمن الخطط الإقليمية التي تغطي الدولة، وتضيف حقول الاستخدام العادل (fup_daily_mb, fup_throttle_kbps) للخطط غير المحدودة. اطلع على [كيف تعمل الحدود اليومية غير المحدودة](/blog/unlimited-esim-daily-limit-by-country-2026).

5. تسليم فوري للطلب ورمز QR

ما الذي يجب البحث عنه: يجب أن تتضمن استجابة الطلب (أو webhook بعد ثوانٍ) رمز التنشيط بتنسيق LPA القياسي، على سبيل المثال LPA:1$smdp.example.com$ACTIVATION_CODE، حتى تتمكن من عرض رمز QR أو رابط تثبيت بنقرة واحدة.

كيفية الاختبار: قم بإجراء طلب في البيئة التجريبية (sandbox)، وقم بتوليد الـ QR من سلسلة LPA، وامسحه بكاميرا الهاتف للتحقق من صحة التنسيق.

6. webhooks موقعة لكل حدث (Signed webhooks for every event)

ما الذي يجب البحث عنه: إشعارات دفع (push notifications) لدورة حياة eSIM كاملة، وتكون موقعة بحيث لا يمكن للمهاجمين تزييفها.

يرسل TripoSIM ثمانية أنواع من الأحداث: order.completed, order.failed, esim.activated, esim.usage_80, esim.suspended, esim.resumed, esim.depleted و esim.expired. يحمل كل طلب رأس X-TripoSIM-Signature — وهو عبارة عن HMAC-SHA256 للطابع الزمني والمحتوى الخام باستخدام سر التوقيع الخاص بك:

<pre><code>// reject requests older than 5 minutes (replay protection) if (Math.floor(Date.now() / 1000) - parseInt(timestamp) > 300) throw new Error('Webhook too old'); const expected = crypto .createHmac('sha256', signingSecret) .update(timestamp + '.' + rawBody) .digest('hex'); if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) { throw new Error('Invalid webhook signature'); }</code></pre>

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

7. بيئة تجريبية تحاكي دورة حياة eSIM كاملة

ما الذي يجب البحث عنه: تستغرق شرائح eSIM الحقيقية أياماً لتنشيطها واستخدام البيانات. البيئة التجريبية الجيدة تسمح لك بتسريع الوقت.

Ready to get connected?

Get a travel eSIM for 200+ destinations — instant QR by email, no roaming charges, with a discount applied automatically at checkout.

Browse eSIM plans

كيفية الاختبار: في بيئة TripoSIM sandbox، استخدم POST /sandbox/esims/{iccid}/simulate مع إجراء (action) مثل activate, usage, deplete, expire أو reset. كل خطوة تطلق الـ webhook المطابق، بحيث يمكنك اختبار رسالة البريد الإلكتروني "بياناتك أوشكت على النفاد" في دقائق بدلاً من أيام.

8. محاكاة الفشل (Failure simulation)

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

كيفية الاختبار: أرسل رأس X-Sandbox-Simulate مع أنماط مثل insufficient_balance, price_changed, rate_limit, provider_unavailable أو timeout، وتحقق من أن تطبيقك يظهر رسالة واضحة ولا يعيد المحاولة إلا عندما ينبغي له ذلك.

9. عمليات الشحن على نفس الـ eSIM

ما الذي يجب البحث عنه: يجب أن يتمكن العملاء الذين تنفد بياناتهم من إضافة المزيد دون تثبيت eSIM جديدة.

كيفية الاختبار: استدعِ POST /esims/{iccid}/topup في البيئة التجريبية (مع مفتاح idempotency)، ثم تحقق من رصيد البيانات الجديد. تحقق أيضاً من الخطط التي تدعم الشحن — يجب أن يخبرك الكتالوج بذلك.

10. بيانات الاستخدام والحالة

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

كيفية الاختبار: استدعِ GET /esims/{iccid}/usage بعد حدث استخدام محاكى. يقوم TripoSIM بتخزين الاستخدام مؤقتاً لمدة 5 minutes، لذا استخدم webhooks (esim.usage_80, esim.depleted) للتنبيهات في الوقت الفعلي.

11. التعليق والاستئناف (Suspend and resume)

ما الذي يجب البحث عنه: طريقة لإيقاف eSIM مؤقتاً — على سبيل المثال عند النزاع على عملية دفع أو عندما يبلغ العميل عن فقدان هاتفه — واستئنافها لاحقاً.

كيفية الاختبار: قم بتعليق eSIM في البيئة التجريبية، وتأكد من وصول webhook esim.suspended، ثم قم باستئنافها وتأكد من وصول esim.resumed.

12. حدود معدل طلبات واضحة، وأكواد خطأ وسجل تغييرات

ما الذي يجب البحث عنه: حدود موثقة، وأكواد خطأ تخبرك ما إذا كان يجب عليك إعادة المحاولة، وسجل تغييرات (changelog) عام حتى لا تفاجئك التحديثات أبداً.

كيفية الاختبار: اقرأ قائمة الأخطاء واربط كل كود بـ "إعادة المحاولة" أو "عدم إعادة المحاولة" في الكود الخاص بك. يسمح TripoSIM بـ 120 طلباً في الدقيقة لكل حساب شريك (يمكنك وضع حدود أقل لمفاتيح API الفردية)، ويعيد رأس Retry-After في استجابات 429، ويميز كل كود خطأ كقابل للإعادة أو غير قابل، وينشر نقطة نهاية لسجل التغييرات.

خطة إطلاق بسيطة

اليوم 1: احصل على مفاتيح البيئة التجريبية، قم بالمصادقة، واسحب الكتالوج.
اليوم 2: قم بإجراء طلبات في البيئة التجريبية باستخدام مفاتيح idempotency واعرض رموز QR.
اليوم 3: أضف webhooks، وقم بتشغيل محاكيات دورة الحياة والفشل.
اليوم 4: أضف عمليات الشحن والاستخدام، ثم اختبر على هاتف حقيقي باستخدام eSIM واحدة حقيقية.
اليوم 5: انطلق فعلياً.

معظم الفرق تكتمل عملية الربط لديها في أقل من أسبوع. اقرأ [وثائق API الكاملة](https://docs.triposim.com) أو اطلع على [دليل دمج API لـ eSIM خطوة بخطوة](/blog/esim-reseller-api-how-to-integrate-travel-esim-sales-into-your-platform).

الأسئلة الشائعة

ماذا يجب أن يتضمن API لـ eSIM السفر؟

بحد أدنى: مصادقة الرموز، مفاتيح idempotency، عروض الأسعار، تغذية الكتالوج، رموز QR/التنشيط الفورية، webhooks موقعة، بيئة تجريبية مع محاكيات دورة الحياة والفشل، عمليات الشحن، بيانات الاستخدام، التعليق/الاستئناف، وحدود معدل الطلبات وأكواد الخطأ الموثقة.

لماذا تعتبر مفاتيح idempotency مهمة لـ API الخاص بـ eSIM؟

كل طلب eSIM يكلف مالاً حقيقياً. إذا انتهت مهلة الطلب وقام نظامك بإعادة المحاولة، فإن مفتاح idempotency يضمن أن تعيد المحاولة النتيجة الأولى بدلاً من شراء eSIM ثانية.

كيف أختبر API لـ eSIM دون شراء شرائح eSIM؟

استخدم البيئة التجريبية (sandbox). البيئة التجريبية الجيدة تحاكي الطلبات، والتنشيط، واستخدام البيانات، والنفاذ، والانتهاء — وتسمح لك بإجبار الأخطاء — دون خصم أي مبالغ من محفظتك.

كم يستغرق دمج API لـ eSIM؟

مع وجود API موثق جيداً وبيئة تجريبية كاملة، تطلق معظم الفرق خدماتها في غضون 3–5 أيام عمل.

هل يدعم TripoSIM API خدمة العلامة البيضاء (white-label delivery)؟

نعم. ستتلقى رمز التنشيط وبيانات QR، بحيث يمكنك تقديم الـ eSIM داخل تطبيقك الخاص أو عبر رسائل البريد الإلكتروني تحت علامتك التجارية. اطلع على [برنامج API](/api-program).

الخلاصة

السعر مهم، ولكن بالنسبة لـ API الخاص بـ eSIM، يظهر الفرق الحقيقي بعد الإطلاق: عمليات إعادة محاولة لا تكرر الخصم أبداً، وwebhooks يمكنك الوثوق بها، وبيئة تجريبية تسمح لك باختبار كل شيء أولاً. قم بتطبيق هذه القائمة على أي مزود قبل الالتزام — و[ابدأ مع بيئتنا التجريبية](/api-program) لترى كيف يحصل TripoSIM Partner API في التقييم.