Tổng Kho eSIM
직접 연동

직접 연동

공식 패키지 설치 없이 서명 예제, 실행 파일, 테스트 컬렉션으로 응답을 먼저 확인할 수 있습니다.

회원을 위한 OpenAPI

조직이나 베트남 법인 프로필을 만들지 않고 회원 계정으로 직접 연동하세요.

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

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

회원 전용 요금제 가격은 최종 가격이며 등급 할인이 추가 적용되지 않습니다. 전용 가격이 없으면 현재 정가와 등급 할인이 적용됩니다. 서버가 주문 시 가격을 확정합니다.

청구서는 회원 흐름을 따르며 기본값은 소비자 판매입니다. 주문 생성 시 현재 검증 규칙을 충족하는 개인 정보를 invoice_buyer로 보낼 수 있습니다. OpenAPI 이용에 베트남 법인 프로필은 필요하지 않습니다.

인증과 중복 거래 방지

실제: https://api.tongkhoesim.com 및 tke_member_live_. 테스트: https://api-testing.tongkhoesim.com 및 tke_member_test_. 둘 다 HMAC-SHA256과 X-TKE-Key, X-TKE-Timestamp, X-TKE-Nonce, X-TKE-Signature를 사용합니다. 정확한 메서드, 경로/쿼리, 원문 본문 해시에 서명하고 비밀 키를 브라우저 코드에 넣지 마세요.

주문 생성, 요금제 변경, 취소, 환불 요청 POST에는 Idempotency-Key가 필요합니다. 같은 의도를 재시도할 때 키와 본문을 유지하세요. 중복 방지는 API 키별로 적용되므로 대기 중인 거래를 재시도할 때 API 키를 바꾸지 마세요. 회원 테스트 샘플 생성과 초기화에도 Idempotency-Key가 필요하며 reset에는 {reason} 본문이 필요합니다.

include에 lpa를 넣어 설치 코드를 요청하면 실제 코드가 반환될 때 일반 취소 기간이 닫힙니다. qr는 lpa와 함께 QR 이미지만 추가하며 목록 엔드포인트에서는 무시됩니다. 전달할 준비가 되었을 때만 코드를 요청하고 아직 공개하지 않으려면 include를 생략하세요. 환불 요청은 여전히 업무 조건을 따라야 하며 코드 공개 후 자유롭게 취소하는 방법이 아닙니다.

회원 API 엔드포인트

API 경로: GET /v1/catalog/packages
필요한 권한: catalog:read
API 경로: GET /v1/catalog/packages/{code}
필요한 권한: catalog:read
API 경로: GET /v1/orders
필요한 권한: orders:read
API 경로: POST /v1/orders
필요한 권한: orders:write
API 경로: GET /v1/orders/{id}
필요한 권한: orders:read
API 경로: POST /v1/orders/{id}/resend
필요한 권한: orders:write
API 경로: GET /v1/esims
필요한 권한: esims:read
API 경로: GET /v1/esims/{id}
필요한 권한: esims:read
API 경로: GET /v1/esims/{id}/usage
필요한 권한: esims:read
API 경로: GET /v1/esims/{id}/plan-options
필요한 권한: esims:read
API 경로: POST /v1/esims/{id}/change-plan
필요한 권한: esims:write
API 경로: POST /v1/esims/{id}/cancel
필요한 권한: esims:write
API 경로: GET /v1/esims/{id}/refund-requests
필요한 권한: esims:read
API 경로: POST /v1/esims/{id}/refund-requests
필요한 권한: esims:write
API 경로: GET /v1/wallet/balance
필요한 권한: wallet:read

테스트 모드

GET /v1/testmode/status
esims:read
POST /v1/testmode/seed
orders:write
POST /v1/testmode/reset
orders:write
POST /v1/testmode/esims/{id}/simulate
esims:write

콘솔은 api-testing에서 파트너 tke_test_ 및 회원 tke_member_test_ 테스트 키만 허용합니다. 모든 실제 키는 차단됩니다. 비밀 키는 페이지 메모리에만 있으며 저장소나 로그에 저장되지 않습니다.

요청 서명

HMAC 페이지에 공식, bash/Node/Python/PHP/Go 예제 및 백엔드 테스트 벡터가 있습니다.

bash
#!/usr/bin/env bash
# Yeu cau: openssl. Ky POST /v1/orders.
KEY_ID="tke_test_ab12cd34..."
SECRET="tke_secret_test_0123456789abcdef"
METHOD="POST"
PATH_Q="/v1/orders"
BODY='{"items":[{"package_code":"THAY-BANG-MA-GOI-CUA-BAN","quantity":2}]}'
TS="$(date +%s000)"                 # epoch milliseconds
NONCE="$(uuidgen)"

BODY_HASH="$(printf '%s' "$BODY" | openssl dgst -sha256 -hex | awk '{print $NF}')"
SIGNING="$METHOD"$'
'"$PATH_Q"$'
'"$TS"$'
'"$NONCE"$'
'"$BODY_HASH"
SIG="$(printf '%s' "$SIGNING" | openssl dgst -sha256 -hmac "$SECRET" -hex | awk '{print $NF}')"

curl -sS "https://api.tongkhoesim.com$PATH_Q"   -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"

실행 가능한 예제

examples/sign.mjs와 examples/sign.py는 표준 런타임만으로 실행됩니다. /hmac-test-vectors.json을 읽어 서명을 계산하고 PASS/FAIL을 출력합니다.

bash
node examples/sign.mjs      # plain Node (node:crypto), nothing to install
python examples/sign.py     # plain Python (hmac/hashlib), nothing to install

즉시 실행 컬렉션

Postman 및 .http는 빌드 시 openapi.json에서 생성됩니다. 각 엔드포인트의 요청에 서명 헤더 4개가 준비되어 있으므로 키 입력 후 서명하세요.

Postman 컬렉션 다운로드 tongkhoesim.http 다운로드
.http 컬렉션 사용
  1. VS Code REST Client 확장 또는 JetBrains HTTP Client에서 tongkhoesim.http를 여세요.
  2. @key_id 및 @secret에 tke_test_ 정보를 입력하세요. @base_url은 api-testing.tongkhoesim.com입니다.
  3. HMAC 예제나 examples/sign.*로 timestamp/nonce/signature를 계산해 변수에 넣으세요.
  4. 편집기에서 바로 요청을 보내세요. Postman이나 추가 코드는 필요 없습니다.

SDK가 필요하신가요?

명세와 일치하도록 openapi-generator로 openapi.json에서 클라이언트를 생성하세요.

bash
npx @openapitools/openapi-generator-cli generate \
  -i https://docs.tongkhoesim.com/openapi.json \
  -g typescript-fetch \
  -o ./tke-sdk