合作夥伴 API(B2B)
商品搜尋
GET /b2b/v1/products — 依國家、關鍵字、天數、流量等搜尋 esimoa 商品。
請求#
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"]查詢參數#
所有參數皆為選填。超出範圍的值回傳 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 |
排序#
| 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
}PartnerProduct 物件#
| 欄位 | 類型 | 說明 |
|---|---|---|
id | string | 'partner_<packageCode>' — 與 esimoa 網站的商品 id 相同 |
name | string | 格式為「<地區> <流量> <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 零售價(韓元)— 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') |
注意
回應中不含供應商與成本欄位。欄位只會新增,名稱與含義不會改變,解析時請忽略未知欄位。
