概要
公開API（/v1）
ベースURL、レスポンス形式、ページング規則、レスポンス言語など /v1 API の共通ルールです。
ベースURL#
すべてのリクエストは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 でリクエストしてください。limit の倍数でない offset だと同じ商品が別ページに再び出る可能性があるため、切り捨てています。
レスポンス言語#
lang パラメータ（ko | en | ja | zh-CN | zh-TW、既定 en）は国名、商品の title、そして url が指す購入ページの言語を決めます。ユーザーの言語に合わせて送ってください。
価格とキャッシュ#
価格（priceKrw）はesimoaの販売価格をウォン（KRW）の整数で返します。価格は頻繁に変わるため、検索結果のキャッシュは数分以内にし、決済金額は常にesimoaの決済画面が基準です。