Operações em lote

Quando você precisa mudar muitos registros de uma vez ("aumentar 10% o preço de uma categoria", "desativar todas as promoções vencidas"), fazer uma chamada por registro é lento e arriscado. As operações em lote resolvem isso com um fluxo de quatro passos: simular, confirmar, acompanhar e, se for preciso, desfazer.

Esta seção documenta o lote genérico (POST /bulk/apply), o acompanhamento das tarefas (/bulk-jobs), o desfazer (/bulk-undo) e o acompanhamento de importações de arquivos (/import-jobs).

Como funciona

1. Simular

   Chame a rota com o corpo completo e "simulate": true. Nada é gravado. A resposta traz total, sample (antes e depois de alguns registros), avisos e o confirm_token.

2. Mostrar ao usuário e confirmar

   Mostre o total e a amostra a quem decide. Se aprovado, repita o mesmo corpo, sem simulate, com confirm_token.

3. Acompanhar

   Com 50 registros ou mais, a resposta é 202 com um job. Leia o andamento em GET /bulk-jobs/{id} ou pelo stream de eventos.

4. Desfazer, se preciso

   O lote devolve um undo_id. POST /bulk-undo/{id} (também com simulação e confirmação) restaura os valores anteriores.

Estados de uma tarefa

Conceitos-chave

Dinheiro em centavos

Nos filtros e nas mudanças, preços são inteiros em centavos (10000 é R$ 100,00). Um filtro price_max: 100 pega até R$ 1,00.

Resultado parcial não é sucesso

Um lote pode alterar parte dos registros e falhar em outros. A resposta traz affected, failed (lista dos que falharam, com o motivo) e partial_failure: true. Confira sempre failed antes de dar o lote como concluído.

Fila por sessão

Tarefas iniciadas na mesma sessão (a mesma sessão do painel) rodam uma por vez, na ordem de confirmação, para que "aumente o preço" e "zere o estoque" não se atropelem.

Endpoints

Erros comuns

• Executar sem simular. 428 simulate_required. Simule primeiro e reenvie com o confirm_token.
• Mudar o corpo entre a simulação e a execução. O token é amarrado ao pedido: 409 confirm_token_invalid.
• Filtrar preço em reais. O filtro espera centavos. Simule e leia a amostra antes de confirmar.
• Dar o lote por feito sem ler failed. Lotes parciais voltam 200 ou 202.
• Mandar GET em route. O lote só escreve: POST, PUT, PATCH ou DELETE.
• Esperar desfazer para sempre. Um lote já desfeito responde 409 already undone.

Próximos passos