接碼 API 接入流程：報價、取號、查詢短信與取消退款

如果需要在自己的系統裡批量取號、自動讀取驗證碼，可以使用接碼 API。本文按實際調用順序整理流程，接口細節以 API 檔案 為準。

開通條件和鑑權

• 開發者業務接口需要帳戶累計核實的實付充值滿 1000 USDT 後開通；網頁手動操作不受這個限制。
• 請求頭攜帶 X-API-Key，不支援 Bearer；不要把密鑰寫進網址或前端代碼，建議放在服務端環境變量裡。
• POST 請求使用表單格式（application/x-www-form-urlencoded），不是 JSON。
• 返回裡 code=1 才是成功，HTTP 200 不等於業務成功。

呼叫順序

1. 讀取目錄：調用國家、服務列表和某個國家的價格接口，拿到可用的 country_id、application_id、價格和參考庫存。目錄來自數據庫快照，可以本地緩存，不必每次取號都請求。
2. 獲取報價：用 country_id 和 application_id 請求報價，返回 quote_id、金額和有效期。報價約 120 秒內有效，只綁定當前帳戶，本身不扣費。
3. 按報價取號：提交 quote_id 和一個新的冪等鍵（16–64 位字母、數字、下劃線或短橫線）。這一步會預扣餘額並返回訂單和號碼。
4. 查詢短信：按訂單號輪詢訂單狀態，收到短信後狀態和內容會出現在訂單裡。輪詢頻率要控制，過快會返回 429。
5. 取消：沒有收到短信時調用取消接口。只有供應商確認取消成功後才退回餘額，所以取消後要再查一次訂單確認狀態。

為什麼要用冪等鍵

網絡超時時，你不知道取號請求是否已經成功。用同一個冪等鍵重試，系統不會重復創建訂單；如果每次都生成新的鍵，就可能重復扣費。原則是：一次新的取號用一個新鍵，同一次取號的重試用同一個鍵。

常見錯誤怎麼處理

目前不支持的功能

主動傳送簡訊、拉黑號碼、自動續租、自動 eSIM 交付和回調通知暫未接入，需要用輪詢方式獲取結果。

常見問題

網頁上的餘額和 API 共用嗎？

共用同一個帳戶餘額，扣費和退款規則一致。

可以用 API 租號嗎？

可以查詢租賃方案和創建租賃訂單，具體參數見 API 檔案。租賃訂單付款後按後台流程交付。

價格多久更新？

價格來自數據庫快照，按批次同步，取號時以報價接口返回的金額為準。