API atual/Referência completa/Mudanças agendadas

POSTAgendar mudanças

Agenda um lote de mudanças de preço, preço de lista ou status de produtos.

Envie todos os itens da campanha de uma vez. A plataforma confere os conflitos de todos antes de gravar qualquer um; se um item conflita, nada é criado. Cada item pode ter revert_at para voltar ao valor anterior sozinho. A resposta devolve o batch_id, que serve para cancelar o lote inteiro.

Agendar um lote

POST/api/v1/admin/scheduled-changesAdmin

Agenda um lote de mudanças

Corpo da requisição

itemsarrayobrigatório

Um ou mais itens.

entity_typestringobrigatório

product

Tipo do alvo. Hoje só product.

entity_idstringobrigatório

UUID do produto.

fieldstringobrigatório

pricelist_pricestatus

Campo a mudar.

new_valueanyobrigatório

Novo valor. Centavos (inteiro) para price e list_price (null em list_price remove o preço "de"); texto para status (active, inactive/disabled ou a letra). Obrigatório na prática: sem ele a mudança falha ao ser aplicada.

apply_atstring (RFC 3339)obrigatório

Quando aplicar. Não pode ser omitido nem zero.

revert_atstring (RFC 3339)

Quando restaurar o valor anterior. Omitido = permanente.

Exemplo de requisição: agendar

bash

curl -X POST "$BASE_URL/api/v1/admin/scheduled-changes" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "entity_type": "product",
        "entity_id": "4a6235f6-9132-4945-806d-09c617174c42",
        "field": "price",
        "new_value": 8990,
        "apply_at": "2026-11-27T00:00:00-03:00",
        "revert_at": "2026-11-29T23:59:00-03:00"
      },
      {
        "entity_type": "product",
        "entity_id": "83e6c157-293b-4acb-9f11-003a5e17ec5b",
        "field": "price",
        "new_value": 2490,
        "apply_at": "2026-11-27T00:00:00-03:00",
        "revert_at": "2026-11-29T23:59:00-03:00"
      }
    ]
  }'

Resposta: agendar

201Lote agendado

json

{
  "batch_id": "0d4c8f1a-6b2e-4c9d-9f31-7a5e2b8c0d14",
  "items": [
    {
      "id": "2fe513d8-c5e4-44ce-89c5-4287ea725748",
      "batch_id": "0d4c8f1a-6b2e-4c9d-9f31-7a5e2b8c0d14",
      "entity_type": "product",
      "entity_id": "4a6235f6-9132-4945-806d-09c617174c42",
      "entity_label": "",
      "field": "price",
      "new_value": 8990,
      "apply_at": "2026-11-27T03:00:00Z",
      "revert_at": "2026-11-30T02:59:00Z",
      "status": "scheduled",
      "created_by": "67bf291c-0846-4053-9528-8cfd5ab0ebf1",
      "created_at": "2026-10-11T15:10:00Z"
    }
  ]
}

Campos da resposta

batch_iduuid

Identificador do lote.

itemsarray

Um item por mudança agendada, na ordem enviada.

iduuid

Identificador da mudança agendada.

batch_iduuid

Lote em que a mudança foi criada. Todas as mudanças de uma mesma chamada compartilham o lote.

entity_typestring

Tipo do alvo. Hoje só product.

entity_idstring

Id do alvo (UUID do produto).

entity_labelstring

Nome legível do alvo (nome do produto). Se o alvo não existe, repete o entity_id. Vem vazio na resposta da criação.

fieldstring

Campo que muda: price, list_price ou status.

new_valueany

Valor aplicado em apply_at. Centavos (inteiro) para price e list_price; texto para status.

revert_valueany | omitted

Valor que o campo tinha quando a mudança foi aplicada. Só existe se há revert_at e a mudança já foi aplicada.

apply_atstring (RFC 3339)

Quando aplicar.

revert_atstring (RFC 3339) | null

Quando desfazer. null = permanente.

statusstring

scheduledappliedrevertedcancelledfailed

scheduled, applied, reverted, cancelled ou failed.

errorstring | omitted

Motivo da falha, quando status é failed.

created_byuuid | null

Usuário que agendou.

created_atstring (RFC 3339)

Quando foi agendada.

Erros: agendar

Status	Quando	Corpo de exemplo
401	Token ausente ou inválido.	`{"error":"authentication required"}`
403	Falta um destes privilégios: `manage_catalog`, `manage_layout` ou `manage_content`. Vale também para leitura.	`{"error":"insufficient privileges","required":"manage_catalog"}`
400	Corpo que não é JSON.	`{"error":"invalid body","detail":"..."}`
409	Algum item conflita com outra mudança do mesmo produto e campo. `conflicts` lista cada uma, com `existing_id` e `apply_at`. Nada foi criado.	`{"error":"window_conflict","conflicts":[{"entity_type":"product","entity_id":"...","field":"price","existing_id":"...","apply_at":"..."}]}`
422	Lote vazio; item sem `entity_type`, `entity_id`, `field` ou `apply_at`; ou `entity_type` não suportado.	`{"error":"failed","detail":"unsupported entity_type \"banner\""}`

Veja também

POSTAgendar mudanças

Agenda um lote de mudanças de preço, preço de lista ou status de produtos.

Agendar um lote

POST/api/v1/admin/scheduled-changesAdmin

Agenda um lote de mudanças

Corpo da requisição

itemsarrayobrigatório

Um ou mais itens.

entity_typestringobrigatório

product

Tipo do alvo. Hoje só product.

entity_idstringobrigatório

UUID do produto.

fieldstringobrigatório

pricelist_pricestatus

Campo a mudar.

new_valueanyobrigatório

apply_atstring (RFC 3339)obrigatório

Quando aplicar. Não pode ser omitido nem zero.

revert_atstring (RFC 3339)

Quando restaurar o valor anterior. Omitido = permanente.

Exemplo de requisição: agendar

bash

curl -X POST "$BASE_URL/api/v1/admin/scheduled-changes" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "entity_type": "product",
        "entity_id": "4a6235f6-9132-4945-806d-09c617174c42",
        "field": "price",
        "new_value": 8990,
        "apply_at": "2026-11-27T00:00:00-03:00",
        "revert_at": "2026-11-29T23:59:00-03:00"
      },
      {
        "entity_type": "product",
        "entity_id": "83e6c157-293b-4acb-9f11-003a5e17ec5b",
        "field": "price",
        "new_value": 2490,
        "apply_at": "2026-11-27T00:00:00-03:00",
        "revert_at": "2026-11-29T23:59:00-03:00"
      }
    ]
  }'

Resposta: agendar

201Lote agendado

json

{
  "batch_id": "0d4c8f1a-6b2e-4c9d-9f31-7a5e2b8c0d14",
  "items": [
    {
      "id": "2fe513d8-c5e4-44ce-89c5-4287ea725748",
      "batch_id": "0d4c8f1a-6b2e-4c9d-9f31-7a5e2b8c0d14",
      "entity_type": "product",
      "entity_id": "4a6235f6-9132-4945-806d-09c617174c42",
      "entity_label": "",
      "field": "price",
      "new_value": 8990,
      "apply_at": "2026-11-27T03:00:00Z",
      "revert_at": "2026-11-30T02:59:00Z",
      "status": "scheduled",
      "created_by": "67bf291c-0846-4053-9528-8cfd5ab0ebf1",
      "created_at": "2026-10-11T15:10:00Z"
    }
  ]
}

Campos da resposta

batch_iduuid

Identificador do lote.

itemsarray

Um item por mudança agendada, na ordem enviada.

iduuid

Identificador da mudança agendada.

batch_iduuid

Lote em que a mudança foi criada. Todas as mudanças de uma mesma chamada compartilham o lote.

entity_typestring

Tipo do alvo. Hoje só product.

entity_idstring

Id do alvo (UUID do produto).

entity_labelstring

Nome legível do alvo (nome do produto). Se o alvo não existe, repete o entity_id. Vem vazio na resposta da criação.

fieldstring

Campo que muda: price, list_price ou status.

new_valueany

Valor aplicado em apply_at. Centavos (inteiro) para price e list_price; texto para status.

revert_valueany | omitted

Valor que o campo tinha quando a mudança foi aplicada. Só existe se há revert_at e a mudança já foi aplicada.

apply_atstring (RFC 3339)

Quando aplicar.

revert_atstring (RFC 3339) | null

Quando desfazer. null = permanente.

statusstring

scheduledappliedrevertedcancelledfailed

scheduled, applied, reverted, cancelled ou failed.

errorstring | omitted

Motivo da falha, quando status é failed.

created_byuuid | null

Usuário que agendou.

created_atstring (RFC 3339)

Quando foi agendada.

Erros: agendar

Status	Quando	Corpo de exemplo
401	Token ausente ou inválido.	`{"error":"authentication required"}`
403	Falta um destes privilégios: `manage_catalog`, `manage_layout` ou `manage_content`. Vale também para leitura.	`{"error":"insufficient privileges","required":"manage_catalog"}`
400	Corpo que não é JSON.	`{"error":"invalid body","detail":"..."}`
409	Algum item conflita com outra mudança do mesmo produto e campo. `conflicts` lista cada uma, com `existing_id` e `apply_at`. Nada foi criado.	`{"error":"window_conflict","conflicts":[{"entity_type":"product","entity_id":"...","field":"price","existing_id":"...","apply_at":"..."}]}`
422	Lote vazio; item sem `entity_type`, `entity_id`, `field` ou `apply_at`; ou `entity_type` não suportado.	`{"error":"failed","detail":"unsupported entity_type \"banner\""}`