Tổng Kho eSIM
테스트 환경

테스트 모드

api-testing.tongkhoesim.com에서 파트너 tke_test_ 또는 회원 tke_member_test_ 키를 사용하세요. 가상 잔액과 모의 eSIM은 실제 자금, 재고, 청구서와 분리됩니다. 지원 작업은 키 소유자에 따라 다르며 대량 주문, 웹훅, 환불 심사 제한은 회원 안내를 확인하세요.

실제 자금 사용 전에 전체 흐름을 테스트하세요. 다음 참조: HMAC 서명 인증 공식 및 테스트 콘솔 브라우저에서 테스트 요청을 보내세요.

회원을 위한 OpenAPI

관리자가 회원별 OpenAPI 권한을 부여합니다. 기본 사이드바에서 API 키를 열고 실제 또는 테스트 모드를 선택해 키를 만드세요. 비밀 키는 한 번만 표시됩니다. 두 모드는 키 한도를 공유하며, 권한을 끄면 두 모드가 차단되지만 키 폐기는 가능합니다.

실제 모드는 회원의 실제 VND 지갑을 사용하며 신용 한도가 없습니다. 테스트는 별도 가상 지갑과 모의 eSIM을 사용합니다. 테스트 모드에서 가상 잔액과 샘플 데이터를 추가하거나 초기화할 수 있습니다. 테스트 주문은 실제 구매 내역에 표시되지 않습니다.

회원의 대량 주문과 웹훅은 두 모드 모두 지원되지 않습니다. 검토가 필요한 환불 요청은 실제 모드 전용입니다. 테스트 eSIM을 취소해 가상 지갑 환불을 시험하세요. 테스트는 실제 공급자를 호출하거나 실제 MISA 청구서를 발행하지 않습니다. 미지원 작업은 capability.not_supported를 반환합니다.

회원 API 엔드포인트

키 유형별 두 호스트

키 유형에 맞는 호스트를 사용하세요. 잘못된 호스트는 업무 처리 전에 거부됩니다.

호스트기본 URL허용 키
운영https://api.tongkhoesim.com/v1tke_live_ / tke_member_live_
테스트https://api-testing.tongkhoesim.com/v1tke_test_ / tke_member_test_

테스트 키 만들기

대시보드 테스트 모드에서 tke_test_를 만들고 한 번 표시되는 비밀 키를 보관하세요. 첫 키는 POST /v1/testmode/seed를 자동 실행합니다.

운영과 테스트의 7가지 차이

항목운영 (api, tke_live_)테스트 (api-testing, tke_test_)
호스트api.tongkhoesim.comapi-testing.tongkhoesim.com — 잘못된 호스트: 403
지갑실제 조직 지갑가상 지갑, 대시보드 또는 관리자 조정으로 무제한 충전
재고실제 esim_profiles가상 재고, 모의 eSIM 무제한 생성
발급실제 통신사동일 입력에 동일 모의 ICCID/LPA 생성 (LPA:1$testmode-smdp.tongkhoesim.com$…)
사용량실제 통신사 측정자동 증가, 75/90% 알림
웹훅실제 운영 이벤트테스트 이벤트, 수동 전송 및 fail-next
원장실제 재무 원장격리된 가상 원장, 추가 전용이며 삭제하거나 운영 원장과 혼합하지 않음
POST

/v1/testmode/seed

POST /v1/testmode/seed가 즉시 사용할 샘플을 생성합니다. 조직별 멱등 처리로 재호출 시 중복 없이 already_seeded: true를 반환합니다.

  • 충분한 잔액의 테스트 지갑
  • 조직 가격의 실제 요금제 3종으로 각 eSIM 1개인 주문 3개
  • 3가지 상태: 미설치 · 사용량 40% · 만료
bash
#!/usr/bin/env bash
# Requires: bash + openssl + uuidgen.

KEY_ID="tke_test_REPLACE_WITH_YOUR_KEY_ID"
SECRET="REPLACE_WITH_YOUR_SECRET"

METHOD="POST"
REQ_PATH="/v1/testmode/seed"
BODY='{}'

TS="$(date +%s000)"                 # epoch milliseconds
NONCE="$(uuidgen)"
BODY_HASH="$(printf '%s' "$BODY" | openssl dgst -sha256 -hex | awk '{print $NF}')"
SIGNING="$METHOD"$'\n'"$REQ_PATH"$'\n'"$TS"$'\n'"$NONCE"$'\n'"$BODY_HASH"
SIG="$(printf '%s' "$SIGNING" | openssl dgst -sha256 -hmac "$SECRET" -hex | awk '{print $NF}')"

curl -sS -X "$METHOD" "https://api-testing.tongkhoesim.com$REQ_PATH" \
  -H "X-TKE-Key: $KEY_ID" \
  -H "X-TKE-Timestamp: $TS" \
  -H "X-TKE-Nonce: $NONCE" \
  -H "X-TKE-Signature: $SIG" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  --data-raw "$BODY"
json
{
  "ok": true,
  "data": {
    "seeded": true,
    "already_seeded": false,
    "orders_created": 3,
    "esims_created": 3
  }
}

자동 사용량 증가 (drift)

활성화된 테스트 eSIM은 기본 5분 주기로 소진 또는 만료까지 사용량이 증가합니다. 75% 및 90%에 esim.usage_threshold를 전송합니다. GET /v1/testmode/status로 상태와 주기를 확인합니다.

/v1/testmode/* 엔드포인트

api-testing.tongkhoesim.com에서 tke_test_ 키로만 호출합니다. 이전 경로 별칭은 없습니다.

메서드경로목적
GET/v1/testmode/status준비 상태, 체크리스트, 키/주문/eSIM 수, 지갑, 웹훅 및 drift 상태
POST/v1/testmode/seed조직별 멱등 샘플 생성
POST/v1/testmode/reset테스트 주문/eSIM 소프트 삭제, 상쇄 원장 기록으로 지갑 초기화
POST/v1/testmode/esims/{order_item_id}/simulate사용량, 상태, 만료, 속도 제한 및 다음 통신사 거부 모의
POST/v1/testmode/webhooks/fire샘플 이벤트({event_type})를 테스트 웹훅으로 즉시 전송
POST/v1/testmode/webhooks/fail-next다음 N회 전송을 503 실패시켜 재시도 시험
상태 변경 감사 출처 (via)
via발생 시점ref_id 의미
open_api테스트 키의 /v1 호출: 주문, 충전, 취소 또는 시뮬레이션호출 키의 api_keys.id
simulate구성원 또는 대리 관리자가 대시보드에서 시뮬레이션구성원 또는 관리자 ID
seed/v1/testmode/seed로 생성한 데이터비어 있음
POST

/v1/testmode/esims/{id}/simulate

test-mode-only

POST /v1/testmode/esims/{order_item_id}/simulate로 사용량, 상태, 만료, 속도를 설정하거나 다음 충전/취소를 1회 거부시킵니다.

bash
#!/usr/bin/env bash
KEY_ID="tke_test_REPLACE_WITH_YOUR_KEY_ID"
SECRET="REPLACE_WITH_YOUR_SECRET"
ORDER_ITEM_ID="REPLACE_WITH_ORDER_ITEM_ID"

METHOD="POST"
REQ_PATH="/v1/testmode/esims/$ORDER_ITEM_ID/simulate"
BODY='{"data_used_mb":4096,"status":"enabled"}'

TS="$(date +%s000)"
NONCE="$(uuidgen)"
BODY_HASH="$(printf '%s' "$BODY" | openssl dgst -sha256 -hex | awk '{print $NF}')"
SIGNING="$METHOD"$'\n'"$REQ_PATH"$'\n'"$TS"$'\n'"$NONCE"$'\n'"$BODY_HASH"
SIG="$(printf '%s' "$SIGNING" | openssl dgst -sha256 -hmac "$SECRET" -hex | awk '{print $NF}')"

curl -sS -X "$METHOD" "https://api-testing.tongkhoesim.com$REQ_PATH" \
  -H "X-TKE-Key: $KEY_ID" \
  -H "X-TKE-Timestamp: $TS" \
  -H "X-TKE-Nonce: $NONCE" \
  -H "X-TKE-Signature: $SIG" \
  -H "Content-Type: application/json" \
  --data-raw "$BODY"
# No Idempotency-Key required: state mutation is intrinsically idempotent.
json
{
  "ok": true,
  "data": {
    "order_item_id": "018f2b00-0000-7000-8000-000000000001",
    "esim_state": "enabled",
    "running_package_code": "TKE-VN-30D-X3K9F",
    "running_started_at": "2026-07-11T07:00:00Z",
    "running_expires_at": "2026-08-10T07:00:00Z",
    "data_bytes": 5368709120,
    "used_bytes": 4294967296,
    "remaining_bytes": 1073741824,
    "throttled": false,
    "via": "simulate",
    "last_via": "simulate",
    "mode": "test",
    "updated_at": "2026-07-11T09:15:00Z"
  }
}

테스트 모드 오류 코드

오류 코드HTTP의미 및 해결 방법
testmode.live_key_forbidden403운영 키로 /v1/testmode/*를 호출했습니다. 같은 조직의 tke_test_를 사용하세요.
testmode.invalid_scenario422빈 본문, 필드 없음 또는 released/installed/enabled/disabled 외 상태입니다.
testmode.not_test_item422order_item_id가 테스트 주문이 아닙니다. 운영 데이터에는 모의 적용이 불가능합니다.
testmode.no_sellable_package422조직에 가격이 설정된 요금제가 없습니다. 키는 생성되며 샘플 생성만 실패합니다.
partner.wrong_host403키와 호스트가 맞지 않습니다. 오류 응답에 표시된 호스트를 사용하세요.

전체 목록: 오류 코드 페이지 . 표준 /v1 인증 처리는 테스트 로직보다 먼저 실행됩니다.

테스트 웹훅: fire 및 fail-next

POST /v1/testmode/webhooks/fire로 실제 주문 없이 이벤트를 보냅니다. 본문: { "event_type": "order.completed", "data": {...} }. data 생략 시 샘플을 만듭니다.

POST /v1/testmode/webhooks/fail-next { "count": 1 }가 다음 N회에 503을 발생시킨 후 자동 해제됩니다. 실제 수신기를 중단할 필요가 없습니다.