> 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/feature-integrations/category-cross-sell/integration-requirements.md).

# Requisitos de integração

## Visão geral de alto nível

Como parte desta integração, você precisará fazer o seguinte

1. Implementar uma solicitação de anúncio adicional para o posicionamento de venda cruzada por categoria.
   1. Isso inclui o trabalho para posicionar e renderizar anúncios em seu site, bem como relatar cliques e impressões
   2. Os pedidos precisam ser fornecidos para Epsilon Retail Media como parte de sua integração padrão
2. Se você sincronizar IDs de categoria com Epsilon Retail Media, você precisará usar a [filterMapping](/retail-media-interface/integration/pt-br/citrus-filter-mapping-api/filtermapping.md) API para fornecer valores legíveis por humanos para a seleção de categoria na UI
   1. Isso se aplica apenas se você estiver integrado com IDs de categoria em vez de nomes. (como quando você solicita anúncios, seus filtros são `category:123j-dsef-er` em vez de `category:Milk`
3. (Aconselhado) - sincronize os mapeamentos de venda cruzada de categorias para automatizar a aprovação e reduzir a carga de gerenciamento de campanhas.

## Solicitação de anúncio e integração do site

### Solicitação de anúncio

Como a venda cruzada por categoria requer um posicionamento independente, você precisará integrar uma solicitação de anúncio adicional por tipo de anúncio para o qual está integrando a venda cruzada por categoria.

O formato da sua solicitação deve corresponder à solicitação de anúncio de categoria de venda cruzada conforme listado abaixo

* [Anúncio de produto - solicitando anúncios de venda cruzada por categoria](/retail-media-interface/integration/pt-br/generating-ads/product-ads/requesting-product-ads-1.md#cross-sell-category-placements)
* [Anúncio de banner - solicitando anúncios de venda cruzada por categoria](/retail-media-interface/integration/pt-br/generating-ads/banner-ads-static/requesting-banner-ads.md#cross-sell-category-placements)
* Banner X - solicitando anúncios de venda cruzada por categoria

### Relatando impressões e cliques

Depois de integrar sua solicitação de anúncio, você também precisará garantir que está relatando cliques e impressões corretamente para cada anúncio exibido. Certifique-se de ler [Relatando impressões e cliques](/retail-media-interface/integration/pt-br/data-api/api-overview/reporting-impressions-clicks.md).

### Relatando pedidos

Geralmente, a maioria das integrações relata todas as informações de pedidos para Epsilon Retail Media conforme uma integração padrão. Você precisa garantir que está relatando todos os pedidos corretamente para Epsilon Retail Media conforme [Dados do pedido](/retail-media-interface/integration/pt-br/data-api/order-data-1.md).

## Mapeamentos de filtro

O endpoint de mapeamento de filtro pode ser usado para mapear seus IDs de categoria para valores legíveis por humanos. Isso é necessário se você sincronizar IDs de categoria, pois a UI mostra os valores para seus usuários.

{% hint style="info" %}
Se você sincronizar categorias legíveis por humanos em seu catálogo de produtos com Epsilon Retail Media, esta etapa não será necessária.
{% endhint %}

Os usuários não entenderão o que `category:12345-abcde` é. A API filterMapping pode ser usada para mapear o valor para o nome da categoria relevante em seu site, como `category:Pantry`.

Não há método baseado em arquivo para sincronizar essas informações, isso deve ser feito por meio da [filterMapping](/retail-media-interface/integration/pt-br/citrus-filter-mapping-api/filtermapping.md) API.

{% hint style="warning" %}
À medida que você cria categorias adicionais em seu site, precisará garantir que a API filterMapping seja usada para atualizar as categorias.
{% endhint %}

## Mapeamentos de venda cruzada por categoria (aconselhado)

É fortemente aconselhado, ao integrar esse tipo de posicionamento, fornecer um mapeamento de quais categorias têm permissão para direcionar umas às outras. Isso pode agilizar suas operações após o trabalho inicial de integração. A experiência do anunciante é simplificada para permitir apenas categorias que já têm permissão para serem selecionadas.

Além disso, também é possível configurar a aprovação automática para campanhas de venda cruzada por categoria, quando mapeamentos de venda cruzada são fornecidos.

### Métodos de integração

* Você pode usar a [crossSellCategory](/retail-media-interface/integration/pt-br/crosssellcategory-api/crosssellcategory.md) API para criar e gerenciar mapeamentos conforme necessário.
* Como alternativa, você pode fornecer um arquivo TSV para um bucket do GCS hospedado por Epsilon Retail Media com o formato listado abaixo.

#### Integração por API

Todas as informações necessárias podem ser vistas na [crossSellCategory](/retail-media-interface/integration/pt-br/crosssellcategory-api/crosssellcategory.md) Referência da API.

#### Integração por arquivo

Se integrar por arquivo, Epsilon Retail Media requer um arquivo por catálogo, de quais categorias têm permissão para direcionar entre si.

Cada linha no arquivo representa um único mapeamento de uma categoria e a categoria que ela pode direcionar. Cada mapeamento é unidirecional (se você sincronizar chocolate -> leite, os produtos de chocolate podem aparecer na categoria leite. Se os produtos de leite precisarem aparecer em chocolate, uma linha adicional será necessária).

Precisamos de um feed de dados no formato TSV alinhado com as especificações abaixo:

| nome da coluna      | Obrigatório | Tipo de dados | Descrição                                                                                                                                          | Exemplo            |
| ------------------- | ----------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
| `category`          | Obrigatório | Texto         | Este é um ID de categoria exclusivo que identifica a categoria do produto anunciado.                                                               | `category:cookies` |
| `cross_category_id` | Obrigatório | Texto         | Este é um ID de categoria exclusivo que identifica uma categoria elegível na qual os produtos de category\_id podem ser vendidos de forma cruzada. | `category:milk`    |

Especificações adicionais do arquivo estão abaixo:

* Arquivos TSV são suportados apenas
* O TSV deve estar em LF, não em CRLF
* O TSV deve ter codificação UTF-8, qualquer tipo causará falha no feed
* Convenção de nomenclatura necessária: `^cross_sell_category.*.tsv$`

Um trecho de exemplo é como o abaixo:

| category         | cross\_category\_id |
| ---------------- | ------------------- |
| category:cookies | categoria:leite     |
| category:cookies | categoria:chocolate |
| categoria:leite  | category:cookies    |

Este trecho acima permite que a categoria **cookies** faça cross-sell nas categorias **leite** e **chocolate**. A categoria **leite** pode fazer cross-sell na categoria **cookies**. A categoria **chocolate** pode ser direcionada, mas não pode direcionar para nenhuma outra categoria.

{% hint style="danger" %}
️ Cada linha é uma combinação de mapeamento exclusiva

Você precisa sincronizar linhas exclusivas para cada mapeamento exclusivo de categoria de cross-sell. Se tentar sincronizar múltiplos cross\_category\_id em uma única linha, a ingestão do arquivo falhará.
{% endhint %}

{% hint style="warning" %}
Ordem das colunas

Certifique-se de que seu arquivo tenha a `category` coluna como a primeira coluna. Se você sincronizar `cross_category_id` como a primeira coluna, a ingestão falhará.
{% endhint %}

## Processo de ativação do recurso

Assim que estiver pronto para começar a sincronizar seu feed de termos de busca sugeridos, Epsilon Retail Media configurará um bucket do GCS para você enviar seus arquivos.

Esta funcionalidade é suportada apenas em buckets do GCS. Buckets externos como AWS/Azure/outros não são suportados.

Seu Technical Account Manager poderá guiá-lo através da ativação deste recurso. Como Epsilon Retail Mediaa equipe de operações da plataforma precisa executar uma configuração, esteja ciente de que há um prazo de entrega adicional para a ativação.


---

# 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/feature-integrations/category-cross-sell/integration-requirements.md?ask=<question>&goal=<endgoal>
```

`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.