คุณสามารถใช้ API เพื่ออัปเดตรายละเอียดผลิตภัณฑ์ รวมถึงรหัสผลิตภัณฑ์ ราคา รายละเอียดสต๊อก URL ภาพ และอื่นๆ นอกจากนี้ คุณยังสามารถอัปเดตข้อมูลตำแหน่งและข้อมูลไขมัน น้ำตาล และเกลือสูง (HFSS) ได้อีกด้วย

ข้อกําหนดเบื้องต้น

คุณต้องมีคีย์ API และ URL ฐานก่อนจึงจะทำการร้องขอสร้างแค็ตตาล็อก

คุณต้องมีคีย์ API ที่ถูกต้อง หากต้องการดึงข้อมูลคีย์ API ให้ทำดังต่อไปนี้:
1. ลงชื่อเข้าใช้บัญชีทีม Retail Media ของ Epsilon
2. ไปที่มุมขวาบนของหน้าแล้วคลิกเมนูแบบเลื่อนลง
3. เลือก การตั้งค่าการรวม จากเมนูแบบเลื่อนลง
4. คลิกที่แท็บคีย์ API รหัส API ลับของคุณถูกซ่อนไว้ในตอนแรก หากต้องการดู ให้คลิกที่ปุ่มแสดง เมื่อมองเห็นได้ ให้คัดลอกคีย์ API ลับของคุณ ใช้คีย์นี้เพื่อเรียก API
คุณต้องมี URL ฐานสำหรับเอนพอยต์ API ตัวอย่างเช่น https://staging-test.citrusad.com/v1/ads/generate HTTP/1.1 ตรวจสอบกับผู้จัดการบัญชีทางเทคนิคของคุณสำหรับ URL ฐาน

บริบทมาตรฐานในการเพิ่มผลิตภัณฑ์

เมื่อคุณสร้างแค็ตตาล็อกแล้ว คุณสามารถซิงโครไนซ์ผลิตภัณฑ์โดยใช้ API ตัวอย่างต่อไปนี้สาธิตบริบทมาตรฐานในการเพิ่มผลิตภัณฑ์

ขอพารามิเตอร์

ต่อไปนี้เป็นพารามิเตอร์การสืบค้นและเนื้อหา:

พารามิเตอร์การสืบค้น

วัตถุ	ประเภท	คำอธิบาย
ID ทีม	สตริง, ไม่บังคับ	ID of your team. If a `teamId` is not provided, it will default to the `teamId` specified in the authentication.

พารามิเตอร์เนื้อหา

วัตถุ	ประเภท	คำอธิบาย
ID แคตตาล็อก	สตริง, จำเป็น	ตัวระบุสำหรับแค็ตตาล็อกที่ผลิตภัณฑ์นั้นอยู่
GTIN	สตริง, จำเป็น	หมายเลขประจำตัวสินค้าสากล (GTIN) สำหรับผลิตภัณฑ์
สินค้าคงคลัง	หมายเลข, ไม่บังคับ	จำนวนสต็อกสําหรับผลิตภัณฑ์
ราคา	หมายเลข, ไม่บังคับ	ราคาผลิตภัณฑ์
categoryHierarchy	อาร์เรย์สตริง ไม่จําเป็น	ลําดับชั้นของแค็ตตาล็อกที่ผลิตภัณฑ์นั้นอยู่
แท็ก	อาร์เรย์สตริง ไม่จําเป็น	แท็กที่เกี่ยวข้องกับผลิตภัณฑ์
ตัวกรอง	อาร์เรย์สตริง ไม่จําเป็น	ตัวกรองที่ใช้กับผลิตภัณฑ์

ตัวอย่างคำขอ

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

ร้องขอการตอบกลับ

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

อัปเดตข้อมูลตำแหน่ง

นอกจากนี้ คุณยังสามารถอัปเดตตัวกรองสำหรับตำแหน่งที่ตั้งร้านค้าต่างๆ ที่มีผลิตภัณฑ์ของคุณจำหน่ายได้ คุณสมบัตินี้มีประโยชน์สำหรับการปรับข้อมูลผลิตภัณฑ์ในระดับร้านค้าหรือตำแหน่งที่ตั้งให้เหมาะสมที่สุด

ตัวอย่างคำขอ

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

ตัวอย่างการตอบสนอง

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

อัปเดตข้อมูล HFSS

หากต้องการรวมข้อมูล HFSS (High Fat, Sugar, and Salt) ในการอัปเดตผลิตภัณฑ์ คุณต้องส่งตัวกรองที่มีค่า hfss:true หรือ hfss:false ซึ่งจะช่วยให้ Epsilon Retail Media สามารถกรองอินเทอร์เฟซตามเกณฑ์ HFSS ได้อย่างเหมาะสม

ตัวอย่างคำขอ

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

เพิ่มผลิตภัณฑ์หลายรายการ

เมื่ออัปเดตผลิตภัณฑ์หลายรายการ คุณสามารถประมวลผลได้สูงสุด 100 รายการต่อคำขอ ตัวอย่างต่อไปนี้แสดงให้เห็นบริบทสำหรับการอัปเดตผลิตภัณฑ์สองรายการ

ตัวอย่างคำขอ

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

ร้องขอการตอบกลับ

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

เพิ่มตัวกรองผลิตภัณฑ์

ในกระบวนการสร้างโฆษณาผ่าน CitrusAd API คุณอาจต้องการใช้ตัวกรองผลิตภัณฑ์เพื่อปรับแต่งผลลัพธ์ของคุณ สามารถทำได้โดยการใส่ฟิลด์ productFilters ในคำขอ POST ของคุณ ฟิลด์ productFilters เป็นอาร์เรย์ที่ประกอบด้วยอาร์เรย์ย่อยหนึ่งรายการหรือมากกว่า โดยแต่ละรายการแสดงถึงตัวกรองที่แตกต่างกัน

ตัวอย่างคำขอ

นี่คือตัวอย่างคำขอ POST ไปยังเอนพอยต์ /v1/ads/generate ซึ่งรวมถึง 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
}

ในตัวอย่างนี้

มีสองตัวกรองผลิตภัณฑ์ ได้แก่ category:Cupboardและdietary:Gluten-free ตัวเลือก FilterMode ถูกตั้งค่าเป็นAndOr ซึ่งหมายความว่า API จะส่งคืนโฆษณาสำหรับผลิตภัณฑ์ที่ตรงกับตัวกรองทั้งสองนี้
โฆษณาที่ส่งคืนจะแสดงเฉพาะผลิตภัณฑ์ที่อยู่ในหมวดหมู่ 'ตู้กับข้าว' และ 'ปราศจากกลูเตน' เท่านั้น จำนวนโฆษณาที่ส่งคืนจะไม่เกิน maxNumberOfAds ที่ระบุ ซึ่งตั้งค่าเป็น 3 ในตัวอย่างนี้

การใช้productFiltersที่ถูกต้อง จะทำให้คุณสามารถปรับแต่งผลการแสดงโฆษณาได้อย่างมีประสิทธิผลเพื่อให้เหมาะกับความต้องการของแคมเปญของคุณได้มากขึ้น

รวมภาพและชื่อผลิตภัณฑ์ที่จำเป็น

เพื่อให้ค้นหาได้ง่ายขึ้นในระหว่างกระบวนการสร้างแคมเปญในพอร์ทัล CitrusAd โปรดใส่ภาพและชื่อผลิตภัณฑ์ กำหนดค่าให้กับภาพและชื่อภายในแท็กที่เกี่ยวข้อง ค่าเหล่านี้จะถูกส่งไปยัง CitrusAd

ตัวอย่างคำขอ

นี่คือตัวอย่างคำขอ POST ไปยังเอนพอยต์ /v1/catalog-productsที่มีภาพและชื่อผลิตภัณฑ์:

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

ในคำขอตัวอย่างด้านบน ฟิลด์แท็กมีข้อมูลสำคัญสองส่วนคือ URL ภาพและชื่อผลิตภัณฑ์ imageurl และ name คือคีย์ และแต่ละคีย์จะตามด้วยค่าที่เกี่ยวข้อง

imageurl:https://your.image.host.com/image.jpg ให้ URL ที่โฮสต์ภาพผลิตภัณฑ์
name: Covergirl Clean 120 Creamy Natural Liquid Foundation 30mL ให้ชื่อของผลิตภัณฑ์