API legada/Referência completa/API de apps (token vat_)

Estoque em massa

Define o estoque de vários produtos numa só chamada, com quantidades absolutas e relatório de falhas por produto.

Um ERP ou um WMS (sistema de armazém) que contou o estoque físico precisa gravar o resultado na loja. Esta operação recebe uma lista de produtos com a quantidade absoluta de cada um e grava tudo de uma vez, em vez de uma chamada por produto.

Cada linha é independente: se um produto falha, os outros continuam. Para cada produto gravado a plataforma atualiza a quantidade, sincroniza o saldo de estoque que a vitrine consulta e emite o evento de mudança de estoque (que alimenta a busca e as notificações). A operação exige o escopo write_inventory.

POST/api/admin/inventory/bulk-updateAutenticada

Definir o estoque de vários produtos

A quantidade enviada substitui o estoque atual; não é um incremento. Quantidade negativa é gravada como zero.

Corpo da requisição

updatesarrayobrigatório

Lista de atualizações, no mínimo uma.

updates[].product_iduuidobrigatório

Id do produto. Vazio conta como falha da linha.

updates[].quantityintegerobrigatório

Estoque novo, em unidades inteiras. Negativo vira 0.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/admin/inventory/bulk-update" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "updates": [
    {
      "product_id": "b02afb3d-4218-40ef-a72f-47beede28d46",
      "quantity": 120
    },
    {
      "product_id": "f00b151f-498a-4c27-adfb-774ac5ac6c89",
      "quantity": 0
    }
  ]
}'

Resposta

200Processado (com ou sem falhas)

json

{
  "total_requested": 3,
  "total_affected": 2,
  "failed_ids": ["00000000-0000-0000-0000-000000000000"],
  "message": "Updated stock for 2 of 3 products"
}

Campos da resposta

total_requestedinteger

Quantas linhas vieram no pedido.

total_affectedinteger

Quantas foram gravadas.

failed_idsarray

Ids das linhas que falharam: produto inexistente, produto excluído, id vazio (aparece como texto vazio) ou erro ao gravar. Ausente quando tudo deu certo.

messagestring

Resumo em inglês: Updated stock for N of M products.

Erros

Status	Quando	Corpo
400	Corpo que não é JSON, ou `quantity` que não é inteiro	`{"error":"invalid request body","detail":"..."}`
400	`updates` vazio ou ausente	`{"error":"updates cannot be empty"}`
401	Sem token de app	`{"error":"app_token_required"}`
403	Sem o escopo `write_inventory`	`{"error":"missing_scope","required":"write_inventory"}`
500	Falha geral (banco indisponível)	`{"error":"bulk update failed","detail":"..."}`

Veja também