개발자
엔드포인트 넷, webhook 둘, 뜻밖의 일은 없습니다.
스토어가 하는 일은 여러분의 제품도 할 수 있습니다. 전체 인터페이스가 한 페이지에 들어갑니다.
이 API가 존재하는 이유
통신 준비는 여행자가 예약하는 그 순간에, 여러분의 제품 안에서 끝나야 합니다. 공항에 도착해서야 알게 되는 일이면 안 됩니다.
예약 플랫폼은 일정에 데이터를 붙일 수 있습니다. 기기 제조사는 초기 설정 중에 요금제를 켤 수 있습니다. 팀용 도구는 새로 합류한 사람에게 노트북과 함께 데이터를 건넬 수 있습니다.
세 경우 모두 호출 네 번과 webhook 하나면 끝납니다. 로그인해야 하는 파트너 포털도 없고, 올려야 하는 CSV도 없습니다.
인증
모든 요청에 키를 베어러 토큰으로 실어 보내십시오. 키 접두사는 샌드박스가 sk_test, 운영이 sk_live입니다.
환경을 헷갈려 붙여 넣은 키는 조용히 돈을 쓰는 대신 401로 실패합니다. 키에는 범위가 있어서, 읽기 전용 키로는 주문할 수 없고 한 팀 계정으로 발급한 키는 다른 계정을 보지 못합니다.
콘솔에서 언제든 교체할 수 있습니다. 이전 키는 24시간 동안 계속 동작하므로, 한날한시에 전부 갈아엎어야 하는 상황은 생기지 않습니다.
curl https://api.orbislo.com/v1/catalog?country=jp \
-H "Authorization: Bearer sk_live_9f2c..." \
-H "Orbislo-Version: 2026-08-01"버전 헤더에 관하여
버전 헤더는 선택 사항이며, 응답 형태를 날짜가 붙은 릴리스에 고정합니다. 보내지 않으면 키를 만들 때의 버전이 쓰이고, 그 버전이 밑에서 바뀌는 일은 없습니다.
필드는 예고 없이 추가합니다. 같은 버전 안에서 필드를 없애거나 타입을 바꾸는 일은 절대 없습니다.
4
API 전체의 엔드포인트 수, 그리고 webhook 이벤트 2개
90초
주문 성공에서 프로파일 활성화까지 걸리는 시간의 중앙값
24시간
같은 멱등 키를 다시 보내면 원래 응답을 돌려주는 기간
엔드포인트 목록
| 메서드 | 경로 | 하는 일 | 속도 제한 |
|---|---|---|---|
| GET | /v1/catalog | 판매 중인 모든 요금제. 가격, 데이터, 유효 기간, 대상 국가 포함. | 분당 600 |
| POST | /v1/orders | 요금제를 사고, 프로비저닝 작업이 붙은 주문을 돌려줍니다. | 분당 60 |
| GET | /v1/provisioning/:id | 프로비저닝 작업 하나의 상태. queued부터 activated 또는 failed까지. | 분당 600 |
| GET | /v1/usage/:esim_id | 사용한 바이트, 남은 바이트, 그리고 그 eSIM이 붙은 통신사. | 분당 300 |
제한은 키별 슬라이딩 윈도로 적용됩니다. 모든 응답에 남은 횟수와 초기화 시각이 담기고, 429에는 재시도까지 걸리는 초가 담깁니다. 쓰임새상 정말 더 큰 한도가 필요하면 말씀하십시오. 한도를 키우는 일은 설정 변경이지 협상이 아닙니다.
카탈로그
무엇이 있고 얼마인지에 대한 기준은 카탈로그입니다. 오늘 운영 중인 145개 여행지를 모두 담고 있습니다.
국가, 지역, 요금제 계열로 걸러 볼 수 있습니다. 가격은 최소 화폐 단위로 돌아오므로 부동소수점이 여러분의 청구 코드까지 오지 않습니다.
GET /v1/catalog?country=jp
{
"object": "list",
"data": [
{
"id": "plan_jp_5gb",
"name": "Japan 5 GB",
"countries": ["jp"],
"data_mb": 5120,
"price": { "amount": 1150, "currency": "usd" },
"expires": false,
"throttle_mbps": null,
"tethering": true,
"carriers": ["NTT Docomo", "KDDI", "SoftBank"]
}
],
"has_more": false
}두 번 읽을 가치가 있는 두 필드
expires 필드는 저희가 파는 모든 종량제 요금제에서 false입니다. 저희 데이터는 소멸하지 않기 때문입니다. 가격 비교를 만들고 있다면, 이 필드가 가격보다 계산을 더 크게 바꿉니다.
throttle_mbps 필드는 종량제에서 null, 무제한 데이 패스에서 1입니다. 데이 패스는 하루 2 GB까지 최고 속도이고 그 뒤로는 1 Mbps로 내려갑니다.
이 제한 수치를 API에 넣는 이유는 구매 버튼에 찍어 두는 이유와 같습니다. 여행자가 나중에 알게 되는 숫자는 곧 문의 티켓이 됩니다.
주문
POST 한 번이면 요금제를 사고 프로비저닝이 시작됩니다. Idempotency-Key 헤더는 권장이 아니라 필수입니다.
이 API에서 가장 나쁜 결말은, 여행자에게 결제가 됐는지 알 수 없는 채로 끝나는 타임아웃입니다. 키를 필수로 두면 그 상태 자체가 사라집니다.
POST /v1/orders
Idempotency-Key: 4f1d0f6e-1c3a-4a2b-9d77-1b6a0e7c9f21
Content-Type: application/json
{
"plan_id": "plan_jp_5gb",
"traveller_ref": "user_88213",
"imei": "356938035643809",
"activate": "on_first_use"
}
201 Created
{
"id": "ord_7Kd2mQ",
"status": "provisioning",
"esim_id": "esim_2xB9Ln",
"provisioning_id": "prv_5Ttq81",
"amount": { "amount": 1150, "currency": "usd" },
"activation": {
"type": "universal_link",
"url": "https://orbislo.com/i/2xB9Ln",
"lpa": "LPA:1$rsp.orbislo.com$K4-9TT-2XB9LN"
}
}기기 확인과 지연 활성화
imei 필드는 선택이지만 강하게 권합니다. 보내 주시면 돈을 받기 전에 eSIM 지원 여부와 통신사 잠금을 확인합니다.
프로파일을 담을 수 없는 휴대폰에는, 팔린 요금제와 화난 여행자 대신 device_not_eligible이 붙은 422가 돌아갑니다.
activate를 on_first_use로 두면 유효 기간이 여러분의 서버가 호출한 시점이 아니라 여행자가 도착한 시점부터 시작됩니다.
프로비저닝 상태
반대편에 통신사 플랫폼이 있기 때문에 프로비저닝은 비동기입니다. 이 엔드포인트를 조회하거나, webhook을 받아서 조회 자체를 건너뛰십시오.
queued에서 activated까지 중앙값은 90초 미만입니다. 10분이 지나도 queued면 실패이고, 환불은 자동으로 이뤄집니다.
GET /v1/provisioning/prv_5Ttq81
{
"id": "prv_5Ttq81",
"status": "activated",
"states": [
{ "state": "queued", "at": "2026-08-24T09:14:02Z" },
{ "state": "provisioning", "at": "2026-08-24T09:14:04Z" },
{ "state": "installed", "at": "2026-08-24T09:14:41Z" },
{ "state": "activated", "at": "2026-08-24T09:15:07Z" }
],
"carrier": "KDDI",
"failure_reason": null
}Webhook
이벤트는 둘이고, 둘 다 여행자에게 전할 내용을 바꿉니다. 아무 HTTPS 엔드포인트로나 보낼 수 있고, 환경마다 따로 설정합니다.
Webhook 이벤트
| 이벤트 | 발생 시점 | 받고 나서 할 일 |
|---|---|---|
| esim.activated | 프로파일이 처음으로 네트워크에 붙었을 때. | 연결됐다고 여행자에게 알리십시오. 구매가 그 사람에게 실감이 되는 순간입니다. |
| esim.depleted | 사용량이 기준선을 넘을 때. 80퍼센트에서 한 번, 100퍼센트에서 다시 한 번. | 발이 묶인 뒤가 아니라 그 전에 충전을 제안하십시오. |
POST https://your-app.example/hooks/orbislo
Orbislo-Signature: t=1756032907,v1=6c1b...
Content-Type: application/json
{
"id": "evt_9pQ4rz",
"type": "esim.depleted",
"created": "2026-08-24T11:41:33Z",
"data": {
"esim_id": "esim_2xB9Ln",
"threshold": 80,
"used_mb": 4096,
"remaining_mb": 1024,
"country": "jp"
}
}전달 검증
타임스탬프, 마침표, 그리고 가공하지 않은 요청 본문을 이어 붙여 엔드포인트 시크릿으로 HMAC SHA-256을 계산하십시오. 비교는 상수 시간으로 하십시오.
타임스탬프가 5분보다 오래된 것은 거부하십시오. 재전송 공격을 막아 줍니다. 전달은 최소 1회이고 24시간 동안 8번까지 재시도되므로, 핸들러는 이벤트 ID를 기준으로 중복을 걸러야 합니다.
오류 코드
| HTTP | 코드 | 의미 | 해야 할 일 |
|---|---|---|---|
| 400 | invalid_request | 필드가 빠졌거나 타입이 틀렸습니다. 본문에 해당 필드 이름이 있습니다. | 요청을 고치십시오. 재시도는 도움이 되지 않습니다. |
| 401 | invalid_token | 베어러 토큰이 틀렸거나, 폐기됐거나, 다른 환경의 것입니다. | 샌드박스 키를 운영 호스트로 보내고 있지 않은지 확인하십시오. |
| 402 | insufficient_balance | 계정 잔액이 주문 금액에 미치지 못합니다. | 충전한 뒤 같은 멱등 키로 다시 시도하십시오. |
| 404 | not_found | 이 환경에는 그 ID를 가진 객체가 없습니다. | 샌드박스 ID와 운영 ID는 서로 통용되지 않습니다. |
| 409 | idempotency_conflict | 같은 멱등 키가 다른 본문으로 재사용됐습니다. | 새 키를 쓰거나, 원래 본문을 바이트 단위로 그대로 다시 보내십시오. |
| 422 | device_not_eligible | 기기가 eSIM을 지원하지 않거나 통신사 잠금이 걸려 있습니다. | 돈을 받기 전에 기기 확인을 돌리십시오. |
| 429 | rate_limited | 그 엔드포인트의 한도를 넘겼습니다. | 헤더의 재시도 지연만큼 물러나십시오. 계속 두드리지 마십시오. |
| 500 | internal_error | 저희 잘못입니다. 이미 알림이 울리고 있습니다. | 2초 뒤 같은 멱등 키로 다시 시도하십시오. |
| 503 | provider_unavailable | 상위 통신사 플랫폼이 멈췄습니다. | 최대 10분까지 재시도하십시오. 두 번째 통신사가 있는 곳에서는 자동으로 넘깁니다. |
모든 오류 본문에는 코드, 사람이 읽을 수 있는 메시지, 요청 ID가 담깁니다. 고객지원에 요청 ID를 알려 주면 앞의 네 가지 질문을 건너뜁니다.
샌드박스와 운영의 차이
호스트도, 경로도, 응답 형태도 같습니다. 접두사가 sk_test인 키는 돈에 닿지 않고 통신사 프로파일도 만들지 않습니다.
프로비저닝 작업은 상태 전이를 전부 4초쯤에 통과하므로, 테스트가 건마다 90초씩 잠들 일이 없습니다.
요금제 ID plan_test_fail을 주문하면 사유가 붙은 실패 작업을 받습니다. plan_test_slow를 주문하면 provisioning 상태로 11분 머무는 작업을 받아, 타임아웃 경로를 시험할 수 있습니다.
webhook 전달은 샌드박스에서도 발생하며, 환경마다 지정한 URL로 갑니다.
아무것도 만들고 싶지 않다면
제휴 프로그램은 연동 없이도 소개한 주문에 대해 보상을 지급합니다. 대부분의 콘텐츠 사이트에는 이 편이 정답입니다.
MCP 엔드포인트는 설정 한 줄과 코드 없이, 저희 커버리지 데이터셋과 가격 지수를 AI 어시스턴트에 열어 줍니다.
여러분이 팔게 될 요금제, 카탈로그 뒤에 있는 실측 속도 데이터, 국가 전체 목록은 모두 이 사이트에 공개돼 있습니다.
개발자들이 묻는 것들
오늘 바로 API 키를 받을 수 있나요?
승인까지 얼마나 걸리나요?
샌드박스와 운영은 무엇이 다른가요?
멱등 키가 꼭 필요한가요?
속도 제한은 어떻게 되나요?
webhook은 얼마나 믿을 만한가요?
SDK가 있나요?
프로비저닝이 실패하면 어떻게 되나요?
샌드박스로 시작하거나, 코드를 아예 건너뛰거나
샌드박스 자격 증명은 같은 영업일에 도착합니다. 연동을 쓰고 싶지 않다면, 제휴 프로그램도 MCP 엔드포인트도 만들 것이 없습니다.