跳至主要内容

API 使用說明及限制

開始串接前，請先確認共同的請求格式、權限、查詢與更新規則。

請求格式​

  • 所有請求皆使用 HTTPS。
  • JSON request body 應使用 Content-Type: application/json。
  • 日期採 YYYY-MM-DD，例如 2026/08/08 應寫成 2026-08-08；日期時間採 API Reference 指定的 ISO-8601 格式，例如同日台北時間上午 9:30 應寫成 2026-08-08T09:30:00+08:00。
  • 請求必須依驗證與簽章規則帶入三個認證標頭。

權限範圍​

Service Account 只能存取 FREONE 實際授權的資源。取得憑證後，請以 GET /v1/merchants 與 GET /v1/squads 確認可存取的商家與組別；若 API 回傳 403，請先檢查目標資源是否在這份清單中。名詞說明請參考基礎名詞。

查詢與更新原則​

  • 查詢時同時帶入多個精確條件，API 只會回傳「每個條件都符合」的資料。例如同時指定 merchantId 與 phone，結果必須同時屬於該商家且電話相符。
  • 不要假設 PUT 只會修改本次送出的欄位。組員 profile 與 squads 更新會以本次送出的完整內容取代現有資料；管理員範圍更新則使用 oldRole 與 newRole 表示要移除或新增的項目。其他 PUT 請以各端點的 API Reference 為準。
  • 班表的日期以商家當地時區為準，不是以伺服器或使用者電腦的時區為準。例如查詢 2026-08-08，指的是該商家當地的 8 月 8 日；請使用商家資料中的 timezone 進行時間轉換。
  • Sandbox 與 Production 的資料和憑證彼此獨立。

錯誤處理​

收到錯誤回應時，請先查看 HTTP 狀態碼與回應中的 code，以判斷是憑證、權限、請求內容或 FREONE 服務問題。日誌可記錄 request path、發生時間與 code，但不要記錄 API Secret 或完整認證標頭。

處理錯誤時會用到的主要欄位如下：

{
  "code": "error-code",
  "message": "Error description"
}

目前公開規格未定義統一的請求配額。若預期有大量或批次流量，請先寄信至 support@freone.com 確認整合方式。