Tổng Kho eSIM
テスト環境

テストモード

api-testing.tongkhoesim.comでパートナーtke_test_または会員tke_member_test_キーを使ってください。仮想残高と模擬eSIMは実際の資金、在庫、請求書から隔離されます。対応操作はキー所有者によって異なります。一括注文、Webhook、返金審査の制限は会員ガイドをご覧ください。

実資金を使う前に全体を試してください。 HMAC署名 で認証式を確認し、 テストコンソール でブラウザから直接リクエストを送れます。

会員向けOpenAPI

管理者が会員ごとにOpenAPIを許可します。メインサイドバーのAPIキーから本番またはテストを選び、キーを作成してください。シークレットは一度だけ表示されます。上限は両モード共通です。権限停止時は両方が停止しますが、キーの失効は可能です。

本番は会員の実際のVND残高を使い、与信はありません。テストは独立した仮想残高と模擬eSIMを使います。テスト画面で残高追加、サンプル作成、リセットができます。テスト注文は本番の購入履歴に表示されません。

会員の一括注文とWebhookは両モードで非対応です。審査する返金リクエストは本番のみです。テストeSIMをキャンセルして仮想残高への返金を試してください。テストは実際のプロバイダーを呼ばず、実際のMISA請求書も発行しません。非対応操作はcapability.not_supportedを返します。

会員向けAPIエンドポイント

キーで分ける2つのホスト

キーの種類に合うホストを使用してください。不一致は業務処理の前に拒否されます。

ホストベース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%で通知
Webhook本番のイベントテストイベント、手動送信とfail-next
元帳実際の会計元帳独立した仮想元帳。追記のみで削除せず、本番と混在しない
POST

/v1/testmode/seed

POST /v1/testmode/seedで試験用データを生成します。組織単位で冪等なため、再実行でも重複せずalready_seeded: trueを返します。

  • 十分な残高のテストウォレット
  • 組織向け価格の3プランで各eSIM1枚、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数、ウォレット、Webhook、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})をテストWebhookに即時送信
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 認証はテスト処理の前に適用されます。

テストWebhook:fireとfail-next

POST /v1/testmode/webhooks/fireは実注文なしでイベントを送ります。本文:{ "event_type": "order.completed", "data": {...} }。data省略時はサンプルを生成します。

POST /v1/testmode/webhooks/fail-next { "count": 1 }で次のN回を503にして自動解除します。受信側を停止せず試せます。