バックエンドを介した注文データの同期（推奨）
注文データをCitrusAdに送信するには、以下のようなコマンドを使用します。なお、以下の orders フィールドのデータはダミーで、説明の例として示しています。ここで示しているのはすべて標準的な統合の例です。
マーケットプレイス出品者IDを統合していますか？
以下の「マーケットプレイス出品者ID」セクションを必ずお読みください。
単品の注文
以下は、1つの商品を購入した顧客のコンテキストです。
POST $BASE_URL/v1/orders HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
"orders": [
{
"customerId": "npc-s243-ir",
"catalogId": "6adb93d0-7he4-4d4e-9b47-e5d3714c976a",
"sessionId": "5cat7-9964-4f",
"orderDate": "2021-12-02T15:00:00Z",
"id": "3h30e938-c158-4d78-a0af-b48bbwfrcss4",
"orderItems": [
{
"gtin": "9891998566P",
"quantity": 3,
"regularUnitPrice": "1.00",
"totalOrderItemPriceAfterDiscounts": "3.00"
}
]
}
]
}
成功すると、以下のオブジェクトが返されます。
HTTP/2 200
{
"orders": [
{
"adIds": null,
"teamId": "a7e5cat7-9964-4ff3-bbb1-94bf9b53a366",
"customerId": "npc-s243-ir",
"catalogId": "6adb93d0-7he4-4d4e-9b47-e5d3714c976a",
"sessionId": "5cat7-9964-4f",
"id": "3h30e938-c158-4d78-a0af-b48bbwfrcss4",
"orderItems": [
{
"regularUnitPrice": 1.00,
"citrusDiscountAmount": null,
"gtin": "9891998566P",
"adId": "",
"quantity": 3,
"substitutedFor": null,
"totalOrderItemPriceAfterDiscounts": 3.00
}
],
"orderDate": "2021-12-02T15:00:00Z",
}
]
}
orderDateの形式
上記の形式のorderDateはUTC時間として読み取られるため、UTCで同期する必要があります。
また、タイムゾーンのオフセットを設定することもできます。その場合は、
Z代替として+HH:MM対象のタイムゾーンに応じて例：「注文日」:“2021-12-02T15:00:00+10:00"タイムゾーンはUTC+10で指定します。
複数品の注文
以下は、複数の商品を購入した顧客のコンテキストです。 orderItems 配列には複数の商品があります。
POST $BASE_URL/v1/orders HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
"orders": [
{
"customerId": "npc-s243-ir",
"catalogId": "6adb93d0-7he4-4d4e-9b47-e5d3714c976a",
"sessionId": "5cat7-9964-4f",
"orderDate": "2021-12-02T15:00:00Z",
"id": "abcti84ew-c158-4d78-a0af-b48bbwfrcss4",
"orderItems": [
{
"gtin": "9891998566P",
"quantity": 3,
"regularUnitPrice": "1.00",
"totalOrderItemPriceAfterDiscounts": "3.00"
}
]
},
{
"gtin": "351998532P",
"quantity": 1,
"regularUnitPrice": "2.50",
"totalOrderItemPriceAfterDiscounts": "2.50"
}
]
}
]
}
成功すると、以下のオブジェクトが返されます。
HTTP/2 200
{
"orders": [
{
"adIds": null,
"teamId": "a7e5cat7-9964-4ff3-bbb1-94bf9b53a366",
"customerId": "npc-s243-ir",
"catalogId": "6adb93d0-7he4-4d4e-9b47-e5d3714c976a",
"sessionId": "5cat7-9964-4f",
"id": "3h30e938-c158-4d78-a0af-b48bbwfrcss4",
"orderItems": [
{
"regularUnitPrice": 1.00,
"citrusDiscountAmount": null,
"gtin": "9891998566P",
"adId": "",
"quantity": 3,
"substitutedFor": null,
"totalOrderItemPriceAfterDiscounts": 3.00
},
{
"regularUnitPrice": 2.50,
"citrusDiscountAmount": null,
"gtin": "351998532P",
"adId": "",
"quantity": 1,
"substitutedFor": null,
"totalOrderItemPriceAfterDiscounts": 2.50
}
],
"orderDate": "2021-12-02T15:00:00Z",
}
]
}
複数注文の同期
複数の注文を同期させる場合、各リクエストで最大100個のアイテムを一括で送信できます。リクエストの回数に上限はありません。プッシュされたペイロードの順序は、返された結果と同じ順序です。これにより、バックエンドの注文表現とのデータの整合性を維持できます。
POST $BASE_URL/v1/orders HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
"orders": [
{
"customerId": "npc-s243-ir",
"catalogId": "6adb93d0-7he4-4d4e-9b47-e5d3714c976a",
"sessionId": "5cat7-9964-4f",
"orderDate": "2021-12-02T15:00:00Z",
"id": "3h30e938-c158-4d78-a0af-b48bbwfrcss4",
"orderItems": [
{
"gtin": "9891998566P",
"quantity": 3,
"regularUnitPrice": "1.00",
"totalOrderItemPriceAfterDiscounts": "3.00"
}
]
},
{
"customerId": "rw3-v3ag-ol0",
"sessionId": "2m342-2dfe-0f",
"orderDate": "2021-12-02T15:00:00Z",
"id": "i32dm3e4-c158-43d78-43ww32x-m2ide3e3",
"orderItems": [
{
"gtin": "5431998566P",
"quantity": 2,
"regularUnitPrice": "2.00",
"totalOrderItemPriceAfterDiscounts": "4.00"
}
]
}
]
}
成功すると、以下のオブジェクトが返されます。
HTTP/2 200
{
"orders": [
{
"adIds": null,
"teamId": "8616fcd8-5821-4465-9609-401d93fdc800",
"customerId": "npc-s243-ir",
"catalogId": "6adb93d0-7he4-4d4e-9b47-e5d3714c976a",
"sessionId": "5cat7-9964-4f",
"id": "3h30e938-c158-4d78-a0af-b48bbwfrcss4",
"orderItems": [
{
"regularUnitPrice": 1.00,
"citrusDiscountAmount": null,
"gtin": "9891998566P",
"adId": "",
"quantity": 3,
"substitutedFor": null,
"totalOrderItemPriceAfterDiscounts": 3.00
}
],
"orderDate": "2021-12-02T15:00:00Z"
},
{
"adIds": null,
"teamId": "8616fcd8-5821-4465-9609-401d93fdc800",
"customerId": "rw3-v3ag-ol0",
"sessionId": "2m342-2dfe-0f",
"id": "i32dm3e4-c158-43d78-43ww32x-m2ide3e3",
"orderItems": [
{
"regularUnitPrice": 2.00,
"citrusDiscountAmount": null,
"gtin": "5431998566P",
"adId": "",
"quantity": 2,
"substitutedFor": null,
"totalOrderItemPriceAfterDiscounts": 4.00
}
],
"orderDate": "2021-12-02T15:00:00Z"
}
]
}
マーケットプレイス出品者ID
マーケットプレイス出品者をオンボーディングしている場合は、注文の報告時に sellerId を同期する必要があります（該当するものがある場合）。購入した商品に sellerIdがない場合は、省略することができます。
マーケットプレイス出品者をオンボーディングしている場合は、注文レポートでSellerIdを指定する必要はありません
以下は、1つの商品がマーケットプレイス出品者からの商品で、もう1つがマーケットプレイスの商品ではない場合の注文の例です。
POST $BASE_URL/v1/orders HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
"orders": [
{
"customerId": "npc-s243-ir",
"catalogId": "6adb93d0-7he4-4d4e-9b47-e5d3714c976a",
"sessionId": "5cat7-9964-4f",
"orderDate": "2021-12-02T15:00:00Z",
"id": "abcti84ew-c158-4d78-a0af-b48bbwfrcss4",
"orderItems": [
{
"gtin": "9891998566P",
"quantity": 3,
"regularUnitPrice": "1.00",
"totalOrderItemPriceAfterDiscounts": "3.00",
"sellerId": "10sa-3s33-j8e3"
}
]
},
{
"gtin": "351998532P",
"quantity": 1,
"regularUnitPrice": "2.50",
"totalOrderItemPriceAfterDiscounts": "2.50"
}
]
}
]
}
フロントエンドを介した注文データの同期（非推奨）
バックエンドを介した注文データの同期ができない場合は、CitrusAdが対応している以下のオープンAPIをお試しください。これは、バックエンドの統合やファイルの同期機能が使えない場合にのみ使用することをお勧めします。
フロントエンドからのデータの報告は、標準的なバックエンドとの統合よりもリスクが高くなります。
インテグレータは、報告用ドメインが現在アドブロッカーによってブロックされていないものの、将来的にブロックされる可能性があることを認識しておく必要があります。その場合、失われたデータについてCitrusAdは責任を負いません。
オープンAPI仕様：
openapi: 3.0.1
info:
title: Citrus
version: 1.0.0
paths:
/v1/resource/third-o:
get:
tags:
- resource
summary: Report an order.
operationId: resource-third-o
parameters:
- in: query
name: key
description: |
(Publishable) API key.
schema:
type: string
required: true
- in: query
name: teaid
description: |
Team id.
schema:
type: string
required: false
- in: query
name: catid
description: |
Catalog id.
schema:
type: string
required: true
- in: query
name: ordid
description: |
Order id.
schema:
type: string
required: true
- in: query
name: ordts
description: |
Order timestamp as a string in RFC3339.
schema:
type: string
required: true
- in: query
name: sesid
description: |
Session id.
schema:
type: string
required: true
- in: query
name: cusid
description: |
Customer id.
schema:
type: string
- in: query
name: procods
description: |
Product codes. Related by index to pris and quas. The length must match pris and quas.
schema:
type: array
items:
type: string
examples:
uat:
value: [ "procods=7913494","procods=6815686" ]
summary: "product code list"
required: true
- in: query
name: pris
description: |
Prices as strings. Related by index to itsids and quas. The length must match pris and quas.
schema:
type: array
items:
type: string
examples:
uat:
value: [ "pris=7913494","pris=6815686" ]
summary: "prices list"
required: true
- in: query
name: quas
description: |
Quantities as strings. Related by index to itsids and pris. The length must match itsids and pris.
schema:
type: array
items:
type: string
examples:
uat:
value: [ "quas=7913494","quas=6815686" ]
summary: "quantity list"
required: true
responses:
200:
description: Successful operation.
content:
application/json:
schema:
type: object
400:
description: Invalid input.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
401:
description: Invalid credentails.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
403:
description: Insufficient permissions.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
500:
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- apiKey: []
components:
schemas:
ErrorResponse:
type: object
properties:
error:
type: object
properties:
message:
type: string
securitySchemes:
apiKey:
type: apiKey
name: Authorization
in: header
このセクションで説明されている用語について不明な点がある場合は、リファレンスページをご覧ください。
注文情報の取得
CitrusAd内で注文情報を確認したい場合は、注文IDを指定して /orders/ APIにGETリクエストを行います。
GET $BASE_URL/v1/orders/<ORDER_ID> HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
CitrusAdのシステム内に保存されている注文に関連する情報をすべて取得することができます。注文情報が見つからない場合は、CitrusAdのシステムに取り込まれていない可能性があります。