獲准且已由業務團隊啟用存取權限的合作夥伴可以使用API。在合作夥伴控制台建立唯讀或可下單金鑰。所有購買均使用美元預付錢包。
API快速入門
帳戶獲准後，業務團隊會分配價格並啟用API權限。請在合作夥伴控制台建立金鑰。唯讀金鑰不能下單，帳戶也必須啟用購買權限。
https://simvoro.com/api/partner/v1每個請求都應使用伺服器端Bearer金鑰。請勿將金鑰放入瀏覽器程式碼或URL。可在合作夥伴控制台撤銷金鑰。
Authorization: Bearer YOUR_API_KEY| 方法 | 端點 | 結果 |
|---|---|---|
| GET | /products?destination=japan | 分配給您的美元價格及產品ID。按目的地slug篩選，使用cursor分頁。 |
| GET | /balance | 錢包餘額、預留款項和可用美元。 |
| GET | /transactions | 錢包交易紀錄和nextCursor。 |
| GET | /orders | 合作夥伴訂單摘要及nextCursor（每頁50筆）。 |
| POST | /orders | 預留款項並訂購一張eSIM。需要具有下單權限的金鑰。 |
| GET | /orders/{orderId} | 訂單狀態、最近同步的數據用量，以及交付後的安裝資訊。 |
建立訂單
將UUID放入Idempotency-Key送出。逾時或連線失敗後，請重用相同UUID。送出客戶已確認的價格，並確認接收裝置支援eSIM且已解除電信業者鎖定。即時價格變動會回傳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已交付後扣款。重送請求也可能回傳已失敗的訂單。供應商結果不明確時，在核對原訂單期間會繼續預留款項。安裝資料屬於私人資訊，僅在確認交付後顯示。
金額為美元十進位字串。清單回傳items和nextCursor，請持續查詢直到nextCursor為null。限制為每個金鑰每分鐘120個請求，每位使用者每分鐘10次購買嘗試。收到429時請遵守Retry-After。常見錯誤：401金鑰無效、403無權限、402餘額不足、404訂單無法存取、409價格或冪等衝突、503服務無法使用。再次購買前請查詢原訂單。
申請內容應包含的資訊
- 你的平台和顧客族群
- 你預估的每月採購量
- 你想提供的目的地
- 你的系統需要執行的操作，例如訂購 eSIM，並向你的顧客顯示該 eSIM 的 QR 碼
成為合作夥伴
請提交申請，我們的團隊會就申請與你聯絡。