واجهة API للشركاء (B2B)
المنتجات
GET /b2b/v1/products — search esimoa products by country, keyword, duration, data and more.
Request#
GET
/b2b/v1/productscurl "https://api.esimoa.com/b2b/v1/products?country=JP&isUnlimited=true&minDays=5&sortBy=price&limit=20" \
-H "X-API-Key: $ESIMOA_PARTNER_KEY"const params = new URLSearchParams({
country: 'JP',
isUnlimited: 'true',
minDays: '5',
sortBy: 'price',
limit: '20',
page: '1',
});
const res = await fetch(`https://api.esimoa.com/b2b/v1/products?${params}`, {
headers: { 'X-API-Key': process.env.ESIMOA_PARTNER_KEY },
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.code}: ${body.message}`);
const { data: products, total, page, limit } = body;import os
import requests
res = requests.get(
"https://api.esimoa.com/b2b/v1/products",
params={"country": "JP", "isUnlimited": "true", "minDays": 5, "sortBy": "price", "limit": 20, "page": 1},
headers={"X-API-Key": os.environ["ESIMOA_PARTNER_KEY"]},
timeout=10,
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['code']}: {body['message']}")
products = body["data"]Query parameters#
جميع المعلمات اختيارية. تُرجع القيم خارج النطاق 400، ويتم تجاهل المعلمات غير المعروفة.
| المعامل | النوع | الوصف |
|---|---|---|
country | string | رمز البلد وفق ISO 3166-1 alpha-2 (مثل JP). تُرجع الصيغ الأخرى 400 |
q | string | الكلمة المفتاحية (حتى 60 حرفًا) |
isUnlimited | boolean | true = غير المحدودة فقط، false = استبعاد غير المحدودة — true | false (يُقبل أيضًا 1 | 0) |
minDays · maxDays | integer | نطاق الصلاحية بالأيام، 1–365 |
minDataGB | number | الحد الأدنى للبيانات بالـ GB، 0–1000 |
hasLocalNumber | boolean | يتضمن رقم هاتف محليًا — true | false (يُقبل أيضًا 1 | 0) |
isMultiCountry | boolean | منتج متعدد البلدان — true | false (يُقبل أيضًا 1 | 0) |
sortBy | string | recommended (افتراضي) | price | validity | data |
sortOrder | string | asc | desc — عند الحذف تُستخدم القيمة الافتراضية لكل sortBy |
page | integer | يبدأ من 1، والافتراضي 1 |
limit | integer | 1–50، الافتراضي 20 |
Sorting#
| sortBy | sortOrder الافتراضي | المعنى |
|---|---|---|
| recommended | desc | الترتيب الموصى به من esimoa (يشمل المبيعات) — بنفس ترتيب الموقع |
| price | asc | الأقل سعرًا أولًا |
| validity | asc | الأقصر صلاحية أولًا |
| data | desc | الأكثر بيانات أولًا |
ترقيم الصفحات#
يبدأ page من 1. تعيد الاستجابة page وlimit مع total، لذا فالصفحة الأخيرة هي ceil(total / limit).
الاستجابة#
200 OKjson
{
"success": true,
"data": [
{
"id": "partner_9VKPYQ3JRYVK5797",
"name": "Japan Unlimited 5일",
"country": "Japan",
"countryCode": "JP",
"coverageCountries": ["JP"],
"isMultiCountry": false,
"dataAmount": "Unlimited",
"isUnlimited": true,
"validityDays": 5,
"priceKRW": 12000,
"currency": "KRW",
"networkType": "5G",
"localNetworks": ["SoftBank"],
"isLocalNetwork": true,
"fupPolicy": null,
"hotspotEnabled": true,
"hasLocalNumber": false,
"voiceMinutes": null,
"smsCount": null,
"supportTopUp": false,
"supportsUsim": false,
"activationType": "instant"
}
],
"total": 128,
"page": 1,
"limit": 20
}The PartnerProduct object#
| الحقل | النوع | الوصف |
|---|---|---|
id | string | 'partner_<packageCode>' — معرّف المنتج نفسه المستخدم في esimoa.com |
name | string | الاسم المعروض بالصيغة "<area> <data> <N>일" (لاحقة الأيام الكورية). للغات الأخرى، أنشئ تسميتك الخاصة من الحقول المنظمة |
country | string | تسمية منطقة التغطية (تُدرج المنتجات متعددة البلدان بلدانها) |
countryCode | string? | رمز البلد ISO — يُحذف عند عدم توفره |
coverageCountries | string[] | رموز البلدان التي يعمل فيها المنتج |
region | string? | المنطقة — تُحذف إذا لم تكن متاحة |
isMultiCountry | boolean | منتج متعدد البلدان |
dataAmount | string | تسمية الكتالوج ('10GB', 'Unlimited', '1GB/Day + Unlimited' …) |
dataAmountGB | number? | البيانات بالـ GB — تُحذف للمنتجات غير المحدودة بالكامل |
isUnlimited | boolean | باقة غير محدودة |
validityDays | integer | الصلاحية بالأيام |
priceKRW / currency | integer / 'KRW' | سعر التجزئة من esimoa بـ KRW — لا يوجد سعر للشركاء في v1 |
networkType | string | الشبكة (مثل 5G) — '' عند عدم المعرفة |
localNetworks | string[] | المشغّلون المحليون |
isLocalNetwork | boolean | يستخدم شبكة محلية بدلًا من التجوال |
fupPolicy | string | null | نص سياسة الاستخدام العادل (FUP) |
hotspotEnabled | boolean | null | مشاركة الإنترنت مسموحة — null = غير معروف |
hasLocalNumber | boolean | يتضمن رقم هاتف محليًا |
voiceMinutes | integer | null | دقائق المكالمات — -1 = غير محدود، null = غير متوفر |
smsCount | integer | null | عدد الرسائل — null = غير متوفر |
supportTopUp | boolean | null | قابل للشحن — null = غير معروف |
supportsUsim | boolean | متوفرة أيضًا كشريحة USIM فعلية |
activationType | string | نوع التفعيل (مثل 'instant') |
ملاحظة
لا تتضمن الاستجابة أبدًا حقول المورّد والتكلفة. تُضاف الحقول فقط ولا تتغير أسماؤها أو معانيها، لذا حلّل الاستجابة بحيث تتجاهل الحقول غير المعروفة.
