先保存業務訂單
生成唯一 client_order_id,先在資料庫保存數量、租期與接收地址,並建立唯一約束。本文是接入參考,不是客戶案例。
保存完整報價
GET /prices/quote 必須對應實際數量與租期。一起保存 quote_id、金額及 expires_at,金額使用整數 SUN 字串或精確數值類型。變更參數須重新報價。
簽名與請求一致
憑據只保留在伺服器。將 JSON 序列化一次,依規範對實際傳送位元組簽名。日誌隱藏密鑰和認證標頭。
同時保存冪等鍵
POST /orders 除 client_order_id 外,還要求 8–128 個可見 ASCII 字元的 Idempotency-Key。提交前保存鍵值及原始請求。重試不確定結果時保持兩者不變,重新生成時間戳、nonce 與簽名。先確認舊請求結果,再處理過期報價。Webhook 規則見公開 Skill,地址啟動沒有回呼,需查詢結果。
超時先查單
POST /orders 超時後,先以 GET /orders?client_order_id={client_order_id} 查詢。已有訂單繼續追蹤,適合重試時保留相同編號與參數,冪等衝突應排查。
受理與完成分開
保存平台訂單號與狀態,依据終態和交付證據更新本地紀錄,HTTP 成功不能視為已委託。失敗與待審核狀態保留給人員處理。
回呼驗簽與去重
按規範驗證 Webhook,依事件編號去重,可靠保存或處理後再回覆。容忍重複通知,狀態不一致時透過查單對帳。
限制重試並驗證異常
使用超時、指數退避及有限重試。記錄不含秘密的訂單狀態變化。上線前檢查餘額不足、過期報價、重複訂單、超時與錯誤簽名;實際傳輸格式以下方規範為準。
開發者接入資料
公開接口規範與伺服器端參考客戶端,無需登入即可閱讀;實際調用 API 仍需已開通的商戶帳戶。
https://api.tronow.io/openapi/v1
| HTTP | API |
|---|---|
GET | /prices/quote |
POST | /orders |
GET | /orders |
GET | /orders/{order_id} |
POST | /address-activations |
GET | /address-activations |
GET | /address-activations/{activation_id} |
GET | /account/balance |