合作伙伴 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') |
注意
响应中不含供应商与成本字段。字段只会新增,名称与含义不会改变,解析时请忽略未知字段。
