CitrusAdの仕組み

CitrusAd APIはRESTを中心に構成されています。APIには、予測可能でリソース指向のURLがあり、HTTPレスポンスコードを使用してAPIエラーを表示します。また、HTTP認証やHTTP動詞など、一般的なHTTPクライアントが理解できる組み込みHTTP機能を使用しています。

CitrusAd APIへの認証は、APIキーを使用して管理されます。APIキーは、お客様のバックエンドとCitrusAd APIとの通信で使用されます。

CitrusAd APIは、広告の生成に使用される、商品、カタログ、顧客、注文に関するデータのアップロードに対応しています。また、CitrusAd APIを使用することで、広告をリクエストしたり、それらの広告とのやり取りをレポートしたりすることができます。

CitrusAdエンドポイント

CitrusAdは各種のエンドポイントを使用してデータを同期し、広告を生成します。以下がその概要です。

エンドポイント	使用方法	説明
`catalogs`	APIを介したカタログの同期	API経由でカタログを作成するときに使用します。単一カタログの名前空間の場合、これはテクニカルアカウントマネージャーが構成します。
`catalog-products`	APIを介した商品の同期	カタログ内の商品データを作成および更新するときに使用します。
`customers`	APIを介した顧客データの同期	カタログ内の顧客データを作成および更新するときに使用します。
`orders`	APIを介した注文データの同期	CitrusAdに注文データを送信するときに使用します。
`/resource/`	インプレッションとクリックをレポートする APIを介した注文データの同期	クリックとインプレッションのレポート、およびフロントエンドを介したレポートの場合は注文のレポートに使用します。
`/ads/generate`	広告を生成する	商品広告やバナー広告を生成するときに使用します。
`/ads/bannerx`	広告を生成する	バナーX広告を生成するときに使用します。

📘
カタログ、商品、顧客、注文の同期にエンドポイントを使用する必要はありません。CitrusAdでは、ファイルを介したデータの同期をサポートしています。こちらの方がお客様の要件に適しているものと考えられます。

データペイロードはJSON形式です。先ほどの Content-Type （これらのエンドポイントに対するもの）は application/jsonです。これは、以下のようにリクエストのヘッダーとして渡す必要があります。

-H "Content-Type: application/json" \

すべての統合リソースは、以下のようにAPIキーと合わせてヘッダーとして渡す必要のある基本的な認証を使用しています。

-H "Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8" \

APIキーは、小売業者チームの「Integration Settings（統合設定）」セクションで確認できます。必要なのはシークレットAPIキーのみです。

CitrusAdの広告生成エンドポイントは、さらにOAuth2.0と互換性があります。詳しくはOAuth 2.0認証をご覧ください。

CitrusAdでは、ステージング環境と本番環境で異なるベースURLを使用しています。

📘
ステージング用のベースURLを受け取るには、CitrusAdにご連絡ください。統合が始まり次第、本番用のベースURLをお知らせします。