跳至主要内容
Version: 1.0.0

OmniSegment External API

用於顧客匯入、購買資料匯入及點金券匯入的外部資料交換 API。

通用 API 規格​

基礎網址​

OmniSegment API 適用於不同環境，基礎網址如下：

  • Taiwan Production: https://api.omnisegment.com
  • Japan Production: https://jp.api.omnisegment.com
  • Staging Environment: https://staging.omnicloud.tech

在本文件中，API 端點中的所有主機名稱均以變數 {API_HOST_NAME} 表示，請依您的環境替換為對應的基礎網址。

驗證​

API 支援多種驗證方式：

  • API 金鑰驗證：大多數外部 API 端點必須使用
  • Session 驗證：適用於網頁應用程式
  • Basic 驗證：適用於舊系統整合

速率限制​

為確保系統穩定性，API 請求受到速率限制。以下端點適用速率限制：

  • /api/v1/interaction-report/
  • /api/v1/tracking-event-report/
  • /api/v1/products/import-event-registration-data/
  • /api/v1/products/import-product-guarantee-data/
  • /api/v1/products/import/
  • /api/import-gift-voucher/
  • /omnidata/show-market-report/
  • /api/import-purchase-data/
  • /ma_audience/import-audience/
  • /api/v1/beacon/track-event/

若超過允許的速率限制，API 可能回傳 429（請求次數過多） 錯誤碼。請在應用程式中實作適當的指數退避重試機制。

回應格式​

所有 API 回應均遵循標準化的 JSON 格式，具有一致的結構與適當的 HTTP 狀態碼。

成功回應格式​

{
  "SUCCESS": true,
  "PAYLOAD": "xxxxxx"
}

注意事項：

  • PAYLOAD 鍵的值為所呼叫 API 的結果
  • 值的內容依各 API 規格而定
  • HTTP 狀態碼：200

失敗回應格式​

{
  "SUCCESS": false,
  "ERR_MSG": "xxxxxx"
}

注意事項：

  • ERR_MSG 鍵的值為錯誤訊息
  • 值的內容依各 API 規格而定
  • HTTP 狀態碼：400（錯誤請求）、403（禁止存取）、500（伺服器內部錯誤）

錯誤回應狀態碼說明​

閘道器與服務錯誤：

  • 502 Bad Gateway
  • 503 Service Unavailable
  • 504 Gateway Timeout

重試策略： 若收到上述任一狀態碼（502、503、504），請每五分鐘重試一次，直到收到不同的狀態碼或已重試五次為止。

Authentication​

使用 X-OmniSegment-Api-Key 標頭的 API 金鑰驗證

Security Scheme Type:

apiKey

Header parameter name:

API Key Auth in Header