VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa

Mudanças agendadas

Como agendar a troca de preço, preço de lista ou status de produtos e desfazê-la sozinha.

Uma mudança agendada diz: "neste dia e hora, troque este campo deste produto por este valor, e (opcionalmente) devolva o valor antigo em outra data". É o jeito de montar uma Black Friday na véspera sem ficar acordado à meia-noite: o preço novo entra às 00:00 e volta ao normal na terça. Um worker da plataforma confere o relógio a cada minuto e aplica o que venceu.

Pontos-chave
  • Exige um destes privilégios: manage_catalog, manage_layout ou manage_content (inclusive para ler).
  • Hoje só o tipo de alvo product está ativo, e só os campos price, list_price (centavos) e status.
  • Você agenda vários itens numa chamada (um lote). O lote é tudo ou nada na criação.
  • Com revert_at, a plataforma guarda o valor que o campo tinha na hora de aplicar e o restaura na data de reversão.
  • Datas em RFC 3339. Envie com o fuso (-03:00) para não errar a hora.
  • O servidor não confere na criação se o produto existe nem se o valor é válido: o erro aparece depois, no item, como failed.

Como funciona

scheduled→applied→reverted
statusSignificado
scheduledAguardando apply_at. É o único estado que pode ser cancelado.
appliedO novo valor foi gravado. Se há revert_at, aguarda a reversão.
revertedO valor antigo foi restaurado em revert_at.
cancelledCancelada antes de ser aplicada.
failedA aplicação ou a reversão falhou; o motivo está em error.

Fluxo típico

  1. Agende o lote
    POST /scheduled-changes com os itens (preço de lançamento e preço de volta, por exemplo). A resposta traz o batch_id. Veja Agendar mudanças.
  2. Confira o calendário
    GET /scheduled-changes/calendar?month=2026-11 mostra o que vai acontecer em cada dia.
  3. Acompanhe
    Depois do horário, GET /scheduled-changes?status=failed revela o que não foi aplicado.
  4. Cancele, se preciso
    Antes de apply_at, cancele o item ou o lote inteiro.

Conceitos importantes

Conflito de janela

Para o mesmo produto e o mesmo campo, a plataforma recusa um novo agendamento (409 window_conflict) se já existe outro scheduled ou applied que ainda vale, isto é, sem revert_at ou com revert_at no futuro. Na prática: depois que uma mudança permanente (sem revert_at) foi aplicada, aquele campo não aceita mais agendamentos novos para o mesmo produto.

Reversão

O valor a restaurar é lido no momento em que a mudança é aplicada, não no agendamento. Se alguém alterar o preço à mão entre a aplicação e a reversão, a reversão ainda devolve o valor que existia antes da aplicação.

Precisão do horário

O worker roda uma vez por minuto. Um apply_at no passado é aplicado na próxima passada (em até 1 minuto); não é recusado.

Endpoints

Método e caminhoPara que serveAuthPágina
POST /api/v1/admin/scheduled-changesAgenda um lote de mudançasadminAgendar mudanças
GET /api/v1/admin/scheduled-changesLista mudanças agendadasadminListar e ver o calendário
GET /api/v1/admin/scheduled-changes/calendarAgrupa as mudanças de um mês por diaadminListar e ver o calendário
POST /api/v1/admin/scheduled-changes/{id}/cancelCancela uma mudançaadminCancelar
POST /api/v1/admin/scheduled-changes/batch/{batchId}/cancelCancela um lote inteiroadminCancelar

Erros comuns

  • Agendar sem fuso. 2026-11-27T00:00:00Z é 21h de 26/11 em Brasília. Use -03:00.
  • Colocar price em reais. É inteiro em centavos: R$ 89,90 é 8990.
  • Campo ou tipo que ainda não existe. entity_type diferente de product leva 422; um field diferente dos três não é recusado na criação e vira failed na hora de aplicar.
  • revert_at antes de apply_at. Não é recusado: a mudança é aplicada e revertida logo em seguida.
  • Tentar cancelar uma mudança já aplicada. Só scheduled pode ser cancelada (422). Uma mudança aplicada com reversão pendente não tem rota para cancelar a reversão.
  • Listar sem filtro e achar que está vazio. A lista é ordenada da mais antiga para a mais nova e limitada a 500: filtre por from/to ou status.

Próximos passos

Agendar mudanças
Corpo, conflitos e exemplos.
Listar e ver o calendário
Filtros e a visão por dia.
Promoções e cupons
Descontos por regra, sem mexer no preço do produto.
Anterior
Pré-visualizar regra
Próxima
Agendar mudanças
Nesta página
  • Como funciona
  • Fluxo típico
  • Conceitos importantes
  • Conflito de janela
  • Reversão
  • Precisão do horário
  • Endpoints
  • Erros comuns
  • Próximos passos