メインコンテンツまでスキップ
Version: 1.0.0

OmniSegment External API

顧客インポート、購入データインポート、ポイントインポートのための外部データ交換 API。

共通 API 仕様​

ベース URL​

OmniSegment API は異なる環境で利用可能で、以下のベース URL を使用します：

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

本ドキュメントでは、API エンドポイントのすべてのホスト名は変数 {API_HOST_NAME} で表されます。ご利用の環境に応じた適切なベース URL に置き換えてください。

認証​

API は複数の認証方式をサポートしています：

  • API キー認証：ほとんどの外部 API エンドポイントで必要
  • セッション認証：Web ベースのアプリケーション向け
  • 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（Too Many Requests） エラーコードを返す場合があります。アプリケーションには適切な指数バックオフによるリトライロジックを実装してください。

レスポンス形式​

すべての API レスポンスは、一貫した構造と適切な HTTP ステータスコードを持つ標準化された JSON 形式に従います。

成功レスポンス形式​

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

注意事項：

  • PAYLOAD キーの値には呼び出した API の結果が含まれます
  • 値は各 API 仕様によって異なります
  • HTTP ステータスコード：200

失敗レスポンス形式​

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

注意事項：

  • ERR_MSG キーの値にはエラーメッセージが含まれます
  • 値は各 API 仕様によって異なります
  • HTTP ステータスコード：400（Bad Request）、403（Forbidden）、500（Internal Server Error）

エラーレスポンスステータスコード一覧​

ゲートウェイおよびサービスエラー：

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

リトライポリシー： 上記のステータスコード（502、503、504）を受信した場合は、異なるステータスコードを受信するか、5 回リトライするまで 5 分ごとにリクエストを再試行してください。

Authentication​

X-OmniSegment-Api-Key ヘッダーを使用した API キー認証

Security Scheme Type:

apiKey

Header parameter name:

API Key Auth in Header