Tùy chọn 1: Sử dụng API để cập nhật danh mục của bạn
Thêm thông tin chi tiết sản phẩm vào danh mục của bạn bằng API.
Bạn có thể sử dụng API để cập nhật thông tin chi tiết của sản phẩm, bao gồm mã sản phẩm, giá cả, thông tin hàng tồn kho, URL hình ảnh, v.v. Ngoài ra, bạn cũng có thể cập nhật thông tin vị trí và thông tin về hàm lượng chất béo, đường và muối cao (HFSS).
Điều kiện tiên quyết
Bạn phải có khóa API và URL cơ sở trước khi yêu cầu tạo danh mục.
-
Bạn phải có mã khóa API hợp lệ. Để tìm nạp khóa API, hãy làm như sau:
-
Đăng nhập vào tài khoản nhóm Phương tiện Bán lẻ của Epsilon của bạn.
-
Điều hướng đến phía trên bên phải của trang và nhấp vào menu thả xuống.
-
Chọn Cài đặt tích hợp, từ menu thả xuống.
-
Nhấp vào tab Mã khóa API. Mã khóa API bí mật của bạn ban đầu bị ẩn. Để xem mã khóa, nhấp vào nút Hiển thị. Khi mã khóa hiển thị, hãy sao chép mã khóa API bí mật của bạn. Sử dụng mã khóa này để thực hiện lệnh gọi API.
-
-
Bạn phải có URL cơ sở cho điểm cuối API. Ví dụ: https://staging-test.citrusad.com/v1/ads/generate HTTP/1.1. Kiểm tra với Người quản lý Tài khoản Kỹ thuật của bạn để biết URL cơ sở.
Bối cảnh tiêu chuẩn để thêm sản phẩm
Sau khi danh mục được tạo, bạn có thể đồng bộ hóa sản phẩm vào danh mục đó bằng API. Ví dụ sau đây thể hiện bối cảnh tiêu chuẩn để thêm sản phẩm.
Yêu cầu Thông số
Sau đây là các thông số truy vấn và nội dung:
Thông số truy vấn
| đối tượng | type | Mô tả |
|---|---|---|
| teamId | chuỗi, tùy chọn | ID của nhóm của bạn. Nếu một teamId không được cung cấp, nó sẽ mặc định là teamId được chỉ định trong xác thực. |
Thông số nội dung
| đối tượng | type | Mô tả |
|---|---|---|
| catalogId | chuỗi, bắt buộc | Mã nhận dạng cho danh mục chứa sản phẩm. |
| gtin | chuỗi, bắt buộc | Mã số thương phẩm toàn cầu (GTIN) cho sản phẩm. |
| inventory | số, tùy chọn | Kiểm kê hàng tồn kho của sản phẩm. |
| giá | số, tùy chọn | Giá của sản phẩm. |
| categoryHierarchy | mảng chuỗi, tùy chọn | Hệ thống phân cấp các danh mục mà sản phẩm thuộc về. |
| tags | mảng chuỗi, tùy chọn | Các thẻ được liên kết với Sản phẩm. |
| bộ lọc | mảng chuỗi, tùy chọn | Các bộ lọc được áp dụng cho sản phẩm. |
Yêu cầu Ví dụ
POST $BASE_URL/v1/catalog-products?teamId=<YOUR_TEAM_ID> HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
"catalogProducts": [
{
"catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
"gtin": "23556578965543",
"inventory": 50,
"price": "19.99",
"tags": [
"imageurl:https://your.image.host.com/image.jpg","name:Covergirl Clean 120 Creamy Natural Liquid Foundation30mL"
],
"filters": [
"category:Health&Beauty","category:Grocery","Brand:Covergirl","Special_Flag:0"
]
}
]
}
Yêu cầu phản hồi
{
"catalogProducts": [
{
"teamId": "e8158f9b-bbb9-49fb-93fe-3ad481ca8450",
"catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
"gtin": "23556578965543",
"inventory": 50,
"price": 19.99,
"tags": [
"imageurl:https://your.image.host.com/image.jpg",
"name:Covergirl Clean 120 Creamy Natural Liquid Foundation30mL"
],
"filters": [
"category:Health&Beauty",
"category:Grocery",
"Brand:Covergirl",
"Special_Flag:0"
],
"groups": [],
"profit": null
}
]
}
Cập nhật thông tin vị trí
Bạn cũng có thể cập nhật bộ lọc cho các vị trí cửa hàng khác nhau nơi sản phẩm của bạn có hàng. Tính năng này rất hữu ích đối với việc tối ưu hóa thông tin sản phẩm ở cấp cửa hàng hoặc vị trí.
Yêu cầu Ví dụ
POST $BASE_URL/v1/catalog-products?teamId=<YOUR_TEAM_ID> HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
"catalogProducts": [
{
"catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
"gtin": "23556578965543",
"inventory": 50,
"price": "19.99",
"tags": [
"imageurl:https://your.image.host.com/image.jpg","name:Covergirl Clean 120 Creamy Natural Liquid Foundation30mL"
],
"filters": [
"category:Health&Beauty","category:Grocery","Brand:Covergirl","Special_Flag:0","location:123","location:ABC"
]
}
]
}
Ví dụ về Phản hồi
{
"catalogProducts": [
{
"teamId": "e8158f9b-bbb9-49fb-93fe-3ad481ca8450",
"catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
"gtin": "23556578965543",
"inventory": 50,
"price": 19.99,
"tags": [
"imageurl:https://your.image.host.com/image.jpg",
"name:Covergirl Clean 120 Creamy Natural Liquid Foundation30mL"
],
"filters": [
"category:Health&Beauty",
"category:Grocery",
"Brand:Covergirl",
"Special_Flag:0",
"location:123",
"location:ABC"
],
"groups": [],
"profit": null
}
]
}
Cập nhật thông tin HFSS
Để đưa thông tin HFSS (Hàm lượng chất béo, đường và muối cao) vào bản cập nhật sản phẩm của bạn, bạn cần gửi bộ lọc có giá trị hfss:true hoặc hfss:false. Điều này cho phép Epsilon Retail Media lọc giao diện một cách thích hợp dựa trên tiêu chí HFSS.
Yêu cầu Ví dụ
POST $BASE_URL/v1/catalog-products?teamId=<YOUR_TEAM_ID> HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
"catalogProducts": [
{
"catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
"gtin": "23556578965543",
"inventory": 50,
"price": "19.99",
"tags": [
"imageurl:https://your.image.host.com/image.jpg","name:Covergirl Clean 120 Creamy Natural Liquid Foundation30mL"
],
"filters": [
"hfss:true","category:Health&Beauty","category:Grocery","Brand:Covergirl","Special_Flag:0","location:123","location:ABC"
]
}
]
}
Thêm nhiều sản phẩm
Khi cập nhật nhiều sản phẩm, bạn có thể xử lý tối đa 100 mặt hàng cho mỗi yêu cầu. Ví dụ sau đây minh họa bối cảnh cập nhật hai sản phẩm.
Yêu cầu Ví dụ
POST $BASE_URL/v1/catalog-products?teamId=<YOUR_TEAM_ID> HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
"catalogProducts": [
{
"catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
"gtin": "23556578965543",
"inventory": 50,
"price": "19.99",
"tags": [
"imageurl:https://your.image.host.com/image.jpg",
"name:Covergirl Clean 120 Creamy Natural Liquid Foundation30mL"
],
"filters": [
"category:Health&Beauty",
"category:Grocery",
"Brand:Covergirl",
"Special_Flag:0"
],
"profit": "1.50"
},
{
"catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
"gtin": "23556578965738",
"inventory": 26,
"price": "8.50",
"tags": [
"imageurl:https://your.image.host.com/image.jpg",
"name:Kelloggs Froot Loops Breakfast Cereal 500g"
],
"filters": [
"Brand:Kelloggs",
"category:Pantry",
"category:BreakfastFoods",
"category:Cereals",
"Special_Flag:0"
],
"profit": "0.50"
}
]
}
Yêu cầu phản hồi
{
"catalogProducts": [
{
"gtin": "23556578965543",
"catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
"price": 19.99,
"teamId": "e8158f9b-bbb9-49fb-93fe-3ad481ca8450",
"groups": [],
"tags": [
"imageurl:https://your.image.host.com/image.jpg",
"name:Covergirl Clean 120 Creamy Natural Liquid Foundation30mL"
],
"filters": [
"category:Health&Beauty",
"category:Grocery",
"Brand:Covergirl",
"Special_Flag:0"
],
"inventory": 50,
"profit": 1.50,
"tags": [
"Natural",
"Lasting",
"Dry Skin",
"Beige"
]
},
{
"gtin": "23556578965736688",
"catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
"price": 8.50,
"teamId": "e8158f9b-bbb9-49fb-93fe-3ad481ca8450",
"groups": [],
"tags": [
"imageurl:https://your.image.host.com/image.jpg",
"name:Kelloggs Froot Loops Breakfast Cereal 500g"
],
"filters": [
"Brand:Kelloggs",
"category:Pantry",
"category:BreakfastFoods",
"category:Cereals",
"Special_Flag:0"
],
"inventory": 26,
"profit": 0.50,
"tags": [
"Pantry",
"BreakfastFoods",
"Cereals",
"Kelloggs"
]
}
]
}
Thêm bộ lọc sản phẩm
Trong quá trình tạo quảng cáo thông qua API CitrusAd, bạn có thể áp dụng các bộ lọc sản phẩm để tinh chỉnh kết quả. Để làm điều này, bạn chỉ cần thêm trường productFilters trường vào yêu cầu POST của bạn. Trường productFilters là một mảng chứa một hoặc nhiều mảng phụ, mỗi mảng đại diện cho một bộ lọc khác nhau.
Yêu cầu Ví dụ
Sau đây là một ví dụ về yêu cầu POST đến /v1/ads/generate điểm cuối bao gồm productFilters:
POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
"customerId": "wertg5432a",
"sessionId": "ec9-4e07-881d-3e9",
"placement": "search",
"catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
"searchTerm": "chocolate",
"productFilters": [
["category:Cupboard"],["dietary:Gluten-free"]
],
"options": {
"filterMode": "AndOr"
},
"maxNumberOfAds": 3
}
Trong ví dụ này,
- Hai bộ lọc sản phẩm được bao gồm
category:Cupboardvàdietary:Gluten-free. Tùy chọn filterMode được đặt thànhAndOr, nghĩa là API sẽ trả về quảng cáo cho các sản phẩm phù hợp với cả hai bộ lọc này. - Quảng cáo trả về sẽ chỉ giới thiệu những sản phẩm thuộc danh mục 'Tủ ly' và 'Không chứa gluten'. Số lượng quảng cáo trả về sẽ không vượt quá quy định
maxNumberOfAds, số lượng này được đặt là 3 trong ví dụ này.
Với việc sử dụng đúng cách productFilters, bạn có thể tùy chỉnh hiệu quả kết quả quảng cáo để phù hợp hơn với nhu cầu chiến dịch của mình.
Bao gồm hình ảnh và tên sản phẩm thiết yếu
Để cải thiện khả năng tìm kiếm trong quá trình tạo chiến dịch trên cổng thông tin CitrusAd, hãy cung cấp hình ảnh và tên sản phẩm. Gán giá trị cho hình ảnh và tên trong các thẻ tương ứng. Những giá trị này sẽ được gửi tới CitrusAd.
Yêu cầu Ví dụ
Sau đây là một ví dụ về yêu cầu POST đến /v1/catalog-products điểm cuối bao gồm hình ảnh và tên sản phẩm:
POST $BASE_URL/v1/catalog-products?teamId=<YOUR_TEAM_ID> HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
"catalogProducts": [
{
"catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
"gtin": "23556578965543",
"inventory": 50,
"price": "19.99",
"tags": [
""imageurl:https://your.image.host.com/image.jpg","name:Covergirl Clean 120 Creamy Natural Liquid Foundation30mL"
],
"filters": [
"category:Health&Beauty","category:Grocery","Brand:Covergirl","Special_Flag:0"
]
}
]
}
Trong ví dụ về yêu cầu ở trên, trường thẻ bao gồm hai thông tin chính là URL hình ảnh và tên sản phẩm. imageurl và name là các khóa, và mỗi khóa đều có các giá trị tương ứng theo sau.
imageurl:https://your.image.host.com/image.jpg cung cấp URL nơi lưu trữ hình ảnh sản phẩm.name: Covergirl Clean 120 Creamy Natural Liquid Foundation 30mL cung cấp tên sản phẩm.
Cập nhật 4 tháng trước