API đối tác (B2B)

Sản phẩm

GET /b2b/v1/products — search esimoa products by country, keyword, duration, data and more.

On this page

Request
Query parameters
Sorting
Phân trang
Phản hồi
The PartnerProduct object

Request#

GET/b2b/v1/products

curl "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#

Tất cả tham số đều không bắt buộc. Giá trị ngoài phạm vi trả về 400; tham số không xác định sẽ bị bỏ qua.

Tham số	Loại	Mô tả
`country`	string	Mã quốc gia ISO 3166-1 alpha-2 (ví dụ: JP). Định dạng khác trả về 400
`q`	string	Từ khóa (tối đa 60 ký tự)
`isUnlimited`	boolean	true = chỉ gói không giới hạn, false = loại trừ gói không giới hạn — true \| false (cũng chấp nhận 1 \| 0)
`minDays · maxDays`	integer	Khoảng thời hạn tính theo ngày, 1–365
`minDataGB`	number	Dữ liệu tối thiểu tính bằng GB, 0–1000
`hasLocalNumber`	boolean	Kèm số điện thoại địa phương — true \| false (cũng chấp nhận 1 \| 0)
`isMultiCountry`	boolean	Sản phẩm nhiều quốc gia — true \| false (cũng chấp nhận 1 \| 0)
`sortBy`	string	recommended (mặc định) \| price \| validity \| data
`sortOrder`	string	asc \| desc — nếu bỏ trống sẽ dùng mặc định theo sortBy
`page`	integer	Bắt đầu từ 1, mặc định 1
`limit`	integer	1–50, mặc định 20

Sorting#

sortBy	sortOrder mặc định	Ý nghĩa
recommended	desc	Xếp hạng đề xuất của esimoa (có tính doanh số) — cùng thứ tự với trang web
price	asc	Giá thấp đến cao
validity	asc	Thời hạn ngắn nhất trước
data	desc	Nhiều dữ liệu nhất trước

Phân trang#

page bắt đầu từ 1. Phản hồi trả về page và limit cùng total, nên trang cuối là ceil(total / limit).

Phản hồi#

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#

Trường	Loại	Mô tả
`id`	string	'partner_<packageCode>' — cùng id sản phẩm được dùng trên esimoa.com
`name`	string	Tên hiển thị theo dạng "<area> <data> <N>일" (hậu tố ngày tiếng Hàn). Với ngôn ngữ khác, hãy tự tạo nhãn từ các trường có cấu trúc
`country`	string	Nhãn vùng phủ sóng (sản phẩm đa quốc gia liệt kê các quốc gia)
`countryCode`	string?	Mã quốc gia ISO — bỏ qua nếu không có
`coverageCountries`	string[]	Mã các quốc gia mà sản phẩm hoạt động
`region`	string?	Khu vực — bỏ qua nếu không có
`isMultiCountry`	boolean	Sản phẩm nhiều quốc gia
`dataAmount`	string	Nhãn danh mục ('10GB', 'Unlimited', '1GB/Day + Unlimited' …)
`dataAmountGB`	number?	Dữ liệu theo GB — bỏ trống với sản phẩm hoàn toàn không giới hạn
`isUnlimited`	boolean	Gói không giới hạn
`validityDays`	integer	Thời hạn tính theo ngày
`priceKRW / currency`	integer / 'KRW'	Giá bán lẻ esimoa bằng KRW — v1 không có giá đối tác
`networkType`	string	Mạng (ví dụ: 5G) — '' nếu không xác định
`localNetworks`	string[]	Nhà mạng địa phương
`isLocalNetwork`	boolean	Dùng mạng địa phương thay vì chuyển vùng
`fupPolicy`	string \| null	Nội dung chính sách sử dụng hợp lý (FUP)
`hotspotEnabled`	boolean \| null	Cho phép chia sẻ mạng — null = không xác định
`hasLocalNumber`	boolean	Kèm số điện thoại địa phương
`voiceMinutes`	integer \| null	Phút gọi thoại — -1 = không giới hạn, null = không cung cấp
`smsCount`	integer \| null	Số lượng SMS — null = không cung cấp
`supportTopUp`	boolean \| null	Có thể nạp thêm — null = không xác định
`supportsUsim`	boolean	Cũng có bán dạng USIM vật lý
`activationType`	string	Loại kích hoạt (ví dụ: 'instant')

Lưu ý

Phản hồi không bao giờ chứa trường nhà cung cấp và giá vốn. Trường chỉ được bổ sung thêm, tên và ý nghĩa không thay đổi — hãy phân tích sao cho bỏ qua các trường không xác định.