파트너 API
가이드

옵션 1: API를 활용하여 카탈로그 업데이트하기

API를 사용하여 카탈로그에 제품 세부 정보 추가하기

API를 사용하여 제품 코드, 가격, 재고 현황, 이미지 URL 등 제품 세부 정보를 업데이트할 수 있습니다. 또한 위치 정보 및 고지방, 고당, 고염분(HFSS) 정보를 업데이트할 수 있습니다.

사전 필수 조건

카탈로그 생성을 요청하려면 API 키 및 기본 URL이 있어야 합니다.

  1. 유효한 API 키가 있어야 합니다. 다음에 따라 API 키를 가져올 수 있습니다.

    1. Epsilon Retail Media 팀 계정에 로그인합니다.

    2. 페이지 오른쪽 상단으로 이동하여 드롭다운 메뉴를 클릭합니다.

    3. 드롭다운 메뉴에서 통합 설정을 선택합니다.

    4. API 키 탭을 클릭합니다. 초기 상태에는 비밀 API 키가 숨겨져 있습니다. 표시 버튼을 클릭하면 확인할 수 있습니다. 클릭 후 비밀 API 키를 복사합니다. API 호출 시 이 키를 사용합니다.

  2. API 엔드포인트의 기본 URL이 있어야 합니다. (예: https://staging-test.citrusad.com/v1/ads/generate HTTP/1.1) 기술 계정 관리자에게 기본 URL을 요청하세요.

제품을 추가하기 위한 표준 컨텍스트

카탈로그가 생성되면 API를 사용하여 제품을 카탈로그에 동기화할 수 있습니다. 다음은 제품을 추가하기 위한 표준 컨텍스트의 예입니다.

요청 매개 변수

다음은 쿼리 및 본문 매개 변수입니다.

쿼리 매개 변수

개체유형설명
팀 ID문자열, 선택 사항팀 ID입니다 . teamId 가 제공되지 않은 경우 인증에 지정된 teamId 로 기본값이 설정됩니다.

본문 매개 변수

개체유형설명
카탈로그 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(고지방, 고당, 고염분) 정보를 포함하려면 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로 광고를 생성하는 과정에서 제품 필터를 적용하여 결과를 세분화할 수 있습니다 . POST 요청에 productFilters 필드를 포함하면 됩니다 . productFilters 필드는 각기 다른 필터를 나타내는 하나 이상의 하위 배열을 포함하는 배열입니다.

요청 예시

아래는 다음 필드를 포함하는 /v1/ads/generate 엔드포인트에 대한 POST 요청의 예입니다. 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로 전송됩니다.

요청 예시

아래는 다음 필드를 포함하는 /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는 제품명입니다.

업데이트됨 4개월 전