개요
공개 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 로 요청하세요. limit 배수가 아닌 offset 을 쓰면 같은 상품이 두 페이지에 걸쳐 다시 나올 수 있어 내림 처리해요.
응답 언어#
lang 파라미터(ko | en | ja | zh-CN | zh-TW, 기본 en)는 국가 이름, 상품 title, 그리고 url 이 가리키는 구매 페이지의 언어를 정해요. 내 사용자의 언어에 맞춰 보내세요.
가격과 캐시#
가격(priceKrw)은 이심모아 판매가를 원화(KRW) 정수로 줘요. 가격은 자주 바뀌니 검색 결과는 몇 분 이내로만 캐시하고, 결제 금액은 항상 이심모아 결제 화면이 기준이에요.