Overview
API العامة (/v1)
Shared rules of the /v1 API: base URL, response envelope, pagination and response language.
On this page
عنوان URL الأساسي#
أرسل كل الطلبات عبر HTTPS إلى العنوان أدناه. يلزم مفتاح API العامة (المصادقة)، وجميع الاستجابات بتنسيق JSON.
https://api.esimoa.com/v1نقاط النهاية#
| نقطة النهاية | الوصف |
|---|---|
| GET /v1/esims | ابحث عن شرائح eSIM |
| GET /v1/esims/:id | احصل على eSIM |
| GET /v1/countries | عرض قائمة البلدان |
| GET /v1/openapi.json | مواصفات OpenAPI 3.1 (لا تتطلب مفتاحًا) |
Response envelope#
تتضمن الاستجابات الناجحة دائمًا "success": true. تأتي القوائم في items والنتيجة الفردية في item.
// List endpoints
{ "success": true, "items": [ ... ], "total": 42, "limit": 10, "offset": 0, "sort": "price" }
// Detail endpoint
{ "success": true, "item": { ... } }للاطلاع على استجابات الأخطاء ورموز الحالة، راجع حدود المعدل والأخطاء.
ترقيم الصفحات#
تُقسَّم القوائم إلى صفحات باستخدام limit (1–50، الافتراضي 10) وoffset. يُقرَّب offset دائمًا للأسفل إلى مضاعف limit — على سبيل المثال، يُعامَل limit=10 وoffset=15 كـ offset=10. قيمة offset في الاستجابة هي القيمة المستخدمة فعليًا، وtotal هو العدد الكامل.
البقشيش
Response language#
المعامل lang (ko | en | ja | zh-CN | zh-TW، والافتراضي en) يحدد لغة أسماء البلدان وعناوين العناصر وصفحة الشراء التي يشير إليها url. اجعلها مطابقة للغة المستخدم.
Prices & caching#
الأسعار (priceKrw) هي سعر البيع لدى esimoa كعدد صحيح بـ KRW. تتغير الأسعار كثيرًا — خزّن نتائج البحث مؤقتًا لبضع دقائق كحد أقصى؛ وتبقى صفحة الدفع في esimoa المرجع الوحيد للمبلغ المحصّل.