Pular para conteúdo

Promoções / Ajustes de Preço

Promoções são ajustes temporários de preço com data de início/fim. Diferente da Formação de Preço (que recalcula preço a partir de custo + margem), a promoção aplica um desconto ou valor fixo durante uma janela configurada.

Quando usar

Recurso Quando
PUT /integration/prices/bysku Ajuste permanente de 1 SKU
Formação de Preço Regra durável (preço = custo + margem)
Promotion (esta página) Campanha temporária (Black Friday, queima de estoque)

Endpoints

Todos sob /integration/promotions (HAL+JSON, JWT obrigatório):

Método Path Descrição
GET /{promotionId} Recupera 1 promoção por ID
GET /list/all?page=&size=&sort= Lista paginada (todas do seller)
POST /list/search Busca paginada por filtro (status, datas, tipo, marketplace)
POST /list/search/ids Mesma busca, mas retorna só IDs (sync incremental)
POST (root) Cria nova promoção (201 Created)
PUT /update/{promotionId} Atualiza promoção existente
DELETE /{promotionId} Remove promoção
PUT /activate Ativa lote de promoções (transição → ACTIVE)
PUT /finish Finaliza lote (transição → FINISHED)
POST /{id}/clone Clona promoção (novo ID, status INACTIVE)

Ciclo de vida

   INACTIVE  ──activate──>  ACTIVE  ──finish (manual ou endDate)──>  FINISHED
       │                        │
       │                        └── se restorePricesOnAutoFinish=true,
       │                            preços voltam ao valor anterior
       │
       └── criada via POST ou clone

Exemplo: Black Friday

# 1. Criar
PROMO_ID=$(curl -s -X POST "$GUBEE_API/integration/promotions" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Black Friday 2026 - Eletrônicos",
    "status": "INACTIVE",
    "startDate": "2026-11-24T00:00:00Z",
    "endDate": "2026-11-30T23:59:59Z",
    "restorePricesOnAutoFinish": true,
    "eligibility": {
      "domain": "PRODUCT",
      "categories": ["Eletrônicos"]
    },
    "ruleType": "PERCENTAGE_DISCOUNT",
    "value": 15.0
  }' | jq -r '.id')

echo "Promoção criada: $PROMO_ID"

# 2. Ativar (no dia da campanha)
curl -X PUT "$GUBEE_API/integration/promotions/activate" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d "[\"$PROMO_ID\"]"

# 3. Finalizar (manualmente antes do endDate, se precisar)
curl -X PUT "$GUBEE_API/integration/promotions/finish" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d "[\"$PROMO_ID\"]"

Modelo de dados (PromotionDTO)

Campo Tipo Descrição
id String ID único (gerado na criação)
name String Nome da promoção
status Enum INACTIVE / ACTIVE / FINISHED
startDate ISO 8601 Início da vigência
endDate ISO 8601 Fim da vigência
restorePricesOnAutoFinish Boolean Se true, restaura preços pré-promoção ao expirar
eligibility Object Árvore de filtros (PRODUCT ou AD, categorias, SKUs, plataformas)
ruleType Enum Tipo: PERCENTAGE_DISCOUNT, FIXED_DISCOUNT, FIXED_PRICE, etc
value BigDecimal Valor do ajuste (% ou absoluto, conforme ruleType)

Próximos passos