Bước đầu tiên là tạo danh mục sản phẩm. Danh mục chứa thông tin chi tiết về sản phẩm của bạn, bắt buộc phải có thông tin này để phân phối quảng cáo cho sản phẩm của bạn.

• Bạn có thể tạo một hoặc nhiều danh mục trong một yêu cầu. Nếu bạn đang tạo nhiều danh mục, bạn có thể sắp xếp tối đa 100 danh mục cho mỗi yêu cầu.
• Khi tạo một danh mục, một catalogId được trả về. Điều này catalogId là giá trị bắt buộc khi thêm thông tin chi tiết về sản phẩm vào danh mục của bạn, đóng vai trò là mã nhận dạng duy nhất cho danh mục.
• Nếu bạn không thể tạo danh mục bằng các API được đề cập trong tài liệu này, hãy liên hệ với Kỹ sư Tích hợp Khách hàng (CIE) của bạn. Họ có thể thay mặt bạn tạo danh mục.
• Sau khi danh mục được tạo, theo mặc định, danh mục đó sẽ bị ẩn, do đó bạn cần liên hệ với CIE để làm cho danh mục đó hiển thị trong không gian tên của bạn.

Đ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.

1. 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:

   1. Đă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.

   2. Đ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.

   3. Chọn Cài đặt tích hợp, từ menu thả xuống.

      

   4. 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.

2. 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ở.

Tạo một danh mục

Điểm cuối API này cho phép bạn tạo danh mục mới. Mỗi danh mục được nhận dạng duy nhất bởi một id mà bạn sẽ cần cho các hoạt động tiếp theo, chẳng hạn như khi thêm thông tin chi tiết về sản phẩm vào danh mục.

Yêu cầu Thông số

Yêu cầu Ví dụ

POST $BASE_URL/v1/catalogs HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "catalogs": [
        {
            "name": "Retailer A"
        }
    ]
}

Ví dụ về Phản hồi

Các phản hồi tuân theo định dạng JSON tiêu chuẩn và trả về các thông tin chi tiết sau trong một mảng.

• teamId: ID của nhóm liên quan đến danh mục.
• name: Tên danh mục.
• id: Mã nhận dạng duy nhất cho danh mục. Bắt buộc phải có ID này cho các hoạt động tiếp theo như khi thêm thông tin thông tin chi tiết của sản phẩm vào danh mục của bạn.

{
    "catalogs": [
        {
            "teamId": "9f48572c-0a5b-4997-9a0e-ed74f4d32dc6",
            "name": "Retailer A",
            "id": "216af452-d219-4807-b8ca-578bba446541"
        }
    ]
}

📘

Khi một đối tượng được trả lại thành công, bạn sẽ nhận được một ID cho danh mục mới của mình. Nếu bạn gửi lại yêu cầu tương tự, bạn sẽ nhận được ID mới, dẫn đến việc tạo ra hai danh mục.

Tạo nhiều danh mục

Điểm cuối API này cho phép bạn tạo nhiều danh mục. Khi tạo nhiều danh mục, bạn có thể sắp xếp tối đa 100 danh mục cho mỗi yêu cầu. Dưới đây là một ngữ cảnh ví dụ để tạo hai danh mục:

Yêu cầu Ví dụ

POST $BASE_URL/v1/catalogs HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "catalogs": [
        {
            "name": "Retailer A"
        },
        {
            "name": "Retailer B"
        }
    ]
}

Ví dụ về Phản hồi

Các phản hồi tuân theo định dạng JSON tiêu chuẩn và trả về các thông tin chi tiết sau trong một mảng. Mỗi danh mục sẽ có riêng teamid, name và id:

• teamId: ID của nhóm liên quan đến danh mục.
• name: Tên danh mục.
• id: Mã nhận dạng duy nhất cho danh mục. Bắt buộc phải có ID này cho các hoạt động tiếp theo như khi thêm thông tin thông tin chi tiết của sản phẩm vào danh mục của bạn.

{
    "catalogs": [
        {
            "teamId": "9f48572c-0a5b-4997-9a0e-ed74f4d32dc6",
            "name": "Retailer A",
            "id": "216af452-d219-4807-b8ca-578bba446541"
        },
        {
            "teamId": "9f48572c-0a5b-4997-9a0e-ed74f4d32dc6",
            "name": "Retailer B",
            "id": "75047339-65f5-41b8-8f2c-e76b04716cd4"
        }
    ]
}

Tạo nhiều danh mục cho mỗi nhà bán lẻ

Cách quản lý nhiều danh mục:

• Tạo nhóm bán lẻ “con” riêng biệt cho mỗi danh mục và một nhóm bán lẻ “mẹ” duy nhất.
• Thiết lập mối quan hệ mẹ/con giữa nhóm mẹ và mỗi nhóm con, đảm bảo nhóm mẹ được liên kết chính xác với tất cả các nhóm con.
• Sau khi thiết lập nhóm mẹ, hãy cập nhật các tiêu chuẩn nội dung cho tất cả các nhóm con để liên kết chúng với nhóm mẹ. Hãy liên hệ với Kỹ sư Tích hợp Khách hàng (CIE) để thực hiện việc này.

Khi tạo nhiều danh mục cho một nhà bán lẻ, hãy cân nhắc những điểm sau:

• Mối quan hệ 1-1: Thiết lập an toàn nhất là có mối quan hệ 1-1 giữa danh mục và các nhóm bán lẻ. Mặc dù không thực sự cần thiết nhưng điều này giúp tránh được các rắc rối.

• Cấu trúc mẫu: Trong sơ đồ sau, nhóm gốc được lồng vào không gian tên của nhà bán lẻ. Mỗi đội con (A, B, C) có danh mục liên kết riêng (A, B, C). Cấu trúc này đảm bảo rằng các giao dịch mua được phân bổ chính xác vào các danh mục tương ứng dựa trên khóa API của nhóm được sử dụng trong xác nhận đơn hàng.

  

• Nhiều danh mục trong một nhóm: Bạn có thể tạo nhiều danh mục trong cùng một nhóm bán lẻ. Tuy nhiên, hãy đảm bảo rằng SKU và SessionID không được chia sẻ trên các danh mục này để duy trì sự phân bổ chính xác. Bao gồm catalogId theo thứ tự lệnh gọi API giúp phân biệt các danh mục và ngăn ngừa lỗi phân bổ. Để biết thêm thông tin, hãy xem Đồng bộ hóa dữ liệu đơn hàng qua API.

• Các vấn đề về phân bổ: Chia sẻ SKU và session IDs cho nhiều danh mục có thể gây ra vấn đề về phân bổ. Ví dụ: nếu bạn có một trang web bằng hai ngôn ngữ (ví dụ: ES và FR) với một nhóm nhà bán lẻ được liên kết với hai danh mục (một nhóm cho mỗi ngôn ngữ) và SKU được chia sẻ, việc một người dùng được xác định bởi cùng một sessionID trong cả hai phiên bản đều có thể dẫn đến việc hành động mua hàng trên trang ES được quy cho trang FR và ngược lại. Bao gồm catalogId theo thứ tự, lệnh gọi API khắc phục sự cố này bằng cách đảm bảo rằng thuộc tính được gán chính xác cho danh mục tương ứng. Để biết thêm thông tin, hãy xem Đồng bộ hóa dữ liệu đơn hàng qua API.