Open APIドキュメント
Open APIはパートナーと管理者に許可された会員が利用できます。/v1を呼び出してカタログの参照、注文の作成・参照、eSIMプロフィール（ICCID + LPAインストールコード）の取得、使用量の確認、RESTの定期ポーリングによる照合を行います。支払いはキー所有者である組織または会員のウォレットから引き落とされます。Webhookは組織向けです。会員の価格と請求書は、連携ガイドの会員向けOpenAPIの手順に従います。
APIの全体像
30件の操作
6グループ：カタログ · 注文 · eSIM · ウォレット · Webhook · テストモード。
統一された認証
GETも含めて4個のX-TKE-*ヘッダーでHMAC-SHA256署名を行います。署名の省略はできません。
共通レスポンス形式
{ ok, data }または{ ok, error }と適切なHTTPステータスを返します。エラーに200は使用しません。
91件の公開エラーコード
各コードにバックエンドのレジストリに基づくHTTPステータスと再試行可否があります。
8種類のWebhookイベント
POST /v1/webhooksで設定します。専用シークレットで署名し、少なくとも1回配信します。履歴から再送できます。
専用ホストのテストモード
api-testing.tongkhoesim.comはtke_test_専用です。仮想ウォレット・在庫、再現可能な発行、使用量の自動増加を試した後、本番ホストとtke_live_に切り替えます。
text
https://api.tongkhoesim.com/v1 # 本番
https://api-testing.tongkhoesim.com/v1 # テストモード本番：api.tongkhoesim.com / tke_live_（パートナー）またはtke_member_live_（許可された会員）。テスト：api-testing.tongkhoesim.com / tke_test_ / tke_member_test_（パートナー／会員）。
4ステップで導入
1. テストキーを作成
テストモードでtke_test_キーを作成し、一度だけ表示されるシークレットを保存します。最初のキーで3つの状態のサンプル注文を生成します。テストウォレットは何度でも入金できます。
2. テストホストで注文
HMAC署名してPOST https://api-testing.tongkhoesim.com/v1/ordersを呼びます。ICCIDが8999で始まる模擬eSIMを即時発行し、実在庫や資金は使いません。コンソールやPostmanで試せます。
3. Webhookを登録して試す
POST /v1/webhooksでURLを登録し、CHECK_HEALTHに2xxを返します。/v1/testmode/webhooks/fireでイベントを送り、/fail-nextで再試行を確認できます。
4. 本番キーに切り替え
コードはそのままで本番ホスト、tke_live_のkey_idとsecretに切り替えます。Webhookはapi_key_idごとに独立しているため、本番キー用にも登録します。
重要な注意点3つ
次の3点はテストを通過しても、実際の支払いや照合で問題が生じることがあります。
Idempotency-KeyはAPIキーごとに有効
重複排除はapi_key_id単位です。同じ組織でも異なるキーで同じIdempotency-Keyを送ると、注文と引き落としが2回発生します。注文フローごとにキーを固定するかkey_idを含めてください。
RESTのidとWebhookのorder_item_id
RESTのeSIMのidとWebhookのorder_item_idは同じUUIDです。order_idは親注文です。ICCIDは再利用されるためUUIDで管理してください。GET /v1/esims?iccid=…でidを取得できます。注文時にexternal_refを送るとRESTとeSIMのWebhookがorder_idと共に返し、?external_ref=…で関連eSIMを検索できます。
カーソルのループを正しく終了
GET /v1/ordersと/v1/esimsはカーソル方式です。無効なカーソルはエラーにならず先頭に戻ります。next_cursorがないか現在と同じなら終了してください。!== nullだけの判定では無限ループになります。