API công khai (/v1)

Liệt kê eSIM

GET /v1/esims — search eSIMs by country, duration and data, and get purchase URLs that carry your partner code.

On this page

Request
Query parameters
Filter rules
Phản hồi
The Esim object

Request#

GET/v1/esims

curl "https://api.esimoa.com/v1/esims?country=JP&days=7&sort=price&limit=3&lang=en" \
  -H "X-API-Key: esk_live_your_key_here"

const res = await fetch(
  'https://api.esimoa.com/v1/esims?country=JP&days=7&sort=price&limit=3&lang=en',
  { headers: { 'X-API-Key': process.env.ESIMOA_API_KEY } },
);
if (!res.ok) throw new Error(`esimoa API ${res.status}`);

const { items, total } = await res.json();
for (const esim of items) {
  console.log(esim.title, esim.priceKrw, esim.url);
}

import os
import requests

res = requests.get(
    "https://api.esimoa.com/v1/esims",
    params={"country": "JP", "days": 7, "sort": "price", "limit": 3, "lang": "en"},
    headers={"X-API-Key": os.environ["ESIMOA_API_KEY"]},
    timeout=10,
)
res.raise_for_status()

for esim in res.json()["items"]:
    print(esim["title"], esim["priceKrw"], esim["url"])

Query parameters#

Tất cả tham số đều không bắt buộc.

Tham số	Loại	Mô tả
`country`	string	Mã quốc gia (ISO 3166-1 alpha-2, ví dụ JP)
`days`	integer	Thời hạn chính xác theo ngày
`minDays`	integer	Thời hạn tối thiểu (ngày)
`maxDays`	integer	Thời hạn tối đa (ngày)
`dataGb`	number	Dữ liệu tối thiểu (GB)
`unlimited`	boolean	true = chỉ gói không giới hạn
`countries`	string	Chuyến đi nhiều nước — 2–8 mã quốc gia phân tách bằng dấu phẩy (vd. FR,IT,ES). Chỉ các gói dùng được ở tất cả
`maxDataGb`	number	Dữ liệu tối đa (GB)
`minPriceKrw / maxPriceKrw`	integer	Khoảng giá (KRW)
`dataType`	string	daily (dung lượng làm mới mỗi ngày) \| total (một dung lượng cho cả thời gian)
`localNumber`	boolean	true = chỉ các gói có số điện thoại địa phương (gọi/SMS)
`network`	string	local (mạng nhà mạng địa phương) \| roaming (mạng chuyển vùng)
`multiCountry`	boolean	true = chỉ gói nhiều nước, false = chỉ gói một nước
`provider`	string	Mã nhà cung cấp — đúng như trong provider
`hotspot / fiveG`	boolean	Hỗ trợ chia sẻ mạng / mạng 5G (gần đúng — xem quy tắc bên dưới)
`sort`	string	recommended (mặc định) \| price (giá thấp nhất trước) \| data (nhiều dữ liệu nhất trước) \| price_per_gb (giá mỗi GB thấp nhất trước) \| validity (thời hạn dài nhất trước)
`limit`	integer	1–50, mặc định 10
`offset`	integer	Số mục bỏ qua — làm tròn xuống bội số của limit
`lang`	string	Ngôn ngữ phản hồi: ko \| en \| ja \| zh-CN \| zh-TW (mặc định en)

Filter rules#

days sẽ ghi đè minDays và maxDays.
unlimited=true sẽ bỏ qua dataGb.
countries sẽ ghi đè country.
hotspot · fiveG được kiểm tra trong 50 gói đầu tiên khớp các bộ lọc khác. offset bị bỏ qua và phản hồi có totalIsApproximate: true.
Giá trị boolean chỉ nhận true, false, 1 hoặc 0; giá trị khác trả về 400.
Kết quả chỉ gồm sản phẩm do esimoa bán trực tiếp; không bao gồm sản phẩm đã ngừng bán.

Phản hồi#

200 OKjson

{
  "success": true,
  "items": [
    {
      "id": "partner_9VKPYQ3JRYVK5797",
      "title": "Japan · 100 MB · 7 days",
      "countryCode": "JP",
      "countryName": "Japan",
      "coverageCountries": ["JP"],
      "isMultiCountry": false,
      "dataAmount": "100 MB",
      "dataAmountGB": 0.1,
      "isUnlimited": false,
      "dataType": "total",
      "validityDays": 7,
      "priceKrw": 1000,
      "currency": "KRW",
      "provider": "TSIM",
      "networkType": "5G",
      "hotspot": true,
      "hasLocalNumber": false,
      "isLocalNetwork": true,
      "url": "https://www.esimoa.com/en/plans/jp/partner_9VKPYQ3JRYVK5797?ref=p_yourcode&utm_source=esimoa_partner"
    }
  ],
  "total": 42,
  "limit": 10,
  "offset": 0,
  "sort": "price"
}

The Esim object#

Trường	Loại	Mô tả
`id`	string	Mã sản phẩm — dùng với endpoint chi tiết
`title`	string	Tên hiển thị (theo lang)
`countryCode / countryName`	string \| null	Quốc gia chính (null với gói nhiều quốc gia)
`coverageCountries`	string[]	Mã các quốc gia mà eSIM hoạt động
`isMultiCountry`	boolean	Gói nhiều quốc gia
`dataAmount / dataAmountGB`	string / number	Dung lượng dữ liệu (nhãn / số GB)
`isUnlimited`	boolean	Gói không giới hạn
`dataType`	'total' \| 'daily' \| null	Dung lượng tổng hoặc theo ngày
`validityDays`	integer	Thời hạn tính theo ngày
`priceKrw / currency`	integer / 'KRW'	Giá theo KRW
`provider / networkType`	string	Nhà cung cấp / mạng (ví dụ: 5G)
`hotspot / hasLocalNumber / isLocalNetwork`	boolean	Chia sẻ mạng / số điện thoại địa phương / mạng địa phương
`url`	string	Liên kết mua hàng chứa mã đối tác của bạn (?ref=). Hiển thị nguyên trạng.

Lưu ý

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