API連携

APIクイックスタート

アカウント承認後、営業担当が価格を設定しAPIアクセスを有効にします。パートナーダッシュボードでキーを作成してください。読み取り専用キーでは注文できません。アカウントの購入権限も必要です。

すべてのリクエストでサーバー側のBearerキーを送信してください。ブラウザーのコードやURLにキーを含めないでください。キーはパートナーダッシュボードで取り消せます。

注文を作成

Idempotency-KeyにUUIDを送信してください。タイムアウトや接続障害の後も同じUUIDを再利用します。顧客が確認した価格を送信し、受取端末がeSIM対応かつSIMロック解除済みであることを確認してください。実際の価格が変わると409 PRICE_CHANGEDが返ります。本番APIのため、受け付けた購入には実際のウォレット資金を使用します。

POST /api/partner/v1/orders
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Idempotency-Key: 83c77d9f-395f-4ff0-8ed6-c461bda46559

{"productId":"PRODUCT_ID_FROM_CATALOG","expectedPrice":"2.25","deviceConfirmed":true}

201レスポンスにはorderIdとesimが含まれます。esim.statusとesim.failureを確認してください。注文は10秒間隔で確認します。資金は先に確保され、eSIMの受け渡し確認後に引き落とされます。再送時に失敗済み注文が返る場合もあります。仕入先の結果が不明な場合、元の注文を照合する間は資金を確保したままにします。インストール情報は非公開で、受け渡し確認後にのみ表示されます。

金額はUSDの小数文字列です。一覧はitemsとnextCursorを返し、nextCursorがnullになるまで取得します。制限はキーごとに毎分120リクエスト、ユーザーごとに毎分10回の購入試行です。429ではRetry-Afterに従ってください。主なエラーは401キー無効、403権限なし、402残高不足、404注文にアクセス不可、409価格または重複防止キーの競合、503サービス利用不可です。再購入の前に元の注文を確認してください。