---
title: Campanhas
---

# 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.
- **Listar e adicionar** anúncios 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](/docs/development-guide/error-structure) 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 e anúncios.    |
| `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](/docs/first-steps/environment)