Atualize o estoque do Magento 2 pela API de source items

O endpoint que existe justamente para isso

Desde o MSI, o Magento tem uma rota só de estoque:

POST /rest/V1/inventory/source-items

Ela cai no SourceItemsSaveInterface, que no próprio código do core está comentado como Service method for source items save multiple. Performance efficient API. O payload é uma lista, então dá para mandar centenas de SKUs numa requisição só:

curl -X POST "https://sualoja.com.br/rest/V1/inventory/source-items" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '
{
  "sourceItems": [
    { "sku": "CAM-001", "source_code": "default", "quantity": 3, "status": 1 },
    { "sku": "CAM-002", "source_code": "default", "quantity": 0, "status": 0 }
  ]
}'

São só quatro campos. sku e source_code são obrigatórios; quantity e status são o que você quer mudar. O status aceita 1 para em estoque e 0 para fora de estoque — no core são as constantes STATUS_IN_STOCK e STATUS_OUT_OF_STOCK.

Se a loja nunca configurou fonte nenhuma, o source_code é default. Esse é o nome literal da fonte que o Magento cria na instalação.

Por que o PUT do produto sai caro

O PUT /V1/products/{sku} cai no ProductRepositoryInterface::save(), que é o mesmo caminho de quando alguém clica em Save no admin. Ou seja, ele arrasta a festa inteira:

• dispara os eventos de save de produto, e junto todo plugin e observer que suas extensões penduraram ali;
• marca os índices de preço, categoria e estoque para reprocessar;
• invalida o full page cache das páginas daquele produto;
• mexe em url_rewrite se a url_key vier no payload.

O source-items não faz nada disso. Ele grava a linha de estoque e deixa o índice de salable quantity se resolver no fluxo normal.

Tem o efeito colateral de conteúdo também: todo atributo que o ERP mandar sobrescreve o que está gravado. Se o ERP tem uma descrição curta e o marketing escreveu outra no admin, a cada sincronização o marketing perde.

Lote, permissão e como conferir

Três coisas práticas para a integração não te acordar de madrugada.

Lote com tamanho fixo. Eu uso blocos de 200 a 500 itens por requisição. Mandar dez mil de uma vez funciona em teste e estoura max_input_vars ou timeout no dia em que o catálogo cresce. Se o volume for mesmo grande, existe a versão assíncrona: POST /rest/all/async/V1/inventory/source-items devolve um bulk_uuid na hora e processa depois — mas aí o consumer async.operations.all precisa estar rodando.

Permissão da role. A rota exige o recurso Magento_InventoryApi::stock_source_item_assign. Se a sua integração está com uma role restrita e o endpoint devolve 401 ou 403 mesmo com token válido, é isso. Não dê acesso total à integração só para resolver — marque o recurso certo.

Confira lendo, não confiando. A leitura equivalente é:

GET /rest/V1/inventory/source-items?searchCriteria[filter_groups][0][filters][0][field]=sku&searchCriteria[filter_groups][0][filters][0][value]=CAM-001&searchCriteria[filter_groups][0][filters][0][condition_type]=eq

E, para saber o que o cliente realmente consegue comprar (que é outro número, porque desconta reserva de pedido em aberto), GET /rest/V1/inventory/get-product-salable-quantity/CAM-001/1, onde 1 é o id do stock.