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