eSIM API 체크리스트 (2026): 여행용 eSIM API가 반드시 갖춰야 할 12가지 기능

빠른 답변

실제 서비스에 바로 적용 가능한 여행용 eSIM API라면 보안 토큰 인증, 재시도 시 중복 결제를 방지하는 멱등성 키(idempotency keys), 가격을 고정해주는 가격 견적(price quotes), 모든 eSIM 이벤트에 대한 서명된 웹훅(signed webhooks), 전체 eSIM 라이프 사이클과 오류를 시뮬레이션할 수 있는 샌드박스, 충전(top-ups), 사용량 데이터, 일시 중지/재개(suspend/resume), 그리고 커버리지와 공정 사용 정책(fair-use)이 포함된 카탈로그 피드를 제공해야 합니다. 서비스를 출시하기 전에 샌드박스에서 이 모든 항목을 테스트하세요.

eSIM API를 앱, 여행 플랫폼 또는 예약 엔진에 연결하는 것은 어렵지 않습니다. 정말 어려운 것은 출시 후에 API가 타임아웃 시 중복 결제를 하거나, 고객의 데이터가 소진되었을 때 알려주지 못하거나, 오류 테스트를 할 방법이 없다는 사실을 깨닫는 것입니다.

이 체크리스트는 실제 운영 환경에서 중요한 12가지 기능과, 가입하기 전에 각 기능을 테스트하는 방법을 다룹니다. TripoSIM Partner API를 예시로 사용하지만, 동일한 체크리스트를 사용하여 어떤 제공업체와도 비교할 수 있습니다.

1. 보안 토큰 인증

확인할 사항: OAuth 2.0 클라이언트 자격 증명(client credentials): 클라이언트 ID와 secret을 교환하여 수명이 짧은 액세스 토큰을 받는 방식입니다. secret은 매 요청마다 전송되지 않습니다.

테스트 방법: 토큰을 요청한 다음, 토큰이 만료되는지 확인합니다. TripoSIM API에서는 POST /auth/token을 통해 15분 동안 유효한 액세스 토큰을 반환합니다. 코드가 토큰이 만료되기 전에 자동으로 갱신하는지 확인하세요.

2. 멱등성 키 (중복 결제 방지)

확인할 사항: 모든 주문과 충전 요청 시 Idempotency-Key 헤더를 사용하는지 확인합니다. 요청이 타임아웃되어 동일한 키로 재시도할 경우, API는 두 번째 eSIM을 결제하는 대신 원래의 결과를 반환해야 합니다.

테스트 방법: 동일한 키를 사용하여 동일한 주문을 두 번 보내고, 주문이 하나만 생성되는지 확인합니다. 그런 다음 다른 본문(body)과 함께 동일한 키를 보내보세요. 좋은 API라면 이를 거부해야 합니다. TripoSIM는 운영 주문과 충전 시 키를 요구하며, 키가 다른 요청과 함께 재사용되면 409 IDEMPOTENCY_KEY_REUSED를 반환합니다.

3. 가격을 고정하는 가격 견적

확인할 사항: 가격을 가져온 뒤 짧은 시간 동안 유지하여, 고객이 화면에 표시된 가격과 정확히 일치하는 금액을 지불할 수 있게 하는 방법입니다.

테스트 방법: 견적(quote)을 생성하고, 잠시 기다린 후 해당 견적으로 주문을 진행합니다. TripoSIM 견적은 10분 동안 유효합니다. 만료된 견적은 409 QUOTE_EXPIRED를 반환하므로, 예상치 못한 가격이 청구되는 대신 다시 견적을 받을 수 있습니다.

4. 깔끔한 카탈로그 피드

확인할 사항: 가격, 데이터, 유효 기간, 커버리지 국가, 5G 지원 여부, 충전 지원 여부, 그리고 무제한 요금제의 경우 일일 최대 속도 제한을 나열하는 단일 엔드포인트가 있는지 확인합니다.

테스트 방법: 특정 국가의 카탈로그를 불러와 제공업체의 자체 웹사이트와 비교해 보세요. TripoSIM /catalog 엔드포인트는 JSON 또는 CSV를 반환하며, 해당 국가를 커버하는 지역 요금제를 포함하고 무제한 요금제를 위한 공정 사용 필드(fup_daily_mb, fup_throttle_kbps)를 제공합니다. 무제한 일일 제한이 작동하는 방식을 확인하세요.

5. 즉각적인 주문 및 QR 전달

확인할 사항: 주문 응답(또는 몇 초 후의 웹훅)에 표준 LPA 형식의 활성화 코드가 포함되어야 합니다. 예를 들어 `LPA:1$smdp.example.com$ACTIVATION_CODE`와 같은 형식이어야 QR 코드를 보여주거나 원탭 설치 링크를 제공할 수 있습니다.

테스트 방법: 샌드박스 주문을 생성하고, LPA 문자열로부터 QR을 생성한 뒤, 휴대폰 카메라로 스캔하여 형식이 유효한지 확인합니다.

6. 모든 이벤트에 대한 서명된 웹훅

확인할 사항: 공격자가 위조할 수 없도록 서명된 전체 eSIM 라이프 사이클 푸시 알림이 있는지 확인합니다.

TripoSIM는 order.completed, order.failed, esim.activated, esim.usage_80, esim.suspended, esim.resumed, esim.depleted, esim.expired의 8가지 이벤트 유형을 전송합니다. 각 요청에는 서명 비밀(signing secret)을 사용하여 타임스탬프와 원본 본문의 HMAC-SHA256 값을 담은 X-TripoSIM-Signature 헤더가 포함됩니다.

<pre><code>// reject requests older than 5 minutes (replay protection) if (Math.floor(Date.now() / 1000) - parseInt(timestamp) > 300) throw new Error('Webhook too old'); const expected = crypto .createHmac('sha256', signingSecret) .update(timestamp + '.' + rawBody) .digest('hex'); if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) { throw new Error('Invalid webhook signature'); }</code></pre>

테스트 방법: 웹훅을 등록하고 주문을 발생시킨 뒤, 코드에서 서명을 검증합니다. 그 다음 본문의 1바이트를 변경하여 검증 로직이 이를 거부하는지 확인하세요.

7. 전체 eSIM 라이프를 시뮬레이션하는 샌드박스

확인할 사항: 실제 eSIM은 활성화되고 데이터를 사용하는 데 며칠이 걸립니다. 좋은 샌드박스는 이를 빠르게 진행(fast-forward)할 수 있게 해줍니다.

연결할 준비가 되셨나요?

200개 이상의 여행지에서 쓸 수 있는 여행용 eSIM을 받으세요 — 이메일로 즉시 QR 발송, 로밍 요금 없음, 결제 시 할인 자동 적용.

eSIM 요금제를 살펴보세요

테스트 방법: TripoSIM 샌드박스에서 POST /sandbox/esims/{iccid}/simulate를 호출하며 action을 activate, usage, deplete, expire 또는 reset으로 설정합니다. 각 단계마다 일치하는 웹훅이 발생하므로, "데이터가 거의 소진되었습니다"라는 이메일 테스트를 며칠이 아닌 몇 분 만에 완료할 수 있습니다.

8. 오류 시뮬레이션

확인할 사항: 앱이 오류를 적절히 처리하는지 알 수 있도록 의도적으로 오류를 발생시키는 방법이 있는지 확인합니다.

테스트 방법: X-Sandbox-Simulate 헤더에 insufficient_balance, price_changed, rate_limit, provider_unavailable 또는 timeout과 같은 모드를 담아 보내고, 앱이 명확한 메시지를 표시하는지, 그리고 재시도가 필요한 경우에만 재시도하는지 확인합니다.

9. 동일한 eSIM에 대한 충전

확인할 사항: 데이터가 소진된 고객이 새로운 eSIM을 설치하지 않고도 데이터를 추가할 수 있어야 합니다.

테스트 방법: 샌드박스에서 (멱등성 키와 함께) POST /esims/{iccid}/topup을 호출한 후, 새로운 데이터 잔량을 확인합니다. 또한 어떤 요금제가 충전을 지원하는지도 확인하세요. 카탈로그에서 확인할 수 있습니다.

10. 사용량 및 상태 데이터

확인할 사항: 사용한 데이터, 남은 데이터, 만료일을 확인할 수 있는 엔드포인트가 있어야 고객 지원 팀과 앱이 "데이터가 얼마나 남았나요?"라는 질문에 답할 수 있습니다.

테스트 방법: 시뮬레이션된 사용 이벤트 후에 GET /esims/{iccid}/usage를 호출합니다. TripoSIM는 사용량을 5분 동안 캐싱하므로, 실시간 알림을 위해서는 웹훅(esim.usage_80, esim.depleted)을 사용하세요.

11. 일시 중지 및 재개

확인할 사항: 결제 분쟁이 발생하거나 고객이 휴대폰 분실을 신고했을 때와 같이 eSIM을 일시 중지하고 나중에 다시 재개할 수 있는 방법입니다.

테스트 방법: 샌드박스 eSIM을 일시 중지(suspend)하고 esim.suspended 웹훅이 도착하는지 확인한 후, 다시 재개(resume)하여 esim.resumed를 확인합니다.

12. 명확한 속도 제한, 오류 코드 및 변경 로그

확인할 사항: 문서화된 제한 사항, 재시도 여부를 알려주는 오류 코드, 그리고 업데이트 내용을 미리 알 수 있는 공개 변경 로그(changelog)가 있는지 확인합니다.

테스트 방법: 오류 목록을 읽고 각 코드를 코드 내에서 "재시도" 또는 "재시도 안 함"으로 매핑합니다. TripoSIM는 파트너 계정당 분당 120개의 요청을 허용하며(개별 API 키에 대해 더 낮은 제한을 설정할 수 있음), 429 응답 시 Retry-After 헤더를 반환하고, 모든 오류 코드를 재시도 가능 여부로 표시하며, 변경 로그 엔드포인트를 게시합니다.

간단한 출시 계획

1일차: 샌드박스 키를 받고, 인증을 수행하며, 카탈로그를 불러옵니다.
2일차: 멱등성 키를 사용하여 샌드박스 주문을 생성하고 QR 코드를 표시합니다.
3일차: 웹훅을 추가하고 라이프 사이클 및 오류 시뮬레이터를 실행합니다.
4일차: 충전 및 사용량을 추가한 뒤, 실제 휴대폰에서 라이브 eSIM 하나로 테스트합니다.
5일차: 서비스를 출시합니다.

대부분의 팀은 일주일 이내에 연결을 완료합니다. 전체 API documentation을 읽거나 단계별 eSIM API integration guide를 확인하세요.

자주 묻는 질문

여행용 eSIM API에는 무엇이 포함되어야 하나요?

최소한 토큰 인증, 멱등성 키, 가격 견적, 카탈로그 피드, 즉각적인 QR/활성화 코드, 서명된 웹훅, 라이프 사이클 및 오류 시뮬레이터가 포함된 샌드박스, 충전, 사용량 데이터, 일시 중지/재개, 그리고 문서화된 속도 제한 및 오류 코드가 포함되어야 합니다.

eSIM API에서 멱등성 키가 왜 중요한가요?

모든 eSIM 주문에는 실제 비용이 발생합니다. 요청이 타임아웃되어 시스템이 재시도할 때, 멱등성 키가 있으면 두 번째 eSIM을 구매하는 대신 첫 번째 결과가 반환되도록 보장합니다.

eSIM을 구매하지 않고 eSIM API를 어떻게 테스트하나요?

샌드박스를 사용하세요. 좋은 샌드박스는 지갑에서 비용을 청구하지 않고도 주문, 활성화, 데이터 사용, 소진 및 만료를 시뮬레이션하며 오류를 강제로 발생시킬 수도 있게 해줍니다.

eSIM API 통합에는 얼마나 걸리나요?

문서화가 잘 된 API와 완전한 샌드박스가 있다면, 대부분의 팀은 영업일 기준 3~5일 이내에 서비스를 출시할 수 있습니다.

TripoSIM API는 화이트 라벨(white-label) 전달을 지원하나요?

네. 활성화 코드와 QR 데이터를 받으므로, 귀하의 브랜드로 귀하의 앱이나 이메일 내에서 eSIM을 전달할 수 있습니다. API program을 확인하세요.

결론

가격도 중요하지만, eSIM API의 진짜 차이는 출시 후에 나타납니다. 중복 결제가 없는 재시도, 신뢰할 수 있는 웹훅, 그리고 모든 것을 미리 테스트할 수 있는 샌드박스가 그 차이를 만듭니다. 계약하기 전에 어떤 제공업체든 이 체크리스트를 적용해 보세요. TripoSIM Partner API가 얼마나 우수한지 확인하려면 샌드박스부터 시작하세요.