概览
公开 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 结账页面为准。