Lote, importação e exportação

Uma loja com milhares de produtos não se mantém com um PUT por vez. Esta seção reúne as rotas que agem sobre muitos produtos em uma só chamada: ações em lote (status, preço, categoria, exclusão, edição de campos), edição de células no estilo planilha, importação e exportação em CSV, XLSX e XML, e duas operações de manutenção.

Todas ficam em /api/v1/admin/products/.... Para o modelo do produto em si (ids, dinheiro, status, produto mestre x do seller), leia antes a seção Produtos.

Como funciona

O jeito seguro de rodar um lote

1. Simule

   Envie o lote com "simulate": true. Com filter você recebe o total, uma amostra de 10 registros com valores de antes e depois e um confirm_token. Com lista de ids você recebe uma linha de prévia por id. Nada é gravado.

2. Confira

   Veja o total e a amostra. Se o total não é o que você esperava, corrija o filtro e simule de novo.

3. Confirme

   Envie o mesmo corpo de novo, sem simulate, acrescentando o confirm_token. Menos de 50 registros: a resposta é imediata (200). 50 ou mais: 202 com uma tarefa.

4. Desfaça se foi engano

   Guarde o undo_id da resposta. POST /api/v1/admin/bulk-undo/{undo_id} devolve os valores anteriores (e restaura da lixeira os produtos excluídos).

Qual operação para qual tarefa

Conceitos-chave

Duas formas de escolher os produtos

Lista de ids (product_ids): o jeito clássico. Todos os ids precisam ser UUIDs de produto (o número curto exibido na tela não é aceito).

Filtro (filter): o servidor encontra os produtos. Chaves aceitas (uma chave fora desta lista é recusada com 400 invalid_filter, então um erro de digitação nunca amplia o lote):

Várias chaves se combinam com E. Um filter vazio é recusado. Um filtro alcança no máximo 200.000 registros. Produtos excluídos nunca entram.

Simulação, token e desfazer

O confirm_token vale 70 minutos, é preso ao seu usuário, à rota e ao corpo exato (ação, parâmetros, filtro): mudou qualquer um, vem 409 confirm_token_invalid. Ele também falha se o filtro agora alcança mais registros do que a simulação aprovou.

Tarefas em segundo plano

Quando o lote alcança 50 registros ou mais (ou outro lote seu ainda está rodando) a chamada devolve 202 com uma tarefa (job). A tarefa tem status queued, running, done, failed ou interrupted, além de total, processed, affected, failed (uma contagem), percent e uma lista de até 50 falhas {id, error}. Consulte com GET /api/v1/admin/bulk-jobs/{id} a cada 2 segundos, ou acompanhe GET /api/v1/admin/bulk-jobs/{id}/stream (eventos do servidor: progress, depois done). O undo_id fica dentro de job.result.

Dinheiro e arquivos

• Lotes em JSON: preços em centavos, percentuais em pontos-base.
• Arquivos CSV/XLSX/XML: números decimais em reais (49.90 ou 49,90). Na importação, um preço sem separador decimal é lido como centavos: 4990 é R$ 49,90, mas 50 é R$ 0,50. Escreva sempre duas casas (50.00).
• Os CSV usam ; como separador e UTF-8 com BOM, para o Excel abrir direito.

Endpoints

Todas as rotas exigem o token Bearer de um usuário com o privilégio manage_catalog.

Erros comuns

• Mandar simulate: true em clone ou update_vendor com lista de ids. Essas duas ações ignoram simulate no caminho por ids e executam de verdade. Para simulá-las, mande os ids como filtro: "filter": {"ids": ["..."]}.
• Mandar um filtro e esquecer a simulação. Vem 428 simulate_required. Simule e repita com o confirm_token.
• Mudar qualquer coisa entre a simulação e a confirmação. O token é preso ao corpo exato: 409 confirm_token_invalid.
• Percentual como 5 em vez de 500. Percentuais são pontos-base. 5 significa 0,05%.
• Ler total_affected: 0 numa simulação como "nada vai mudar". Nas simulações por ids ele é sempre 0: conte as linhas de preview.
• Preço 50 num arquivo de importação. É R$ 0,50. Escreva 50.00.
• Esperar que o export-xml respeite product_ids. Não respeita: ele exporta todo produto que casa com os filtros. Veja Exportar.
• Tratar 200 como "tudo mudou". Confira affected e failed em toda resposta.

Próximos passos