テストモード
api-testing.tongkhoesim.comでパートナーtke_test_または会員tke_member_test_キーを使ってください。仮想残高と模擬eSIMは実際の資金、在庫、請求書から隔離されます。対応操作はキー所有者によって異なります。一括注文、Webhook、返金審査の制限は会員ガイドをご覧ください。
実資金を使う前に全体を試してください。 HMAC署名 で認証式を確認し、 テストコンソール でブラウザから直接リクエストを送れます。
管理者が会員ごとにOpenAPIを許可します。メインサイドバーのAPIキーから本番またはテストを選び、キーを作成してください。シークレットは一度だけ表示されます。上限は両モード共通です。権限停止時は両方が停止しますが、キーの失効は可能です。
本番は会員の実際のVND残高を使い、与信はありません。テストは独立した仮想残高と模擬eSIMを使います。テスト画面で残高追加、サンプル作成、リセットができます。テスト注文は本番の購入履歴に表示されません。
会員の一括注文とWebhookは両モードで非対応です。審査する返金リクエストは本番のみです。テストeSIMをキャンセルして仮想残高への返金を試してください。テストは実際のプロバイダーを呼ばず、実際のMISA請求書も発行しません。非対応操作はcapability.not_supportedを返します。
会員向けAPIエンドポイントキーで分ける2つのホスト
キーの種類に合うホストを使用してください。不一致は業務処理の前に拒否されます。
| ホスト | ベース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%で通知 |
| Webhook | 本番のイベント | テストイベント、手動送信とfail-next |
| 元帳 | 実際の会計元帳 | 独立した仮想元帳。追記のみで削除せず、本番と混在しない |
/v1/testmode/seed
POST /v1/testmode/seedで試験用データを生成します。組織単位で冪等なため、再実行でも重複せずalready_seeded: trueを返します。
- 十分な残高のテストウォレット
- 組織向け価格の3プランで各eSIM1枚、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数、ウォレット、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 | 発生条件 | 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 認証はテスト処理の前に適用されます。
テスト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にして自動解除します。受信側を停止せず試せます。