Campanhas

O que é

A API de Campanhas do Magalu Ads permite criar, consultar e gerenciar campanhas publicitárias e seus anúncios na plataforma de anúncios do Magalu.

Com essa API, você pode:

• Criar campanhas de Produto Patrocinado, junto com seus anúncios, e publicá-las em uma única requisição.
• Consultar campanhas, individualmente ou em listas paginadas.
• Gerenciar o ciclo de vida da campanha: pausar, retomar, reagendar, estender e finalizar.
• Ajustar o orçamento, o lance padrão e o ROAS alvo de uma campanha existente.
• Pausar e retomar anúncios.

Os campos seguem o padrão snake_case, os valores de status e tipos são em minúsculas e os valores monetários são em Reais (BRL), em centavos. Por exemplo, 1050 equivale a R$ 10,50.

Em caso de falha, a resposta segue a estrutura de erros das APIs do portal.

Escopos necessários

Para a utilização das APIs os seguintes escopos poderão ser necessários:

Valor	Descrição
open:ads-campaign-seller:read	Permite a leitura de campanhas.
open:ads-campaign-seller:write	Permite criar e alterar campanhas e anúncios.

Se o token for válido mas a conta não tiver um seller de Ads habilitado, a API retorna 403.

Ciclo de vida da campanha

O status da campanha (status) pode assumir os valores: draft, provisioning, scheduled, active, pausing, paused, resuming, budget_exhausted, finalizing, finalized e archived.

Fluxo principal de uma campanha de Produto Patrocinado:

Criação (SP)  →  provisioning  →  scheduled  →  active  →  finalizing  →  finalized  →  archived

A criação é feita em POST /seller/v1/ads/campaigns/sp.

Situações que fogem do fluxo principal:

Situação	Status	Como acontece
Pausar e retomar	pausing → paused → resuming → active	Chamadas a POST /seller/v1/ads/campaigns/{id}/pause e POST /seller/v1/ads/campaigns/{id}/resume.
Orçamento consumido	budget_exhausted	Ocorre quando o orçamento da campanha se esgota.

A criação via POST /seller/v1/ads/campaigns/sp já publica a campanha, que nasce em provisioning. Se a publicação falhar antes de a campanha sair de draft, tudo o que foi criado é removido e o erro é retornado, então a requisição pode ser repetida. Se a data de início (start_date) já tiver passado, a campanha pode ir direto para active, sem passar por scheduled. Os status pausing, resuming e finalizing são intermediários, pois essas operações são processadas de forma assíncrona.

Os anúncios têm o próprio status (status): active, pausing, paused, resuming e archived. Pausar e retomar um anúncio (POST /seller/v1/ads/ads/{id}/pause e POST /seller/v1/ads/ads/{id}/resume) também são operações assíncronas.

Ambientes

Ambientes disponíveis: Ambientes