API đối tác

Đồng bộ hóa sản phẩm thông qua API

Đồng bộ hóa sản phẩm tiêu chuẩn

Sau khi danh mục của bạn được tạo, bạn có thể đồng bộ hóa các sản phẩm với danh mục đó. Ví dụ dưới đây phác thảo bối cảnh tiêu chuẩn để đồng bộ hóa các 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"
            ]
        }
    ]
}

Nếu thành công, đối tượng sau sẽ được trả về:

{
    "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
        }
    ]
}

Trong ngữ cảnh này, có thể bỏ qua các giá trị trống hoặc rỗng cho nhóm và lợi nhuận.

Đồng bộ hóa thông tin vị trí

Bạn cũng có thể đồng bộ hóa bộ lọc cho các vị trí khác nhau mà sản phẩm của bạn đang có trong cửa hàng. Điều này rất hữu ích cho việc tối ưu hóa cấp độ cửa hàng/vị trí của thông tin sản phẩm của bạn.

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"
            ]
        }
    ]
}

Nếu thành công, đối tượng sau sẽ được trả về:

{
    "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
        }
    ]
}

Đồng bộ hóa thông tin HFSS

Khi đồng bộ hóa sản phẩm của bạn, bạn sẽ cần gửi một bộ lọc có chứa hfss:true hoặc hfss:false. Việc này cho phép CitrusAd lọc giao diện của chúng tôi một cách phù hợp.

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"
            ]
        }
    ]
}

📘

Bạn cần tìm hiểu thêm về HFSS?

Xem bài viết của Chính phủ Anh tại đây: https://www.gov.uk/government/publications/restricting-promotions-of-products-high-in-fat-sugar-or-salt-by-location-and-by-volume-price/restricting-promotions-of-products-high-in-fat-sugar-or-salt-by-location-and-by-volume-price-implementation-guidance

Đồng bộ hóa nhiều sản phẩm

Nếu bạn đang đồng bộ hóa nhiều sản phẩm, bạn có thể sắp xếp tối đa 100 cho mỗi yêu cầu.

Dưới đây là một ví dụ về ngữ cảnh để đồng bộ hóa hai 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"
            ],
            "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"
        }
    ]
}

Nếu thành công, đối tượng sau sẽ được trả về:

{
    "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"
            ]
        }
    ]
}

Cập nhật hàng tồn kho sản phẩm

Để cập nhật tình trạng tồn kho của một sản phẩm, bạn cần đồng bộ lại sản phẩm với CitrusAd. Trong mục đồng bộ của bạn, hãy gắn cờ tình trạng tồn kho của sản phẩm thành 0. Sau đây là 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": 0,
            "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"
            ]
        }
    ]
}

Truy xuất sản phẩm

Khi bạn có một sản phẩm trong danh mục, một lúc nào đó về sau bạn có thể sẽ muốn truy xuất thông tin hiện có về sản phẩm đó.

Để làm vậy, bạn có thể tạo một yêu cầu http LẤY với dạng thức url là v1/catalog-products/catalogId/<PRODUCT_CODE>Điểm cuối có thể tiếp nhận một mã sản phẩm cho mỗi yêu cầu. Dưới đây là yêu cầu giữ chỗ:

GET $BASE_URL/v1/catalog-products/<CATALOG_ID>/<PRODUCT_CODE> HTTP/1.1 
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>

Bạn cần nhận thông tin hiện thời được nhập vào trong hệ thống CitrusAd cho mã sản phẩm này. Dưới đây là một ví dụ

📘

Việc áp dụng một bản cập nhật sản phẩm không phải là quá trình diễn ra ngay lập tức trong hệ thống CitrusAd, có thể mất một khoảng thời gian ngắn để CitrusAd tích hợp đầy đủ bản cập nhật sản phẩm. Đừng lo lắng nếu thông tin sản phẩm không được cập nhật ngay lập tức khi truy xuất thông tin chi tiết.

Xóa sản phẩm

Khi bạn có một sản phẩm trong danh mục của mình, bạn có thể sẽ muốn xóa nó đi sau này.

Để thực hiện việc này, bạn có thể tạo một yêu cầu http XÓA với dạng thức url là v1/catalog-products/catalogId/<PRODUCT_CODE>Điểm cuối có thể tiếp nhận một mã sản phẩm cho mỗi yêu cầu. Dưới đây là yêu cầu giữ chỗ:

DELETE $BASE_URL/v1/catalog-products/<CATALOG_ID>/<PRODUCT_CODE> HTTP/1.1 
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>

Có thể mất 30 phút đến một giờ để xử lý việc xóa sản phẩm.

❗️

Nếu một sản phẩm hết hàng thì sản phẩm đó phải được đặt thành 0 trong kho, KHÔNG bị xóa. Việc xóa một sản phẩm sẽ loại bỏ khả năng các nhà quảng cáo chọn sản phẩm đó trong nền tảng CitrusAd để quảng cáo tự động khi sản phẩm đó có hàng trở lại.

Trong trường hợp không tìm thấy sản phẩm, thông tin của sản phẩm đó có thể chưa được nhập vào hệ thống CitrusAd.