API atual/Guia rápido/Lote, importação e exportação

Edição estilo planilha

Edita vários campos de até 200 produtos por chamada, linha a linha como numa planilha, ou aplica uma transformação de texto ou número a um filtro.

Esta rota alimenta o "modo planilha" da grade de produtos do painel. Onde Ações em lote muda uma coisa (status, preço, categoria) para muitos produtos, aqui cada produto recebe os seus próprios valores em vários campos na mesma chamada, e a resposta vem linha a linha.

Há dois modos, escolhidos pelo corpo:

Modo linhas (updates): você manda o valor final de cada campo de cada produto. Até 200 produtos por chamada. Grava na hora.
Modo transformação (filter + changes): você descreve uma mudança ("acrescentar - PROMO ao nome") e o servidor a aplica a todos os produtos que o filtro alcança. Mesmo fluxo de simular, confirm_token e desfazer dos outros lotes.

POST/api/v1/admin/products/bulk/cellsAdmin

Edição estilo planilha de produtos

Exige o privilégio manage_catalog.

Campos editáveis (qualquer outra chave dentro de fields é ignorada em silêncio):

Campo	Tipo	Observações
`name`, `sku`, `ean`, `brand`, `seo_title`, `seo_description`	texto	Texto
`price_cents`, `list_price_cents`	inteiro	Centavos, não negativo
`quantity`	inteiro	Não negativo
`weight`, `length`, `width`, `height`	número	Não negativo
`status`	texto	`A`, `D`, `H` ou `active`, `disabled`, `hidden`

Corpo da requisição

updatesarray

Modo linhas. Uma entrada por produto, no máximo 200.

product_iduuidobrigatório

O produto.

fieldsobjectobrigatório

Mapa de nome do campo para o novo valor (veja a tabela acima).

expected_updated_atstring

O updated_at em RFC 3339 que você leu antes. Se o produto mudou desde então, a linha é recusada com "registro alterado por outro usuário", e você nunca sobrescreve a edição de outra pessoa.

filterobject

Modo transformação: seleciona os produtos (veja a tabela de chaves na visão geral).

changesarray

Modo transformação. Cada entrada é {"field", "op", "value", "find"}. Campos de texto aceitam set, append, prepend, replace (exige find) e clear; campos numéricos aceitam set, increase, decrease; status aceita set. Um campo só pode aparecer uma vez.

simulatebooleanpadrão: false

Modo transformação: simulação com antes e depois de uma amostra de 10 produtos.

confirm_tokenstring

Modo transformação: token da simulação.

Exemplo de requisição

bash

# Modo linhas
curl -X POST "$BASE_URL/api/v1/admin/products/bulk/cells" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "updates": [
      { "product_id": "ea4e5a3d-bed2-4bcc-bce4-53a8370cee28",
        "fields": { "name": "Camiseta Azul", "price_cents": 5290, "quantity": 12 } }
    ]
  }'

# Modo transformação, simulação
curl -X POST "$BASE_URL/api/v1/admin/products/bulk/cells" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "filter": { "sku_contains": "CAM-" },
    "changes": [ { "field": "name", "op": "append", "value": " - PROMO" } ],
    "simulate": true
  }'

Resposta

200Modo linhas

json

{
  "total_requested": 1,
  "total_affected": 1,
  "results": [
    { "product_id": "ea4e5a3d-bed2-4bcc-bce4-53a8370cee28", "ok": true }
  ],
  "previous": [
    {
      "product_id": "ea4e5a3d-bed2-4bcc-bce4-53a8370cee28",
      "fields": { "name": "Doc Bulk Camiseta", "price_cents": 4990, "quantity": 10 }
    }
  ]
}

200Modo linhas com uma linha recusada

json

{
  "total_requested": 1,
  "total_affected": 0,
  "results": [
    { "product_id": "ea4e5a3d-bed2-4bcc-bce4-53a8370cee28", "ok": false, "error": "no editable fields in payload" }
  ],
  "previous": null
}

200Modo transformação, simulação

json

{
  "simulate": true,
  "action": "update_field",
  "description": "Editar produtos: acrescentar \" - PROMO\" ao fim de nome",
  "total": 3,
  "sample": [
    { "id": "734e2d83-973f-4a57-9803-11bd235f8adb", "name": "Mochila", "before": "Mochila", "after": "Mochila - PROMO" }
  ],
  "confirm_token": "eyJ0IjoiZGZl...",
  "expires_at": "2026-10-11T22:04:00Z",
  "async": false,
  "by": "filter"
}

Campos da resposta

total_requestedinteger

Linhas recebidas (modo linhas) ou produtos alcançados (modo transformação).

total_affectedinteger

Linhas ou produtos alterados.

resultsarray

(modo linhas) Uma entrada por linha, na ordem: product_id, ok, e error quando ok é falso.

previousarray

(modo linhas) Os valores anteriores, das linhas que deram certo. Mande-os de volta como fields para reverter; este modo não devolve undo_id.

undo_idstring

(modo transformação, após executar) Id do retrato para POST /api/v1/admin/bulk-undo/{undo_id}. Em tarefa em segundo plano fica em job.result.

As respostas do modo transformação (simulação, resultado 200, tarefa 202) têm o mesmo formato de Ações em lote.

Erros

Status	Quando	Exemplo de corpo
400	JSON inválido	`{"error":"invalid request body","detail":"..."}`
400	Nem `updates` nem `filter`	`{"error":"updates is required"}`
400	Mais de 200 linhas	`{"error":"failed to bulk update cells","detail":"batch too large: max 200 rows per request"}`
400	`filter` ou `changes` inválido	`{"error":"invalid_filter","detail":"filtro de lote inválido: changes[0].field \"vendor_id\" não é editável em lote; aceitos: ..."}`
401 / 403	Sem token / sem `manage_catalog`	`{"error":"missing authorization header"}` / `{"error":"insufficient privileges","required":"manage_catalog"}`
409 / 428	Token inválido ou expirado / simulação ausente (modo transformação)	`confirm_token_invalid` / `simulate_required`

Uma linha recusada não derruba a chamada. O status é 200 e a linha traz ok: false com uma destas mensagens: product_id is required, no fields to update, no editable fields in payload, field price_cents: valor não pode ser negativo, status inválido: ..., product not found, registro alterado por outro usuário, campo ... bloqueado (produto vinculado a produto mestre).

Veja também

Edição estilo planilha

Edita vários campos de até 200 produtos por chamada, linha a linha como numa planilha, ou aplica uma transformação de texto ou número a um filtro.

Há dois modos, escolhidos pelo corpo:

Modo linhas (updates): você manda o valor final de cada campo de cada produto. Até 200 produtos por chamada. Grava na hora.
Modo transformação (filter + changes): você descreve uma mudança ("acrescentar - PROMO ao nome") e o servidor a aplica a todos os produtos que o filtro alcança. Mesmo fluxo de simular, confirm_token e desfazer dos outros lotes.

POST/api/v1/admin/products/bulk/cellsAdmin

Edição estilo planilha de produtos

Exige o privilégio manage_catalog.

Campos editáveis (qualquer outra chave dentro de fields é ignorada em silêncio):

Campo	Tipo	Observações
`name`, `sku`, `ean`, `brand`, `seo_title`, `seo_description`	texto	Texto
`price_cents`, `list_price_cents`	inteiro	Centavos, não negativo
`quantity`	inteiro	Não negativo
`weight`, `length`, `width`, `height`	número	Não negativo
`status`	texto	`A`, `D`, `H` ou `active`, `disabled`, `hidden`

Corpo da requisição

updatesarray

Modo linhas. Uma entrada por produto, no máximo 200.

product_iduuidobrigatório

O produto.

fieldsobjectobrigatório

Mapa de nome do campo para o novo valor (veja a tabela acima).

expected_updated_atstring

O updated_at em RFC 3339 que você leu antes. Se o produto mudou desde então, a linha é recusada com "registro alterado por outro usuário", e você nunca sobrescreve a edição de outra pessoa.

filterobject

Modo transformação: seleciona os produtos (veja a tabela de chaves na visão geral).

changesarray

simulatebooleanpadrão: false

Modo transformação: simulação com antes e depois de uma amostra de 10 produtos.

confirm_tokenstring

Modo transformação: token da simulação.

Exemplo de requisição

bash

# Modo linhas
curl -X POST "$BASE_URL/api/v1/admin/products/bulk/cells" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "updates": [
      { "product_id": "ea4e5a3d-bed2-4bcc-bce4-53a8370cee28",
        "fields": { "name": "Camiseta Azul", "price_cents": 5290, "quantity": 12 } }
    ]
  }'

# Modo transformação, simulação
curl -X POST "$BASE_URL/api/v1/admin/products/bulk/cells" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "filter": { "sku_contains": "CAM-" },
    "changes": [ { "field": "name", "op": "append", "value": " - PROMO" } ],
    "simulate": true
  }'

Resposta

200Modo linhas

json

{
  "total_requested": 1,
  "total_affected": 1,
  "results": [
    { "product_id": "ea4e5a3d-bed2-4bcc-bce4-53a8370cee28", "ok": true }
  ],
  "previous": [
    {
      "product_id": "ea4e5a3d-bed2-4bcc-bce4-53a8370cee28",
      "fields": { "name": "Doc Bulk Camiseta", "price_cents": 4990, "quantity": 10 }
    }
  ]
}

200Modo linhas com uma linha recusada

json

{
  "total_requested": 1,
  "total_affected": 0,
  "results": [
    { "product_id": "ea4e5a3d-bed2-4bcc-bce4-53a8370cee28", "ok": false, "error": "no editable fields in payload" }
  ],
  "previous": null
}

200Modo transformação, simulação

json

{
  "simulate": true,
  "action": "update_field",
  "description": "Editar produtos: acrescentar \" - PROMO\" ao fim de nome",
  "total": 3,
  "sample": [
    { "id": "734e2d83-973f-4a57-9803-11bd235f8adb", "name": "Mochila", "before": "Mochila", "after": "Mochila - PROMO" }
  ],
  "confirm_token": "eyJ0IjoiZGZl...",
  "expires_at": "2026-10-11T22:04:00Z",
  "async": false,
  "by": "filter"
}

Campos da resposta

total_requestedinteger

Linhas recebidas (modo linhas) ou produtos alcançados (modo transformação).

total_affectedinteger

Linhas ou produtos alterados.

resultsarray

(modo linhas) Uma entrada por linha, na ordem: product_id, ok, e error quando ok é falso.

previousarray

(modo linhas) Os valores anteriores, das linhas que deram certo. Mande-os de volta como fields para reverter; este modo não devolve undo_id.

undo_idstring

(modo transformação, após executar) Id do retrato para POST /api/v1/admin/bulk-undo/{undo_id}. Em tarefa em segundo plano fica em job.result.

As respostas do modo transformação (simulação, resultado 200, tarefa 202) têm o mesmo formato de Ações em lote.

Erros

Status	Quando	Exemplo de corpo
400	JSON inválido	`{"error":"invalid request body","detail":"..."}`
400	Nem `updates` nem `filter`	`{"error":"updates is required"}`
400	Mais de 200 linhas	`{"error":"failed to bulk update cells","detail":"batch too large: max 200 rows per request"}`
400	`filter` ou `changes` inválido	`{"error":"invalid_filter","detail":"filtro de lote inválido: changes[0].field \"vendor_id\" não é editável em lote; aceitos: ..."}`
401 / 403	Sem token / sem `manage_catalog`	`{"error":"missing authorization header"}` / `{"error":"insufficient privileges","required":"manage_catalog"}`
409 / 428	Token inválido ou expirado / simulação ausente (modo transformação)	`confirm_token_invalid` / `simulate_required`