API atual/Referência completa/Promoções e cupons

POSTAções em lote

Ativa, desativa ou exclui várias promoções numa chamada, por lista de ids ou por critério.

Há dois modos. Por ids: até 100 promoções por chamada, resposta imediata. Por critério (filter): serve para recortes enormes, como "desative todas as vencidas" numa loja com 18 mil delas. O critério exige duas chamadas iguais: a primeira com simulate: true mostra quantas seriam afetadas e devolve um confirm_token; a segunda, sem simulate e com o token, executa. Lotes grandes rodam em segundo plano e a resposta vem com status 202.

Executar uma ação em lote

POST/api/v1/admin/promotions/bulkAdmin

Ativa, desativa ou exclui promoções em lote

Corpo da requisição

actionstringobrigatório

activatedeactivatedelete

O que fazer com as promoções.

idsarray of uuid

Até 100 ids. Duplicados e vazios são descartados. Obrigatório se não houver filter.

filterobject

Em vez de ids, um recorte por critério (veja abaixo). Funciona em duas etapas: simulação e confirmação.

expiredboolean

true: só promoções cujo valid_until já passou.

current_statusstring

Restringe ao status atual (active, inactive ou a letra).

without_productsboolean

true: promoções sem produto nem categoria e sem cupom, isto é, as que descontam a loja inteira sem ninguém ter pedido.

simulateboolean

Com true, não altera nada: devolve o total, uma amostra e o confirm_token.

confirm_tokenstring

Token devolvido pela simulação. Obrigatório para executar um lote por filter.

Exemplo de requisição: lote

bash

curl -X POST "$BASE_URL/api/v1/admin/promotions/bulk" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "deactivate",
    "ids": [
      "7c1f0a52-3b8e-4d11-9a47-5e2b6d8c1f30",
      "45646519-bcd1-4b6d-b341-2f94da1cbe2e"
    ]
  }'

Resposta: lote

200Lote por ids

json

{
  "action": "deactivate",
  "affected": 1,
  "failed": ["45646519-bcd1-4b6d-b341-2f94da1cbe2e"]
}

Campos da resposta

actionstring

A ação executada.

affectedinteger

Quantas promoções foram alteradas.

failedarray of uuid

Ids que falharam (não existem, ou a ativação foi barrada por regra como o piso de margem). Os demais foram processados.

No modo por critério a simulação responde 200 com o total, uma amostra e o confirm_token; a execução responde 200 com o resultado ou 202 com o identificador da tarefa em segundo plano.

Erros: lote

Status	Quando	Corpo de exemplo
401	Token ausente ou inválido.	`{"error":"authentication required"}`
403	O módulo `promotions` está desligado na loja.	`{"error":"module_disabled","module":"promotions"}`
403	O usuário não tem o privilégio exigido (`view_promotions` para ler, `manage_promotions` para gravar).	`{"error":"insufficient privileges","required":"manage_promotions"}`
400	`ids` vazio, mais de 100 ids, ou `action` fora de `activate`, `deactivate`, `delete`. A mensagem explica as duas formas de uso.	`{"error":"ids is required and must not be empty","detail":"mande {\"ids\":[...]} ou, por critério, ..."}`
400	Corpo que não é JSON.	`{"error":"invalid request body","detail":"..."}`
400	Critério por filtro inválido ou vazio.	`{"error":"invalid_filter","detail":"..."}`
400	Lote por filtro sem simulação prévia.	`{"error":"simulate_required","detail":"lote por filtro exige simulação: ..."}`
400	`confirm_token` de outro pedido, ou o recorte cresceu desde a simulação. Simule de novo.	`{"error":"confirm_token_invalid","detail":"..."}`

Veja também