테스트 모드
api-testing.tongkhoesim.com에서 파트너 tke_test_ 또는 회원 tke_member_test_ 키를 사용하세요. 가상 잔액과 모의 eSIM은 실제 자금, 재고, 청구서와 분리됩니다. 지원 작업은 키 소유자에 따라 다르며 대량 주문, 웹훅, 환불 심사 제한은 회원 안내를 확인하세요.
실제 자금 사용 전에 전체 흐름을 테스트하세요. 다음 참조: HMAC 서명 인증 공식 및 테스트 콘솔 브라우저에서 테스트 요청을 보내세요.
관리자가 회원별 OpenAPI 권한을 부여합니다. 기본 사이드바에서 API 키를 열고 실제 또는 테스트 모드를 선택해 키를 만드세요. 비밀 키는 한 번만 표시됩니다. 두 모드는 키 한도를 공유하며, 권한을 끄면 두 모드가 차단되지만 키 폐기는 가능합니다.
실제 모드는 회원의 실제 VND 지갑을 사용하며 신용 한도가 없습니다. 테스트는 별도 가상 지갑과 모의 eSIM을 사용합니다. 테스트 모드에서 가상 잔액과 샘플 데이터를 추가하거나 초기화할 수 있습니다. 테스트 주문은 실제 구매 내역에 표시되지 않습니다.
회원의 대량 주문과 웹훅은 두 모드 모두 지원되지 않습니다. 검토가 필요한 환불 요청은 실제 모드 전용입니다. 테스트 eSIM을 취소해 가상 지갑 환불을 시험하세요. 테스트는 실제 공급자를 호출하거나 실제 MISA 청구서를 발행하지 않습니다. 미지원 작업은 capability.not_supported를 반환합니다.
회원 API 엔드포인트키 유형별 두 호스트
키 유형에 맞는 호스트를 사용하세요. 잘못된 호스트는 업무 처리 전에 거부됩니다.
| 호스트 | 기본 URL | 허용 키 |
|---|---|---|
| 운영 | https://api.tongkhoesim.com/v1 | tke_live_ / tke_member_live_ |
| 테스트 | https://api-testing.tongkhoesim.com/v1 | tke_test_ / tke_member_test_ |
테스트 키로 운영 호스트 호출 또는 그 반대는 403 partner.wrong_host와 올바른 호스트를 반환합니다. 로그에 키를 노출하지 않습니다.
테스트 키 만들기
대시보드 테스트 모드에서 tke_test_를 만들고 한 번 표시되는 비밀 키를 보관하세요. 첫 키는 POST /v1/testmode/seed를 자동 실행합니다.
운영과 테스트의 7가지 차이
| 항목 | 운영 (api, tke_live_) | 테스트 (api-testing, tke_test_) |
|---|---|---|
| 호스트 | api.tongkhoesim.com | api-testing.tongkhoesim.com — 잘못된 호스트: 403 |
| 지갑 | 실제 조직 지갑 | 가상 지갑, 대시보드 또는 관리자 조정으로 무제한 충전 |
| 재고 | 실제 esim_profiles | 가상 재고, 모의 eSIM 무제한 생성 |
| 발급 | 실제 통신사 | 동일 입력에 동일 모의 ICCID/LPA 생성 (LPA:1$testmode-smdp.tongkhoesim.com$…) |
| 사용량 | 실제 통신사 측정 | 자동 증가, 75/90% 알림 |
| 웹훅 | 실제 운영 이벤트 | 테스트 이벤트, 수동 전송 및 fail-next |
| 원장 | 실제 재무 원장 | 격리된 가상 원장, 추가 전용이며 삭제하거나 운영 원장과 혼합하지 않음 |
/v1/testmode/seed
POST /v1/testmode/seed가 즉시 사용할 샘플을 생성합니다. 조직별 멱등 처리로 재호출 시 중복 없이 already_seeded: true를 반환합니다.
- 충분한 잔액의 테스트 지갑
- 조직 가격의 실제 요금제 3종으로 각 eSIM 1개인 주문 3개
- 3가지 상태: 미설치 · 사용량 40% · 만료
#!/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"{
"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 | 발생 시점 | ref_id 의미 |
|---|---|---|
open_api | 테스트 키의 /v1 호출: 주문, 충전, 취소 또는 시뮬레이션 | 호출 키의 api_keys.id |
simulate | 구성원 또는 대리 관리자가 대시보드에서 시뮬레이션 | 구성원 또는 관리자 ID |
seed | /v1/testmode/seed로 생성한 데이터 | 비어 있음 |
/v1/testmode/esims/{id}/simulate
test-mode-onlyPOST /v1/testmode/esims/{order_item_id}/simulate로 사용량, 상태, 만료, 속도를 설정하거나 다음 충전/취소를 1회 거부시킵니다.
#!/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.{
"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_forbidden | 403 | 운영 키로 /v1/testmode/*를 호출했습니다. 같은 조직의 tke_test_를 사용하세요. |
testmode.invalid_scenario | 422 | 빈 본문, 필드 없음 또는 released/installed/enabled/disabled 외 상태입니다. |
testmode.not_test_item | 422 | order_item_id가 테스트 주문이 아닙니다. 운영 데이터에는 모의 적용이 불가능합니다. |
testmode.no_sellable_package | 422 | 조직에 가격이 설정된 요금제가 없습니다. 키는 생성되며 샘플 생성만 실패합니다. |
partner.wrong_host | 403 | 키와 호스트가 맞지 않습니다. 오류 응답에 표시된 호스트를 사용하세요. |
전체 목록: 오류 코드 페이지 . 표준 /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을 발생시킨 후 자동 해제됩니다. 실제 수신기를 중단할 필요가 없습니다.