> 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/partner/pt-br/partner-api-overview/campaign-field-definitions.md).
# Definições dos campos da campanha
## Campos comuns de campanha
Esta seção fornece descrições breves e exemplos para ajudar você a entender os campos comuns de campanha em diferentes tipos, como anúncios de produtos, banners e banner X. Cada entrada inclui a finalidade do campo e um exemplo de implementação representativo para sua plataforma.
| Campo | Finalidade e exemplo |
| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | Recomenda-se incluir detalhes como o produto promovido, o período ou a estratégia, como 'Queima de Estoque de Chocolates Cadbury em Junho', para ajudar a identificar a campanha facilmente. O nome pode ter até 255 caracteres. |
| `namespaceId` | O identificador exclusivo do seu namespace, localizado na URL base. Por exemplo, em exampleretailer.citrusad.com, o namespaceId is exampleretailer.
Certifique-se de que o recurso exista para o ID fornecido como namespace.
|
| `approval.state` | O estado de aprovação da campanha só pode usar valores enum especificados. Os estados suportados são APPROVAL\_STATE\_APPROVED, APPROVAL\_STATE\_REJECTED, APPROVAL\_STATE\_PENDING.
Observe queAPPROVAL\_STATE\_UNSPECIFIED não pode ser usado.
|
| `approval.rejectionReason` | O motivo pelo qual uma campanha foi rejeitada. Este é um campo obrigatório se o status for `APPROVAL_STATE_REJECTED`. |
| `campaignState` | O estado ativo da campanha indica se ela está ativa, pausada, em rascunho ou arquivada. Por exemplo, CAMPAIGN\_STATE\_ACTIVE, CAMPAIGN\_STATE\_DRAFT, CAMPAIGN\_STATE\_UNSPECIFIED.
Observe que CAMPAIGN\_STATE\_UNSPECIFIED não pode ser usado.
|
| `teamId` | O teamId é o identificador exclusivo da equipe da campanha.
Certifique-se de que o recurso exista para o ID de equipe fornecido e não esteja com o sinalizador de arquivado ativado. Além disso, o ID da equipe do modelo deve corresponder ao ID da equipe da campanha.
|
| `startTime` | O horário de início da campanha usando um carimbo de data/hora preciso no formato ISO-8601. Por exemplo, 2024-09-01T12:00:00Z.
Omita este valor para campanhas always on campanhas.
|
| `endTime` | O horário de término da campanha usa um carimbo de data/hora preciso no formato ISO-8601 e deve ser definido se startTime for especificado. Por exemplo, 2024-09-30T23:59:59Z. O horário de término deve ser posterior ao horário de início.
Omita este valor para campanhasalways on campanhas.
|
| `walletId` | O identificador exclusivo da carteira a ser cobrada pela campanha, por exemplo, wallet\_123456789.
- If campaignType não for 'Wildcard', um objeto deve existir para o ID.
- O ID da equipe da carteira deve corresponder ao ID da equipe da campanha.
- O código de moeda da carteira deve corresponder ao código de moeda do catálogo da campanha. Se não tiver certeza disso, consulte seu Engenheiro de Integração de Clientes (CIE).
|
| `placementId` | O identificador exclusivo do posicionamento da campanha. Por exemplo, placement\_987654321.
Certifique-se de que o recurso exista para o ID de posicionamento fornecido e corresponda à campanha correta.
|
| `catalogIds` | O identificador exclusivo do(s) catálogo(s) do varejista. Por exemplo, \["329f1e08-d3ee-4e04-90c4-068b3ce6b856","6c29a96a-f55a-497f-b03a-2fed85dd7198" ].
Certifique-se de que o recurso exista para o ID de catálogo fornecido e corresponda à campanha correta.
|
| `advertisedProducts.
productsByKey` | As combinações de códigos de produtos e IDs de catálogo que estão sendo anunciadas na campanha. Se uma campanha aparecer em dois catálogos, forneça dois pares de catálogo-produto.
Por exemplo, \[{"catalogId": "14edbbc5-a7be-4c54-9f35-767b4ee29fd3","productCode": "ABC123"}].
|
| `targeting.searchTerms` | Os termos de pesquisa e seus tipos de correspondência que a campanha direcionará. Inclua estas informações apenas para posicionamentos de pesquisa. Por exemplo, `{"matchType": "MATCH_TYPE_EXACT_MATCH","phrase": "string"}`}. |
| `targeting.excludeFilters` | Filtros para excluir durante a etapa de direcionamento, que devem ser apenas filtros de localização ou categoria alinhados ao seu filterClassIdA maioria das integrações pode omitir esses valores. Se estiver usando duas classes de filtro, especifique um objeto por classe de filtro:
{"excludeFilters": \[ \
{ \
"catalogId": "76df36b4-45a2-46a5-9308-3dd14861d76e", \
"filter": "category:chocolate" \
}, \
{ \
"catalogId": "76df36b4-45a2-46a5-9308-3dd14861d76e", \
"filter": "location:florida" \
} \
] \
}
|
| `targeting.includeFilters` | Filtros explícitos a serem direcionados pela campanha. Omita isso para integrações padrão. Preencha este campo apenas se aconselhado ou ao criar campanhas de posicionamento fixo.
{"includeFilters": \[ \
{ \
"catalogId": "76df36b4-45a2-46a5-9308-3dd14861d76e", \
"filter": "category:flavoured-milk" \
} \
] \
}
|
| `targeting.negativeSearchTerms` | Termos de pesquisa negativos excluem palavras ou frases específicas da sua campanha, evitando que seus anúncios apareçam em pesquisas não relacionadas. Essa estratégia refina seu público-alvo, reduz custos e aumenta a eficiência da campanha. Por exemplo, adicionar `used` como um termo negativo para um anúncio de carro novo evita exibi-lo para quem procura carros usados. |
| `targeting.crossSell` | Especifica o direcionamento em posicionamentos de venda cruzada. |
| `targeting.crossSell.
targetProductsByKey` | Especifica pares explícitos de produto e catálogo a serem direcionados.
\[{"catalogId": "14edbbc5-a7be-4c54-9f35-767b4ee29fd3","productCode": "ABC123"}]
- Os catálogos de produtos de destino devem corresponder aos catálogos da campanha.
- Um produto deve existir para cada par de produto-catálogo.
- Os produtos de destino não podem estar entre os produtos anunciados.
- Os produtos de destino e os produtos anunciados devem compartilhar categorias correspondentes.
|
| `targeting.upSell.
targetProductsByKey` | Especifica pares explícitos de produto e catálogo a serem direcionados.
\[{"catalogId": "14edbbc5-a7be-4c54-9f35-767b4ee29fd3","productCode": "ABC123"}]
|
| `strategy.auction.maxBid` | O lance máximo de custo por clique (CPC) da sua campanha. Por exemplo, 2.99.
- Deve ser um BigDecimal válido.
- Deve ser maior que o lance mínimo.
},
"strategy": {
"auction": {
"maxBid": "string",
"spendLimit": {
"daily": "string",
"total": "string"
}
},
|
| `strategy.auction.spendLimit` | Especifica o gasto máximo diário ou total de uma campanha.
Omita isto para uma campanha always on que continuará gastando enquanto houver fundos na carteira da campanha. Por exemplo: "daily": "1000". Certifique-se de que o limite de gastos seja um valor BigDecimal maior que 0.
},
"strategy": {
"auction": {
"maxBid": "string",
"spendLimit": {
"daily": "string",
"total": "string"
}
},
|
| `strategy.fixedTenancy.cost` | Representa o custo total da campanha, usado apenas para fins de relatórios e não deduzido da carteira. Este valor pode ser atualizado se o varejista otimizar todo um pacote ou ordem de inserção (IO). Por exemplo: 1000.99.
"fixedTenancy": {
"cost": "1000.99",
"positions": \[
0
],
"catalogCosts": \[
{
"catalogId": "string",
"catalogCostPercentage": 0
}
]
}
|
| `strategy.fixedTenancy.
catalogCostPercentage` | Um valor entre 0 e 1 indicando a parcela do custo alocada para cada catálogo. Se usar vários catálogos, aloque uma parcela (ex.: 0,5). Para um único catálogo, use o valor 1.
"fixedTenancy": {
"cost": "string",
"positions": \[
0
],
"catalogCosts": \[
{
"catalogId": "string",
"catalogCostPercentage": 0.5
}
]
}
|
| `strategy.fixedTenancy.
fixedCosts` | Especifica custos adicionais para dados externos, trabalho criativo ou outros serviços relacionados à campanha. Essas cobranças se aplicam quando a campanha é aprovada e não podem ser modificadas. Omita isso, a menos que custos adicionais sejam aplicáveis ao seu anunciante.
{
"dataCost": "150",
"creativeCost": "200",
"otherCost": "400"
}
|
| `fixedCosts.dataCost` | O custo associado aos dados para a campanha. Por exemplo, $100.00. |
| `fixedCosts.creativeCost` | O custo associado à produção do Criativo para a campanha. Por exemplo, $200.00. |
| `fixedCosts.otherCost` | O custo associado a outras despesas para a campanha. Por exemplo, $50.00. |
| `customFields.customFieldId` | Especifica o customFieldId exclusivo sendo configurado. Campos personalizados não são obrigatórios em uma integração padrão e é provável que esse campo não seja usado, a menos que recomendado pelo seu Customer Integration Engineer (CIE).
{
"customFieldId": "3e31d3e4-bf15-411b-a18e-5553f08a6122",
"content": "PO-12345"
}
|
| `customFields.content` | O conteúdo para o campo personalizado na campanha.
{
"customFieldId": "3e31d3e4-bf15-411b-a18e-5553f08a6122",
"content": "PO-12345"
}
|
| `customQuestions.customQuestionId` | Especifica a pergunta de direcionamento personalizada exclusiva sendo configurada. Perguntas personalizadas não são obrigatórias em uma integração padrão e é provável que esse campo não seja usado, a menos que recomendado pelo seu Customer Integration Engineer (CIE).
{
"answers": \[
"preference:delivery",
"preference:online"
],"customQuestionId": "593a9860-5ce4-4dcc-b6c4-15cf6fb08426"
}
|
| `customQuestions.answers` | Especifica as respostas selecionadas pelos anunciantes para o direcionamento de clientes. Deve estar alinhado com o cliente targetingData valores.
{
"answers": \[
"preference:delivery",
"preference:online"
],"customQuestionId": "593a9860-5ce4-4dcc-b6c4-15cf6fb08426"
}
|
## Banner X campos de campanha
| Campo | Finalidade e exemplo |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `contentStandardId` | Um identificador exclusivo para o padrão de conteúdo. Padrões de conteúdo são diretrizes e parâmetros técnicos que ditam como um anúncio de banner deve ser exibido dentro de um espaço designado em um site ou plataforma digital.
Este identificador é necessário para verificar se o recurso de banner X criado adere aos padrões de conteúdo do varejista.
|
| `slotId` | Um identificador exclusivo para o slot na configuração, como 'homepage\_banner\_slot\_1'. Este identificador garante que o banner use o slot correto conforme definido pelo varejista, como tile único, tile duplo ou banner. |
| `slotType` | O slot exclusivo dentro do padrão de conteúdo onde a imagem será colocada. Ele garante que a imagem adira aos requisitos e validações pré-definidos do slot. Exemplos incluem left\_ribbon, top\_banner ou side\_panel. |
| `headingText` | O texto do título para o banner. |
| `bannerText` | Texto do banner é o texto exibido no seu anúncio de banner. |
| `bannerTextColourHex` | A cor do texto do banner em formato hexadecimal. |
| `ctaFlag` | Uma sinalização indicando se o banner tem uma chamada para ação ativada. |
| `ctaText` | O texto da chamada para ação no banner. Uma chamada para ação (CTA) é um texto ou botão clicável que incentiva os usuários a agir, como fazer uma compra ou visitar outra página. Por exemplo, "Compre agora". |
| `ctaTextAccessibility` | O texto da chamada para ação para fins de acessibilidade. |
| `ctaLink` | A URL para o link da chamada para ação. |
| `backgroundColourHex` | A cor da imagem de fundo principal do banner X em formato hexadecimal. |
| `backgroundImageId` | Este é o identificador exclusivo da imagem de fundo principal. |
| `backgroundImagePosition` | O alinhamento ou posição da imagem de fundo principal dentro de seu contêiner. |
| `secondaryBackgroundImageId` | O identificador exclusivo para a imagem de fundo secundária. |
| `secondaryBackgroundImagePosition` | O alinhamento ou posição da imagem de fundo secundária dentro de seu contêiner. |
| `heroImageId` | O identificador exclusivo para a imagem hero. A imagem hero é a imagem promocional principal, normalmente usada para exibir seu produto ou logotipo. |
| `heroImageAltText` | O texto alternativo para a imagem hero, auxiliando na acessibilidade. |
| `heroMode` | O modo de exibição ou estilo da seção hero. |
| `secondaryHeroImageId` | O identificador exclusivo para a imagem hero secundária. |
| `secondaryHeroImageAltText` | O texto alternativo para a imagem hero secundária, auxiliando na acessibilidade. |
| `secondaryHeroMode` | O modo de exibição ou estilo da seção hero secundária. |
| `trackingTags` | Um array obrigatório de objetos usado para especificar provedores de rastreamento e suas tags associadas para monitorar e analisar o desempenho de uma campanha de banner X. |
| `additionalFields` | Um array obrigatório de objetos fornecendo opções extras de configuração para o banner X. |
## Campos da campanha de banner
| Campo | Finalidade e exemplo |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `contentStandardId` | Um identificador exclusivo para o padrão de conteúdo. Padrões de conteúdo são diretrizes e parâmetros técnicos que ditam como um anúncio de banner deve ser exibido dentro de um espaço designado em um site ou plataforma digital.
Este identificador é necessário para verificar se o recurso de banner criado adere aos padrões de conteúdo do varejista.
|
| `slotId` | Um identificador exclusivo para o slot na configuração, como 'homepage\_banner\_slot\_1'. Este identificador garante que o banner use o slot correto conforme definido pelo varejista, como tile único, tile duplo ou banner. |
| `artworkImageId` | Um identificador exclusivo para a imagem da arte enviada para o banner. Este ID (fileId) é retornado pela API Upload the creative assets. |
| `link` | Esta é a URL vinculada ao Espaço de banner, direcionando os usuários para uma página de destino quando eles clicam no anúncio. Exemplo: |
| `altText` | Texto alternativo que descreve a imagem da arte para fins de acessibilidade. Exemplo: 'Banner promocional para a liquidação de verão'. |
| `text` | Texto de exibição no banner. O texto de exibição para o slot, fornecendo informações adicionais ou uma mensagem. Exemplo: 'Ganhe 20% de desconto na sua primeira compra!' |
| `trackingTags` | Uma lista de tags de rastreamento do provedor, usada para monitorar interações com o slot. Exemplo: \[ { provider: 'Google Analytics', tag: 'promo\_click' }, { provider: 'Adobe Analytics', tag: 'banner\_view' } ]. Essas tags são incluídas no seu anúncio para verificação de terceiros. |
---
# 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/partner/pt-br/partner-api-overview/campaign-field-definitions.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.