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.
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:
É necessário o consentimento dos usuários, para isso implemente o processo de autenticação e autorização.
Se você não possui integração com as APIs antigas, basta seguir o processo de solicitação de criação de aplicação.
Escopos necessários
Para a utilização das APIs os seguintes escopos poderão ser necessários:
| Valor | Descrição |
|---|---|
open:promotion-promotions-seller:read | Permite a leitura de promoções e dados relacionados. |
open:promotion-skus-seller:read | Permite a leitura de SKUs de uma promoção. |
open:promotion-skus-seller:write | Permite a atualização de SKUs de uma promoção. |
open:promotion-subscriptions-seller:write | Permite inscrever-se ou remover inscrição em uma promoção. |
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 integrar o Módulo Promocional da Open API, o Seller — ou a Integradora — passa a ter acesso aos dados de descontos e subsídios por Canal de venda, obtendo uma visão única e consolidada 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 Canal 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 Canal, 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 com programa de fidelidade no Canal de venda, geralmente restrito ao SuperApp. |
Origem das Promoções
| Origem | Descrição |
|---|---|
channel | Criada pelo Canal (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.