Campanhas
O que é
A API de Campanhas do Magalu ADS permite consultar campanhas publicitárias gerenciadas na plataforma de anúncios do Magalu. Ela retorna uma projeção pública da campanha, com as informações necessárias para acompanhamento de orçamento, estratégia de lance e status de veiculação, omitindo campos internos de roteamento que não são destinados a consumidores externos.
Objetivos da API
A API foi projetada para atender simultaneamente aos seguintes objetivos:
- Permitir a consulta de uma campanha específica a partir do seu identificador único.
- Expor o orçamento configurado (diário ou vitalício) e a política de ritmo de consumo (pacing).
- Detalhar a estratégia de lance utilizada pela campanha (CPC manual ou ROAS alvo).
- Indicar o estado atual do ciclo de vida da campanha (planejada, ativa, pausada, encerrada, etc.).
- Fornecer metadados de criação e atualização da campanha.
Domínios da Solução
| Domínio | Descrição |
|---|---|
| Campaign | Projeção pública de uma campanha, incluindo tipo, orçamento, estratégia de lance, status e período de veiculação. |
| Budget | Configuração de orçamento da campanha, com o valor limite e a política de consumo. |
| BiddingStrategy | Estratégia de lance da campanha. Pode ser ManualCpcBidding (lance manual por clique) ou TargetRoasBidding (lance por ROAS alvo). |
| Money | Valor monetário representado em unidades inteiras, sempre em Reais (BRL). |
| Metadata | Metadados de sistema com as datas de criação e última atualização da campanha. |
Detalhamento dos Campos
Campaign
| Campo | Tipo | Descrição |
|---|---|---|
| id | String (UUID) | Identificador único da campanha. |
| name | String | Nome de exibição da campanha. |
| type | CampaignType | Objetivo e estratégia de posicionamento da campanha: SPONSORED_PRODUCT, SPONSORED_DISPLAY ou SPONSORED_BRAND. |
| sellerId | String | Identificador do seller dono e financiador da campanha. |
| advertiserId | String | Identificador do anunciante dono e financiador da campanha. |
| budget | Budget | Configuração de orçamento e ritmo de consumo da campanha. |
| bidding | BiddingStrategy | Estratégia de lance utilizada nos grupos de anúncios associados à campanha. |
| status | CampaignStatus | Estado operacional atual da campanha. |
| startDate | String (ISO 8601) | Data e hora (UTC) em que a campanha está programada para começar a veicular. |
| endDate | String (ISO 8601) | Data e hora (UTC) em que a campanha termina. Quando omitido, a campanha roda indefinidamente. |
| metadata | Metadata | Datas de criação e última atualização da campanha. |
Budget
| Campo | Tipo | Descrição |
|---|---|---|
| amount | Money | Valor limite do orçamento. |
| type | String | Tipo de orçamento: DAILY (diário) ou LIFETIME (vitalício). |
| pacing | String | Ritmo de consumo do orçamento: STANDARD (padrão) ou ACCELERATED (acelerado). |
BiddingStrategy
Estratégia polimórfica, identificada pelo campo strategyType:
| Campo | Tipo | Descrição |
|---|---|---|
| strategyType | String | Tipo da estratégia: MANUAL_CPC ou TARGET_ROAS. |
ManualCpcBidding — lance manual por clique:
| Campo | Tipo | Descrição |
|---|---|---|
| defaultBid | Money | Valor padrão do lance por clique. |
TargetRoasBidding — lance por ROAS alvo:
| Campo | Tipo | Descrição |
|---|---|---|
| targetRoas | Integer | ROAS alvo da campanha, entre 5 e 20. |
Money
| Campo | Tipo | Descrição |
|---|---|---|
| currencyCode | String | Moeda do valor. Atualmente restrita a BRL. |
| amount | Integer | Valor monetário representado em unidades inteiras. |
CampaignStatus
Estado unificado do ciclo de vida e sincronização de uma campanha:
DRAFT, PROVISIONING, SCHEDULED, ACTIVE, PAUSING, PAUSED, RESUMING, BUDGET_EXHAUSTED, ENDED, ARCHIVED.
Metadata
| Campo | Tipo | Descrição |
|---|---|---|
| created | String (ISO 8601) | Data e hora de criação da campanha. |
| updated | String (ISO 8601) | Data e hora da última atualização da campanha. |
Ambientes
Ambientes disponíveis: Ambientes