API atual/Referência completa/Operações em lote

Desfazer lotes

Lista os lotes que guardaram um retrato para desfazer e restaura os valores anteriores de um lote, com simulação opcional.

Antes de alterar os registros, a maioria dos lotes grava um retrato do estado anterior. Esse retrato permite desfazer: devolver cada registro ao que era. O desfazer vale para o lote genérico, para os lotes de produtos (preço, status, categoria, exclusão, edição em planilha) e para importações de produtos.

Listar lotes desfazíveis

GET/api/v1/admin/bulk-undoAdmin

Listar os lotes com retrato guardado

Devolve 20 por página, do mais novo para o mais antigo, incluindo os que já foram desfeitos (undone_at preenchido).

Parâmetros de consulta

pageintegerpadrão: 1

Página.

bash

curl "$BASE_URL/api/v1/admin/bulk-undo?page=1" \
  -H "Authorization: Bearer $TOKEN"

200Retratos

json

{
  "items": [
    {
      "id": "ad40a3ab-042f-4495-bb33-c44cb51cfdff",
      "job_type": "bulk_prices",
      "job_ref": "filter",
      "item_count": 2,
      "created_by_name": "Maria Souza",
      "created_at": "2026-10-11T20:54:04.782881Z",
      "undone_at": "2026-10-11T20:54:08.327337Z"
    }
  ],
  "total": 14
}

Campos da resposta

items[].iduuid

Id do retrato. É o undo_id devolvido pelo lote.

items[].job_typestring

Tipo do lote, como bulk_prices, bulk_delete, import.

items[].job_refstring

Referência do lote (por exemplo filter para lotes por critério). Ausente quando não há.

items[].item_countinteger

Registros no retrato.

items[].created_by_namestring

Nome de quem executou o lote, quando conhecido.

items[].created_atstring

Quando o lote rodou, RFC 3339, UTC.

items[].undone_atstring

Quando foi desfeito. Ausente se ainda pode ser desfeito.

totalinteger

Total de retratos, desfeitos ou não.

Desfazer um lote

POST/api/v1/admin/bulk-undo/{id}Admin

Restaurar os valores anteriores de um lote

Devolve cada registro do retrato ao estado anterior. Há dois modos:

Sem corpo: desfaz na hora, como o botão "Desfazer" do painel. Responde com o resultado por registro.
Com simulate: true e depois confirm_token: mesmo fluxo de simulação e confirmação do lote. Para retratos do lote genérico, a resposta é a de um lote (200 ou 202 com tarefa quando passa de 50 registros).

Um lote só é desfeito uma vez: a segunda tentativa responde 409. Exige manage_catalog.

Parâmetros de caminho

iduuidobrigatório

Id do retrato (undo_id).

Corpo da requisição

simulateboolean

true mostra o que voltaria, sem gravar, e devolve um confirm_token.

confirm_tokenstring

Token da simulação, para executar o desfazer simulado.

bash

curl -X POST "$BASE_URL/api/v1/admin/bulk-undo/ad40a3ab-042f-4495-bb33-c44cb51cfdff" \
  -H "Authorization: Bearer $TOKEN"

200Lote desfeito

json

{ "total": 2, "ok": 2 }

Quando algum registro não pôde voltar:

json

{
  "total": 2,
  "ok": 1,
  "failed": [
    { "product_id": "d8a6c5e7-8e44-4055-a0e2-49014f5d17f6", "error": "..." }
  ]
}

Campos da resposta

totalinteger

Registros no retrato.

okinteger

Quantos voltaram ao estado anterior.

failedarray

Os que não voltaram, com product_id e error. Ausente sem falhas.

Erros

Status	Quando	Corpo de exemplo
400	Retrato inexistente, ou falha ao restaurar.	`{"error":"failed to undo","detail":"undo not found"}`
401	Sem token ou token expirado.	`{"error":"invalid or expired token"}`
403	Sem `manage_catalog`.	`{"error":"insufficient privileges","required":"manage_catalog"}`
409	O lote já foi desfeito.	`{"error":"already undone","detail":"..."}`
409	Na execução simulada: token inválido ou recorte alterado.	`{"error":"confirm_token_invalid","detail":"..."}`
428	Simulação exigida e não feita.	`{"error":"simulate_required","detail":"..."}`

Veja também

Desfazer lotes

Lista os lotes que guardaram um retrato para desfazer e restaura os valores anteriores de um lote, com simulação opcional.

Listar lotes desfazíveis

GET/api/v1/admin/bulk-undoAdmin

Listar os lotes com retrato guardado

Devolve 20 por página, do mais novo para o mais antigo, incluindo os que já foram desfeitos (undone_at preenchido).

Parâmetros de consulta

pageintegerpadrão: 1

Página.

bash

curl "$BASE_URL/api/v1/admin/bulk-undo?page=1" \
  -H "Authorization: Bearer $TOKEN"

200Retratos

json

{
  "items": [
    {
      "id": "ad40a3ab-042f-4495-bb33-c44cb51cfdff",
      "job_type": "bulk_prices",
      "job_ref": "filter",
      "item_count": 2,
      "created_by_name": "Maria Souza",
      "created_at": "2026-10-11T20:54:04.782881Z",
      "undone_at": "2026-10-11T20:54:08.327337Z"
    }
  ],
  "total": 14
}

Campos da resposta

items[].iduuid

Id do retrato. É o undo_id devolvido pelo lote.

items[].job_typestring

Tipo do lote, como bulk_prices, bulk_delete, import.

items[].job_refstring

Referência do lote (por exemplo filter para lotes por critério). Ausente quando não há.

items[].item_countinteger

Registros no retrato.

items[].created_by_namestring

Nome de quem executou o lote, quando conhecido.

items[].created_atstring

Quando o lote rodou, RFC 3339, UTC.

items[].undone_atstring

Quando foi desfeito. Ausente se ainda pode ser desfeito.

totalinteger

Total de retratos, desfeitos ou não.

Desfazer um lote

POST/api/v1/admin/bulk-undo/{id}Admin

Restaurar os valores anteriores de um lote

Devolve cada registro do retrato ao estado anterior. Há dois modos:

Sem corpo: desfaz na hora, como o botão "Desfazer" do painel. Responde com o resultado por registro.
Com simulate: true e depois confirm_token: mesmo fluxo de simulação e confirmação do lote. Para retratos do lote genérico, a resposta é a de um lote (200 ou 202 com tarefa quando passa de 50 registros).

Um lote só é desfeito uma vez: a segunda tentativa responde 409. Exige manage_catalog.

Parâmetros de caminho

iduuidobrigatório

Id do retrato (undo_id).

Corpo da requisição

simulateboolean

true mostra o que voltaria, sem gravar, e devolve um confirm_token.

confirm_tokenstring

Token da simulação, para executar o desfazer simulado.

bash

curl -X POST "$BASE_URL/api/v1/admin/bulk-undo/ad40a3ab-042f-4495-bb33-c44cb51cfdff" \
  -H "Authorization: Bearer $TOKEN"

200Lote desfeito

json

{ "total": 2, "ok": 2 }

Quando algum registro não pôde voltar:

json

{
  "total": 2,
  "ok": 1,
  "failed": [
    { "product_id": "d8a6c5e7-8e44-4055-a0e2-49014f5d17f6", "error": "..." }
  ]
}

Campos da resposta

totalinteger

Registros no retrato.

okinteger

Quantos voltaram ao estado anterior.

failedarray

Os que não voltaram, com product_id e error. Ausente sem falhas.

Erros

Status	Quando	Corpo de exemplo
400	Retrato inexistente, ou falha ao restaurar.	`{"error":"failed to undo","detail":"undo not found"}`
401	Sem token ou token expirado.	`{"error":"invalid or expired token"}`
403	Sem `manage_catalog`.	`{"error":"insufficient privileges","required":"manage_catalog"}`
409	O lote já foi desfeito.	`{"error":"already undone","detail":"..."}`
409	Na execução simulada: token inválido ou recorte alterado.	`{"error":"confirm_token_invalid","detail":"..."}`
428	Simulação exigida e não feita.	`{"error":"simulate_required","detail":"..."}`