API Promocional

Visão Geral

A API Promocional expõe os endpoints do módulo Promocional da plataforma para Sellers e Integradores, permitindo automatizar a gestão de promoções e a participação em campanhas. Com isso, os parceiros conseguem aderir e criar promoções de diversos tipos — Preço Promocional, Desconto à Vista e Cupom de Desconto — com ou sem incentivos do Canal, diretamente de seus próprios sistemas (ERPs e Hubs), centralizando a operação em um só local e reduzindo a necessidade de acesso manual ao Portal do Seller.

Disponibilidade em fases

Esta documentação descreve o escopo completo da API Promocional. As funcionalidades serão liberadas em fases. Atualmente, estão disponíveis:

• Lista as promoções disponíveis para o Seller
• Buscar promoção por ID

Novas capacidades serão adicionadas progressivamente. Confira o cronograma de implantação do módulo:

Contexto

Atualmente, a gestão de promoções exige que o Seller acesse o Portal do Seller manualmente para configurar cada oferta ou aderir a promoções sazonais. Esse processo gera duplicidade de trabalho para quem opera grandes catálogos e dificulta a velocidade de reação frente à concorrência.

Ao plugar o Módulo Promocional na Open API, o Magalu passa a atuar como uma plataforma integrada, onde a inteligência de descontos e os subsídios do canal são consumidos automaticamente, garantindo que o lojista tenha uma visão única de sua estratégia comercial.

Objetivos

• Expor APIs de leitura e escrita para criação e gestão de promoções via ferramentas externas.
• Seguir os padrões da Open Platform, operadas com token de seller.
• Habilitar o fluxo de Opt-in/Opt-out para que Sellers participem de campanhas com incentivos do Magalu via API.
• Disponibilizar consulta de campanhas vigentes e SKUs elegíveis.
• Centralizar a operação no ERP/Hub, eliminando a necessidade de acesso manual ao Portal do Seller.
• Disponibilizar Webhooks de notificação para alterações de status, expiração ou exclusão de promoções em tempo real.

Tipos de Promoção

Tipo	Descrição
absolute_discount	Preço fixo "De/Por".
percentage_discount	Desconto percentual (ex: 10% OFF). Geralmente criado pelo Magalu, focado em métodos de pagamento específicos.
coupon_discount	Desconto via código de cupom. Pode ser Autosserviço.
fidelity_discount	Exclusivo para clientes Ouro, geralmente restrito ao SuperApp.

Origem das Promoções

Origem	Descrição
channel	Criada pelo Magalu (Marketplace).
self_service	Criada pelo próprio Seller.

Status do Ciclo de Vida

Status	Descrição
scheduled	Promoção agendada, ainda não iniciada.
draft	Aceita, mas aguardando dados complementares (ex: planilha de SKUs).
active	Vigente e visível para o cliente final.
finished	Encerrada.

Elegibilidade Comercial

Nem toda promoção está disponível para todos os vendedores. O sistema valida se o seller_id está na allowlist da promoção, definida pelo time comercial. Caso o Seller não seja elegível para nenhuma promoção, o array promos retorna vazio [] com status 200 OK.