> 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/pt-br/generating-ads/product-ads/requesting-product-ads-1.md). # Solicitando anúncios de produto ## Solicitando anúncios Todas as solicitações de anúncios de produtos exigem o contexto do `placement`, e `catalogId`, bem como o `maxNumberOfAds` que você gostaria de exibir para o cliente. Além disso, sua solicitação deve incluir o contexto do `customerId` e `sessionId`. ### Posicionamentos de busca Os posicionamentos de busca são tipicamente os mais fáceis de solicitar. Eles exigem que um `searchTerm` seja especificado na solicitação, como no exemplo abaixo: ```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 } ``` ### Posicionamentos de categoria Os posicionamentos de categoria exigem que `productFilters` sejam especificados na solicitação. O exemplo abaixo mostra onde você enviaria os filtros de categoria: ```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 } ``` À medida que categorias adicionais são examinadas, você precisa atualizar sua chamada de API de acordo. {% hint style="info" %} Melhor prática É uma melhor prática enviar o nível mais baixo de categoria na sua solicitação de anúncio para Epsilon Retail Media à medida que os clientes navegam em categorias mais profundas. Em vez de especificar uma solicitação encadeada no nível 3 de L1 + L2 + L3, você especificaria apenas a categoria L3. {% endhint %} ### Posicionamentos de categoria de venda cruzada Os posicionamentos de categoria de venda cruzada têm uma solicitação muito semelhante aos posicionamentos de categoria. Você desejará especificar a categoria exata para a qual está solicitando anúncios. Essa é tipicamente a página em que você está. Especifique a categoria no `productFilters` da solicitação. O exemplo abaixo mostra onde você enviaria os filtros de categoria: ```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 } ``` À medida que categorias adicionais são examinadas, você precisa atualizar sua chamada de API de acordo. {% hint style="info" %} Mesclando direcionamento de categoria orgânica e de venda cruzada? Se você deseja mesclar uma solicitação de anúncio de categoria orgânica e de venda cruzada em um único posicionamento, precisará implementar a lógica de mesclagem e entrega para seus clientes. Essa é uma responsabilidade do integrador, embora Epsilon Retail Media estão felizes em ser consultados. Em geral, aconselhamos que você exiba anúncios de categoria orgânica e posicione anúncios de venda cruzada de categoria após os posicionamentos orgânicos. {% endhint %} ### Posicionamentos de correspondência ampla Posicionamentos amplos, como páginas iniciais ou de checkout, não exigem que nenhum `productFilters` seja especificado na solicitação. Quaisquer filtros que o varejista gostaria de especificar (em oferta, novo, etc.) podem ser especificados no `productFilters` para garantir que Epsilon Retail Media veiculem anúncios apenas dentro dos 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 } ``` ### Melhorias de solicitação Em posicionamentos de busca, categoria e correspondência ampla, aconselhamos você a considerar as melhorias abaixo para aprimorar sua experiência do usuário. #### Paginando solicitações Ao gerar anúncios de produtos, você receberá um `memoryToken` que pode ser enviado em solicitações subsequentes para excluir anúncios veiculados anteriormente. Você pode então enviar este `memoryToken` em uma solicitação de anúncio subsequente, e Epsilon Retail Media excluirá qualquer anúncio veiculado anteriormente para o mesmo contexto de nossa resposta de anúncio. Por favor, revise [Paginação](/retail-media-interface/integration/pt-br/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 } ``` #### Buscas filtradas Se o seu cliente filtrar a busca dele, você pode estender seu contexto para fornecer `productFilters`. Abaixo está um exemplo em que o cliente está filtrando pela categoria "Armário" e pela restrição alimentar "Sem glúten". Esse mesmo princípio pode ser aplicado a qualquer posicionamento de categoria ou correspondência ampla. ```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 } ``` #### Filtrando por localização Se você estiver sincronizando filtros de localização em seu catálogo, poderá estender seu contexto para fornecer a localização da loja do cliente no `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 } ``` ## A resposta do anúncio de produto Todas as respostas de anúncios de produtos seguem o mesmo formato JSON. Os anúncios de produtos são retornados no `ads` array, como no exemplo abaixo: ```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=" } ``` O `id` campo é o seu ID de anúncio usado em relatórios de impressões e cliques. O `position` campo define a posição no Epsilon Retail Media payload. Consulte a referência para obter mais informações sobre cada string. {% hint style="info" %} Você deve ler e honrar o `position` campo para garantir que os posicionamentos de posicionamento fixo apareçam corretamente. {% endhint %} ### sellerId de Marketplace Se estiver integrando vendedores de marketplace, você poderá ver um `sellerId` adicional por anúncio na resposta. Isso só aparecerá se a equipe proprietária da campanha sendo veiculada tiver um ID de vendedor configurado na UI. O exemplo abaixo mostra um anúncio com um sellerId e um sem. ```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" %} Se você não tiver certeza sobre as strings nesta seção, visite a página de [Referência de anúncio de produto](/retail-media-interface/integration/pt-br/references/product-ad-reference-1.md) . {% endhint %} ## Digital Services Act Epsilon Retail Media ajuda os varejistas a cumprirem suas obrigações da União Europeia (UE) [Digital Services Act](https://commission.europa.eu/strategy-and-policy/priorities-2019-2024/europe-fit-digital-age/digital-services-act_en) (DSA). A DSA estabelece um conjunto unificado de regras em toda a UE, visando a regulamentação de conteúdo online, publicidade transparente e desinformação. Para obter mais informações, consulte [Digital Services Act](/retail-media-interface/integration/pt-br/feature-integrations/digital-services-act.md). ### Exemplo de solicitação de anúncio ``` { "placement": "search-only", "catalogId": "zesty-fruits-catalog", "searchTerm": "lime", "maxNumberOfAds": 5, "options": { "filterMode": "AndOr", "includeAdvertiserInfo": true, }, } ``` ### Exemplo de resposta de anúncio ``` { "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/pt-br/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.