概覽
公開 API（/v1）
/v1 API 的通用規則：基礎網址、回應結構、分頁規則與回應語言。
基礎網址#
所有請求皆透過 HTTPS 傳送到以下網址，並需要公開 API 金鑰（身分驗證），所有回應皆為 JSON。
url
https://api.esimoa.com/v1端點#
| 端點 | 說明 |
|---|---|
| GET /v1/esims | 搜尋 eSIM |
| GET /v1/esims/:id | eSIM 詳情 |
| GET /v1/countries | 販售國家列表 |
| GET /v1/openapi.json | OpenAPI 3.1 規格（無需金鑰） |
回應結構#
成功回應一律包含 "success": true。列表放在 items 中，詳情放在 item 中。
json
// List endpoints
{ "success": true, "items": [ ... ], "total": 42, "limit": 10, "offset": 0, "sort": "price" }
// Detail endpoint
{ "success": true, "item": { ... } }錯誤回應格式與狀態碼請參閱速率限制與錯誤。
分頁#
列表透過 limit（1–50，預設 10）與 offset 分頁。offset 一律向下取整為 limit 的倍數 — 例如 limit=10、offset=15 會以 offset=10 處理。回應中的 offset 為實際使用的值，total 為總數。
提示
請用 offset + limit 請求下一頁。若 offset 不是 limit 的倍數，同一商品可能在兩頁中重複出現，因此會向下取整。
回應語言#
lang 參數（ko | en | ja | zh-CN | zh-TW，預設 en）決定國家名稱、商品 title 以及 url 指向的購買頁面的語言。請與您使用者的語言保持一致。
價格與快取#
價格（priceKrw）為 esimoa 售價，以韓元（KRW）整數回傳。價格經常變動，搜尋結果請最多快取幾分鐘；實際付款金額一律以 esimoa 結帳頁面為準。