Open API 문서
Open API는 파트너와 관리자가 권한을 허용한 회원을 위한 서비스입니다. 시스템은 /v1을 호출하여 카탈로그 조회, 주문 생성·조회, eSIM 프로필(ICCID + LPA 설치 코드) 수신, 사용량 추적 및 REST 주기 조회를 통한 대사를 수행합니다. 결제는 키 소유자인 조직 또는 회원의 지갑에서 차감됩니다. 웹훅은 조직용이며, 회원 가격과 청구서는 자체 통합 가이드의 회원 OpenAPI 절차를 따릅니다.
API 한눈에 보기
작업 30개
6개 그룹: 카탈로그 · 주문 · eSIM · 지갑 · 웹훅 · 테스트 모드.
통합 인증
GET을 포함한 모든 요청에 X-TKE-* 헤더 4개와 HMAC-SHA256 서명이 필요합니다.
일관된 응답 형식
{ ok, data } 또는 { ok, error }와 의미에 맞는 HTTP 상태를 반환합니다. 오류에 200을 사용하지 않습니다.
공개 오류 코드 91개
백엔드 레지스트리의 각 오류 코드에는 HTTP 상태와 재시도 가능 여부가 포함됩니다.
웹훅 이벤트 8개
POST /v1/webhooks로 설정하며 전용 비밀 키, 최소 1회 전달, 전송 기록 및 재전송을 지원합니다.
전용 호스트 테스트 모드
api-testing.tongkhoesim.com은 tke_test_ 키만 받습니다. 가상 지갑·재고·고정 모의 발급·자동 사용량을 제공하며, 준비 후 운영 호스트와 tke_live_로 전환합니다.
text
https://api.tongkhoesim.com/v1 # 운영
https://api-testing.tongkhoesim.com/v1 # 테스트 모드실제 환경: api.tongkhoesim.com / tke_live_(파트너) 또는 tke_member_live_(허가된 회원). 테스트: api-testing.tongkhoesim.com / tke_test_ / tke_member_test_(파트너 / 회원).
4단계 시작 안내
1. 테스트 키 만들기
테스트 모드에서 tke_test_ 키를 만드세요. 한 번만 표시되는 비밀 키를 안전하게 보관하세요. 첫 키 생성 시 상태가 다른 샘플 주문 3개를 자동 생성하며 테스트 지갑은 무제한 충전할 수 있습니다.
2. 테스트 호스트에서 주문
HMAC으로 서명하여 POST https://api-testing.tongkhoesim.com/v1/orders를 호출하세요. ICCID 8999 모의 eSIM을 즉시 발급하며 실제 재고와 자금에는 영향이 없습니다. 콘솔 또는 Postman을 사용할 수 있습니다.
3. 웹훅 등록 및 테스트
POST /v1/webhooks로 URL을 등록하세요. CHECK_HEALTH에 2xx 응답이 필요합니다. /v1/testmode/webhooks/fire로 이벤트를 보내고 /fail-next로 재시도를 시험하세요.
4. 운영 키로 전환
코드는 그대로 두고 tke_live_ 키, 운영 호스트, key_id, secret으로 바꾸세요. 웹훅은 api_key_id별로 분리되므로 운영 키에 별도로 등록하세요.
주의할 연동 함정 3가지
다음 세 가지는 테스트를 통과해도 실제 결제나 대사에서만 드러날 수 있습니다.
Idempotency-Key는 API 키별로 적용
중복 제거 범위는 api_key_id입니다. 같은 조직이라도 두 키로 같은 Idempotency-Key를 보내면 주문과 차감이 두 번 발생합니다. 주문 흐름별로 키를 고정하거나 key_id를 포함하세요.
REST의 id와 웹훅의 order_item_id
REST의 eSIM id는 웹훅의 order_item_id와 같은 UUID이며 order_id는 상위 주문입니다. ICCID는 재사용될 수 있으므로 이 UUID로 저장하세요. GET /v1/esims?iccid=…로 id를 찾을 수 있습니다. 주문에 external_ref를 보내면 REST 및 eSIM 웹훅에서 order_id와 함께 반환되며 ?external_ref=…로 관련 eSIM을 조회합니다.
커서 페이지 반복 종료 조건
GET /v1/orders 및 /v1/esims는 커서 방식입니다. 잘못된 커서는 오류 없이 처음으로 돌아갑니다. next_cursor가 없거나 현재 커서와 같으면 중지하세요. !== null만 확인하면 무한 반복할 수 있습니다.