Puede usar las API para actualizar los detalles del producto, incluido el código del producto, el precio, los detalles del inventario, la URL de la imagen y mucho más. Además, también puede actualizar la información de ubicación y la información con alto contenido en grasas, azúcar y sal (HFSS).

Requisitos

Debe tener claves de API y la URL básica antes de solicitar la creación de catálogos.

Debe tener una clave de API válida. Para obtener las claves de API, haga lo siguiente:
1. Inicie sesión en la cuenta de equipo de Epsilon Retail Media.
2. Navegue hasta la parte superior derecha de la página y haga clic en el menú desplegable.
3. Seleccione Configuración de integración en el menú desplegable.
4. Haga clic en la pestaña Clave API . Su clave API secreta estará inicialmente oculta. Para verla, haga clic en el botón Mostrar . Una vez sea visible, copie su clave API secreta. Utilice esta clave para realizar llamadas a la API.
Debe tener la URL base del punto de conexión de la API. Por ejemplo, https://staging-test.citrusad.com/v1/ads/generate HTTP/1.1. Consulte a su gestor técnico de cuentas para conocer la URL base.

Contexto estándar para añadir productos

Una vez creado el catálogo, puede sincronizar los productos con él mediante la API. En el ejemplo a continuación se muestra el contexto estándar para añadir productos.

Solicitar parámetros

A continuación se muestran los parámetros de consulta y cuerpo:

Parámetro de consulta

objeto	tipo	Descripción
ID de equipo	cadena, opcional	ID de su equipo. Si no se indica un `teamId` , se utilizará de forma predeterminada `teamId` el especificado en la autenticación.

Parámetro de cuerpo

objeto	tipo	Descripción
ID del catálogo	cadena, obligatorio	Identificador del catálogo al que pertenece el producto.
gtin	cadena, obligatorio	Número de artículo comercial mundial (GTIN) del producto.
inventario	número, opcional	Recuento de inventario para el producto.
precio	número, opcional	Precio del producto.
jerarquía de categorías	matriz de cadenas, opcional	Jerarquía de las categorías a las que pertenece el producto.
Etiquetas:	matriz de cadenas, opcional	Etiquetas asociadas al producto.
filtros	matriz de cadenas, opcional	Filtros aplicados al producto.

Ejemplo de solicitud

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

Solicitud de respuesta

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

Actualizar información de ubicación

También puede actualizar los filtros para varias ubicaciones de tiendas donde sus productos están disponibles. Esta función es útil para optimizar la información del producto a nivel de tienda o ubicación.

Ejemplo de solicitud

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

Ejemplo de respuesta

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

Actualizar información HFSS

Para incluir información de HFSS (alto contenido en grasas, azúcar y sal) en la actualización de su producto, debe enviar un filtro con el valor hfss:true o el hfss:false. Esto permite a Epsilon Retail Media filtrar adecuadamente la interfaz en función de los criterios HFSS.

Ejemplo de solicitud

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

Añadir varios productos

Al actualizar varios productos, puede procesar hasta 100 artículos por solicitud. En el ejemplo a continuación se muestra el contexto para actualizar dos productos.

Ejemplo de solicitud

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

Solicitud de respuesta

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

Añadir filtros de productos

En el proceso de generación de anuncios a través de la API de CitrusAd, es posible que desee aplicar filtros de productos para refinar los resultados. Esto se puede lograr mediante la inclusión de un campo de productFilters en su solicitud POST. El campo productFilters es una matriz que contiene una o más submatrices, cada una de las cuales representa un filtro diferente.

Ejemplo de solicitud

A continuación, se muestra un ejemplo de una solicitud POST al endpoint /v1/ads/generate que incluye 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
}

En este ejemplo,

Se incluyen dos filtros de producto category:Cupboard y dietary:Gluten-free. La opción filterMode se establece en AndOr, lo que significa que la API devolverá anuncios de productos que coincidan con ambos filtros.
Los anuncios devueltos solo incluirán productos que pertenezcan a la categoría «Despensa» y que también sean «Sin gluten». El número de anuncios devueltos no superará el especificado maxNumberOfAds, que se establece en 3 en este ejemplo.

Con el uso correcto de productFilters, puede personalizar eficazmente los resultados de los anuncios para que se adapten mejor a las necesidades de su campaña.

Incluir imágenes y nombres de productos esenciales

Para mejorar la capacidad de búsqueda durante el proceso de creación de campañas en el portal CitrusAd, proporcione imágenes y nombres de productos. Asigne los valores de las imágenes y los nombres dentro de las etiquetas correspondientes. Estos valores se envían a CitrusAd.

Ejemplo de solicitud

A continuación, se muestra un ejemplo de una solicitud POST al endpoint /v1/catalog-products endpoint que incluye imágenes y nombres de productos:

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

En la solicitud de ejemplo anterior, el campo de etiquetas incluye dos datos clave, la URL de la imagen y el nombre del producto. imageurl y name son las claves y cada una de ellas va seguida de sus respectivos valores.

imageurl: https://your.image.host.com/image.jpg indica la URL donde se aloja la imagen del producto.
name: Covergirl Clean 120 Creamy Natural Liquid Foundation 30mL indica el nombre del producto.