Overview
API công khai (/v1)
Shared rules of the /v1 API: base URL, response envelope, pagination and response language.
URL cơ sở#
Gửi mọi yêu cầu qua HTTPS đến địa chỉ bên dưới. Cần có khóa API công khai (Xác thực), và mọi phản hồi đều ở dạng JSON.
https://api.esimoa.com/v1Endpoint#
| Endpoint | Mô tả |
|---|---|
| GET /v1/esims | Tìm eSIM |
| GET /v1/esims/:id | Mua eSIM |
| GET /v1/countries | Liệt kê quốc gia |
| GET /v1/openapi.json | Đặc tả OpenAPI 3.1 (không cần khóa) |
Response envelope#
Phản hồi thành công luôn có "success": true. Danh sách nằm trong items và một kết quả đơn lẻ nằm trong item.
// List endpoints
{ "success": true, "items": [ ... ], "total": 42, "limit": 10, "offset": 0, "sort": "price" }
// Detail endpoint
{ "success": true, "item": { ... } }Về phản hồi lỗi và mã trạng thái, hãy xem Giới hạn tần suất và lỗi.
Phân trang#
Danh sách được phân trang bằng limit (1–50, mặc định 10) và offset. offset luôn được làm tròn xuống bội số của limit — ví dụ limit=10, offset=15 được xử lý như offset=10. offset trong phản hồi là giá trị thực tế được dùng, còn total là tổng số.
Tiền boa
Response language#
Tham số lang (ko | en | ja | zh-CN | zh-TW, mặc định en) đặt ngôn ngữ cho tên quốc gia, tiêu đề sản phẩm và trang mua hàng mà url trỏ tới. Hãy đặt trùng với ngôn ngữ của người dùng.
Prices & caching#
Giá (priceKrw) là giá bán của esimoa tính bằng KRW dạng số nguyên. Giá thay đổi thường xuyên — chỉ lưu bộ nhớ đệm kết quả tìm kiếm tối đa vài phút; trang thanh toán của esimoa luôn là nguồn chuẩn cho số tiền bị trừ.