파트너 API
API 참조

API를 통한 제품 동기화

표준 제품 동기화

카탈로그가 생성되면 제품을 동기화할 수 있습니다. 아래 예시에서는 제품을 동기화하기 위한 표준 컨텍스트를 간략히 설명합니다.

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

이 컨텍스트에서 그룹 및 수익에 대한 비어 있는 값이나 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:true 또는 hfss:false. 이로써 CitrusAd가 인터페이스를 적절하게 필터링할 수 있습니다.

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

📘

HFSS에 대해 더 자세히 알고 싶으십니까?

여기에서 영국 정부 게시 자료를 검토하십시오: 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

여러 제품 동기화

여러 제품을 동기화하는 경우 요청당 최대 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에 재동기화해야 합니다. 동기화 시 제품의 재고를 0으로 지정합니다. 아래 예시를 참조하십시오.

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

제품 검색

카탈로그에 제품을 포함하고 나면 나중에 현재 정보를 검색하고 싶을 수도 있습니다.

이를 위해 다음 URL 형식을 사용하여 GET http 요청을 만들 수 있습니다. v1/catalog-products/catalogId/<PRODUCT_CODE>. 엔드포인트는 요청당 하나의 제품 코드를 허용할 수 있습니다. 플레이스홀더 요청은 아래와 같습니다.

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

제품 코드와 관련해 CitrusAd 시스템에서 수집한 현재의 정보를 수신해야 합니다. 아래는 예시입니다.

📘

제품 업데이트 푸시는 CitrusAd 시스템에서 즉각 이루어지지 않으며 CitrusAd가 제품 업데이트를 완전히 수집하는 데에는 약간의 시간이 소요될 수 있습니다. 세부 정보를 검색할 때 제품 정보가 즉시 업데이트되지 않는 경우 걱정하지 마십시오.

제품 삭제

제품 광고가 더 이상 필요하지 않을 때 카탈로그에서 제품 광고를 삭제하려면 다음 형식을 사용하여 DELETE HTTP 요청을 보내십시오.

요청 매개 변수

엔드포인트는 요청당 하나의 제품 광고 코드를 허용하며 이 코드는 일반적으로 GTIN ID입니다.

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

판매자 ID로 제품 광고 삭제하기

제품 광고에 판매자 ID가 포함되어 있는 경우 제품 광고 삭제 시 이를 쿼리 매개 변수로 지정해야 합니다.

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

처리 시간

제품 광고가 삭제 완료되는 데 30분에서 1시간 정도 소요될 수 있습니다.

📘

중요

제품의 재고가 없는 경우에는 제품을 삭제하는 대신 재고를 0으로 설정합니다. 제품을 삭제하면 광고주가 CitrusAd 플랫폼에서 해당 제품을 선택할 수 있는 기능이 삭제되며 추후 재입고 되는 경우에도 사용할 수 없습니다.

오류 처리

"제품 광고를 찾을 수 없음" 오류가 표시되는 경우 해당 제품 광고가 CitrusAd 시스템에 수집되지 않은 것일 수 있습니다.