> For the complete documentation index, see [llms.txt](https://help.citrusad.com/retail-media-interface/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.citrusad.com/retail-media-interface/integration/es/generating-ads/product-ads/requesting-product-ads-1.md). # Solicitar anuncios de productos ## Solicitud de anuncios Todas las solicitudes de anuncios de productos requieren la información de contexto `placement`, y `catalogId`, así como el `maxNumberOfAds` que te gustaría mostrar al cliente. Además, tu solicitud debe incluir la información de contexto `customerId` y `sessionId`. ### Ubicaciones de búsqueda Las ubicaciones de búsqueda suelen ser las más fáciles de solicitar. Requieren que se especifique un `searchTerm` en la solicitud, como en el siguiente ejemplo: ```http POST $BASE_URL/v1/ads/generate HTTP/1.1 accept: application/json content-type: application/json Authorization: Basic { "customerId": "wertg5432a", "sessionId": "ec9-4e07-881d-3e9", "dtmCookieId": "AAAF8xLBTA968AB6TOthAAAAAAE", "placement": "search", "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b", "searchTerm": "chocolate", "options": { "filterMode": "AndOr" }, "maxNumberOfAds": 3 } ``` ### Ubicaciones de categoría Las ubicaciones de categoría requieren que se especifique `productFilters` en la solicitud. El siguiente ejemplo muestra dónde enviarías los filtros de categoría: ```http POST $BASE_URL/v1/ads/generate HTTP/1.1 accept: application/json content-type: application/json Authorization: Basic { "customerId": "wertg5432a", "sessionId": "ec9-4e07-881d-3e9", "dtmCookieId": "AAAF8xLBTA968AB6TOthAAAAAAE", "placement": "category", "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b", "productFilters": [ ["category:Cupboard/Snacks"] ], "options": { "filterMode": "AndOr" }, "maxNumberOfAds": 3 } ``` A medida que se examinan categorías adicionales, debes actualizar tu llamada a la API en consecuencia. {% hint style="info" %} Buenas prácticas Se considera una buena práctica enviar el nivel más bajo de categoría en tu solicitud de anuncio para Epsilon Retail Media a medida que los clientes navegan por categorías más profundas. En lugar de especificar una solicitud encadenada en el nivel 3 de L1 + L2 + L3, solo especificarías la categoría L3. {% endhint %} ### Ubicaciones de categoría de venta cruzada Las ubicaciones de categoría de venta cruzada tienen una solicitud muy similar a las ubicaciones de categoría. Deberás especificar la categoría exacta para la que estás solicitando anuncios. Por lo general, esta es la página en la que te encuentras. Especifica la categoría en el `productFilters` de la solicitud. El siguiente ejemplo muestra dónde enviarías los filtros de categoría: ```http POST $BASE_URL/v1/ads/generate HTTP/1.1 accept: application/json content-type: application/json Authorization: Basic { "customerId": "wertg5432a", "sessionId": "ec9-4e07-881d-3e9", "dtmCookieId": "AAAF8xLBTA968AB6TOthAAAAAAE", "placement": "category-cross-sell", "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b", "productFilters": [ ["category:Cupboard/Snacks"] ], "options": { "filterMode": "AndOr" }, "maxNumberOfAds": 3 } ``` A medida que se examinan categorías adicionales, debes actualizar tu llamada a la API en consecuencia. {% hint style="info" %} ¿Combinar la segmentación por categoría orgánica y de venta cruzada? Si deseas combinar una solicitud de anuncios de categoría orgánica y de venta cruzada en una sola ubicación, deberás implementar una lógica de combinación y entrega para tus clientes. Esto es responsabilidad del integrador, aunque Epsilon Retail Media está a tu disposición para consultas. En general, recomendamos mostrar anuncios de categoría orgánica y posicionar los anuncios de venta cruzada de categoría y posición después de las ubicaciones orgánicas. {% endhint %} ### Ubicaciones de concordancia amplia Las ubicaciones amplias, como la página de inicio o la de pago, no requieren que se especifique ningún `productFilters` en la solicitud. Cualquier filtro que el vendedor desee especificar (en oferta, nuevo, etc.) se puede especificar en el `productFilters` para garantizar que Epsilon Retail Media solo sirva anuncios que cumplan con los requisitos. ```http POST $BASE_URL/v1/ads/generate HTTP/1.1 accept: application/json content-type: application/json Authorization: Basic { "customerId": "wertg5432a", "sessionId": "ec9-4e07-881d-3e9", "dtmCookieId": "AAAF8xLBTA968AB6TOthAAAAAAE", "placement": "home", "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b", "productFilters": [ [] ], "options": { "filterMode": "AndOr" }, "maxNumberOfAds": 3 } ``` ### Mejoras de solicitud En ubicaciones de búsqueda, categoría y concordancia amplia, te aconsejamos considerar las siguientes mejoras para enriquecer la experiencia del usuario. #### Paginación de solicitudes Al generar anuncios de productos, recibirás un `memoryToken` que se puede enviar en solicitudes posteriores para excluir anuncios mostrados anteriormente. Luego puede enviar esto `memoryToken` en una solicitud de anuncio posterior, y Epsilon Retail Media excluirá cualquier anuncio mostrado anteriormente para el mismo contexto de nuestra respuesta de anuncios. Por favor revise [Paginación](/retail-media-interface/integration/es/feature-integrations/pagination.md) antes de implementar. ```http POST $BASE_URL/v1/ads/generate HTTP/1.1 accept: application/json content-type: application/json Authorization: Basic { "customerId": "wertg5432a", "sessionId": "ec9-4e07-881d-3e9", "dtmCookieId": "AAAF8xLBTA968AB6TOthAAAAAAE", "placement": "search", "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b", "searchTerm": "chocolate", "memoryToken":"85ykKVv-luDHMWLZx2d6xcPq6sF7CgkJCSJDb3VudGVyIjogIjIiLAoJCQkiQWRzIjogWwoJCQkJImRpc3BsYXlfV05VV0NwQkRKMUpKNm5wdVZSVExvOU40TUxzNE1UWTBOemt5TWc9PSIsCgkJCQkiZGlzcGxheV9MME5NUHRxNmdCcVFvREJOd3J0dE9UTGJoWk0xTVRFeU9UYzRPUT09IiwKCQkJCSJkaXNwbGF5XzlCcEpmdUpaWk9VXzgyaWpFM3VCczgxd3VVczRNekkwTnpVeE5nPT0iLAoJCQkJImRpc3BsYXlfcW1VU1p4TkpMQ0lqeWQwdTFJRDk0RmxVZ0pnNE16STBOelV4Tnc9PSIsCgkJCQkiZGlzcGxheV9oeHlFZktCUnRrNWlxMThMQzE1SDJHcEN3QjgxTVRFeU9UYzVNQT09IiwKCQkJCSJkaXNwbGF5X1NkcjFEcU5aUEFtcGh0Q1FIUndoYUxFT1B0RXhNamsxT1RJNE5BPT0iLAoJCQkJImRpc3BsYXlfeVlSai1qV2Ntc2ozNzhrel9PMm0yOVlwTjhJeE5EazNPRE00TXc9PSIsCgkJCQkiZGlzcGxheV9Xbm9NZGZuLTRTVmhxcF9xQzVvLWxoT0paNm8xTkRJeE1UUTROdz09IgoJCQldLAoJCQkiVFRMIjogMTYyODk4NTYwMAoJCX0=", "options": { "filterMode": "AndOr" }, "maxNumberOfAds": 3 } ``` #### Búsquedas filtradas Si su cliente filtra su búsqueda, puede ampliar su contexto para proporcionar `productFilters`. A continuación se muestra un ejemplo donde el cliente está filtrando por la categoría "Cupboard" y la restricción dietética "Gluten-free". Este mismo principio se puede aplicar a cualquier categoría o ubicación de coincidencia amplia. ```http POST $BASE_URL/v1/ads/generate HTTP/1.1 accept: application/json content-type: application/json Authorization: Basic { "customerId": "wertg5432a", "sessionId": "ec9-4e07-881d-3e9", "dtmCookieId": "AAAF8xLBTA968AB6TOthAAAAAAE", "placement": "search", "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b", "searchTerm": "chocolate", "productFilters": [ ["category:Cupboard"],["dietary:Gluten-free"] ], "options": { "filterMode": "AndOr" }, "maxNumberOfAds": 3 } ``` #### Filtrado por ubicación Si está sincronizando filtros de ubicación en su catálogo, puede ampliar su contexto para proporcionar la ubicación de la tienda del cliente en el `productFilters`: ```http POST $BASE_URL/v1/ads/generate HTTP/1.1 accept: application/json content-type: application/json Authorization: Basic { "customerId": "wertg5432a", "sessionId": "ec9-4e07-881d-3e9", "dtmCookieId": "AAAF8xLBTA968AB6TOthAAAAAAE", "placement": "search", "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b", "searchTerm": "chocolate", "productFilters": [ ["category:Cupboard"],["dietary:Gluten-free"],["location:Westenbury"] ], "options": { "filterMode": "AndOr" }, "maxNumberOfAds": 3 } ``` ## La respuesta del anuncio de producto Todas las respuestas de anuncios de productos siguen el mismo formato JSON. Los anuncios de productos se devuelven en el `ads` array, como en el ejemplo a continuación: ```json { "ads": [ { "id": "display_QqHaKRrKlFm1Wxr9c_DXJN4HSE3NzMzNjM2", "gtin": "7733636", "discount": { "amount": 0, "minPrice": 0, "maxPerCustomer": 0 }, "expiry": "2021-05-12T04:17:50.400902957Z", "position": 1 }, { "id": "display_NzsHqP0_iQedlo9VnrO2vqkwi_k3NzMzNjI4", "gtin": "7733628", "discount": { "amount": 0, "minPrice": 0, "maxPerCustomer": 0 }, "expiry": "2021-05-12T04:17:50.400908257Z", "position": 2 }, { "id": "display_xNeShqidaMuEqiJ0zNdt-Gzygjs3NzE0MTA3", "gtin": "7714107", "discount": { "amount": 0, "minPrice": 0, "maxPerCustomer": 0 }, "expiry": "2021-05-12T04:17:50.400912929Z", "position": 3 }, { "id": "display_3rGiryPskhQusmsf43nghbQwnqo3NzMzNjU3", "gtin": "7733657", "discount": { "amount": 0, "minPrice": 0, "maxPerCustomer": 0 }, "expiry": "2021-05-12T04:17:50.400917769Z", "position": 4 } ], "banners": [], "products": [], "memoryToken":"85ykKVv-luDHMWLZx2d6xcPq6sF7CgkJCSJDb3VudGVyIjogIjIiLAoJCQkiQWRzIjogWwoJCQkJImRpc3BsYXlfV05VV0NwQkRKMUpKNm5wdVZSVExvOU40TUxzNE1UWTBOemt5TWc9PSIsCgkJCQkiZGlzcGxheV9MME5NUHRxNmdCcVFvREJOd3J0dE9UTGJoWk0xTVRFeU9UYzRPUT09IiwKCQkJCSJkaXNwbGF5XzlCcEpmdUpaWk9VXzgyaWpFM3VCczgxd3VVczRNekkwTnpVeE5nPT0iLAoJCQkJImRpc3BsYXlfcW1VU1p4TkpMQ0lqeWQwdTFJRDk0RmxVZ0pnNE16STBOelV4Tnc9PSIsCgkJCQkiZGlzcGxheV9oeHlFZktCUnRrNWlxMThMQzE1SDJHcEN3QjgxTVRFeU9UYzVNQT09IiwKCQkJCSJkaXNwbGF5X1NkcjFEcU5aUEFtcGh0Q1FIUndoYUxFT1B0RXhNamsxT1RJNE5BPT0iLAoJCQkJImRpc3BsYXlfeVlSai1qV2Ntc2ozNzhrel9PMm0yOVlwTjhJeE5EazNPRE00TXc9PSIsCgkJCQkiZGlzcGxheV9Xbm9NZGZuLTRTVmhxcF9xQzVvLWxoT0paNm8xTkRJeE1UUTROdz09IgoJCQldLAoJCQkiVFRMIjogMTYyODk4NTYwMAoJCX0=" } ``` El `id` campo es el ID de su anuncio utilizado en los informes de impresiones y clics. El `position` campo define la posición en el Epsilon Retail Media payload. Por favor, consulte la referencia para obtener más información sobre cada cadena. {% hint style="info" %} Debe leer y respetar el `position` campo para garantizar que las ubicaciones de Ubicación fija aparezcan correctamente. {% endhint %} ### Marketplace sellerId Si está registrando vendedores de marketplace, es posible que vea un `sellerId` adicional por anuncio en la respuesta. Esto solo aparecerá si el equipo propietario de la campaña que se está sirviendo tiene un ID de vendedor configurado en la UI. El siguiente ejemplo muestra un anuncio con un sellerId y uno sin él. ```json { "ads": [ { "id": "display_QqHaKRrKlFm1Wxr9c_DXJN4HSE3NzMzNjM2", "gtin": "7733636", "discount": { "amount": 0, "minPrice": 0, "maxPerCustomer": 0 }, "expiry": "2021-05-12T04:17:50.400902957Z", "position": 1 }, { "id": "display_NzsHqP0_iQedlo9VnrO2vqkwi_k3NzMzNjI4", "gtin": "7733628", "sellerId": "2834-ascre-2wcr4", "discount": { "amount": 0, "minPrice": 0, "maxPerCustomer": 0 }, "expiry": "2021-05-12T04:17:50.400908257Z", "position": 2 } ], "banners": [], "products": [], "memoryToken":"85ykKVv-luDHMWLZx2d6xcPq6sF7CgkJCSJDb3VudGVyIjogIjIiLAoJCQkiQWRzIjogWwoJCQkJImRpc3BsYXlfV05VV0NwQkRKMUpKNm5wdVZSVExvOU40TUxzNE1UWTBOemt5TWc9PSIsCgkJCQkiZGlzcGxheV9MME5NUHRxNmdCcVFvREJOd3J0dE9UTGJoWk0xTVRFeU9UYzRPUT09IiwKCQkJCSJkaXNwbGF5XzlCcEpmdUpaWk9VXzgyaWpFM3VCczgxd3VVczRNekkwTnpVeE5nPT0iLAoJCQkJImRpc3BsYXlfcW1VU1p4TkpMQ0lqeWQwdTFJRDk0RmxVZ0pnNE16STBOelV4Tnc9PSIsCgkJCQkiZGlzcGxheV9oeHlFZktCUnRrNWlxMThMQzE1SDJHcEN3QjgxTVRFeU9UYzVNQT09IiwKCQkJCSJkaXNwbGF5X1NkcjFEcU5aUEFtcGh0Q1FIUndoYUxFT1B0RXhNamsxT1RJNE5BPT0iLAoJCQkJImRpc3BsYXlfeVlSai1qV2Ntc2ozNzhrel9PMm0yOVlwTjhJeE5EazNPRE00TXc9PSIsCgkJCQkiZGlzcGxheV9Xbm9NZGZuLTRTVmhxcF9xQzVvLWxoT0paNm8xTkRJeE1UUTROdz09IgoJCQldLAoJCQkiVFRMIjogMTYyODk4NTYwMAoJCX0=" } ``` {% hint style="info" %} Si no está seguro sobre las cadenas de esta sección, por favor visite la [Referencia de anuncios de productos](/retail-media-interface/integration/es/references/product-ad-reference-1.md) página. {% endhint %} ## Ley de Servicios Digitales Epsilon Retail Media ayuda a los minoristas a cumplir con sus obligaciones en la Unión Europea (UE) [Ley de Servicios Digitales](https://commission.europa.eu/strategy-and-policy/priorities-2019-2024/europe-fit-digital-age/digital-services-act_en) (DSA). La DSA establece un conjunto unificado de normas en toda la UE, orientadas a la regulación de contenidos en línea, publicidad transparente y desinformación. Para más información, consulte [Ley de Servicios Digitales](/retail-media-interface/integration/es/feature-integrations/digital-services-act.md). ### Ejemplo de solicitud de anuncio ``` { "placement": "search-only", "catalogId": "zesty-fruits-catalog", "searchTerm": "lime", "maxNumberOfAds": 5, "options": { "filterMode": "AndOr", "includeAdvertiserInfo": true, }, } ``` ### Ejemplo de respuesta de anuncio ``` { "ads": [ { "id": "display_QqHaKRrKlFm1Wxr9c_DXJN4HSE3NzMzNjM2", "gtin": "7733636", "discount": { "amount": 0, "minPrice": 0, "maxPerCustomer": 0 }, "expiry": "2021-05-12T04:17:50.400902957Z", "position": 1, "metadata": { "advertiserInfo": { "advertiser": "Bob's advertising agency", "onBehalfOf": "Brand company inc", } } }, .... ], "banners": [], "products": [], "memoryToken": "85ykKVv-………" } ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://help.citrusad.com/retail-media-interface/integration/es/generating-ads/product-ads/requesting-product-ads-1.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.