Referência da API · Estoque e Preço

Atualizar ou Criar Estoque em Lote para Filial

Método: PUT
Rota: /v1/stock/batch/:partnerId
URL base: https://ws.autorei.net
Parâmetros de rota: :partnerId
Token: Exige token Bearer

Abre esta requisição na documentação pública da API, a fonte oficial da referência.

Descrição

Permite que uma conta matriz crie ou atualize o estoque e o preço de até 50 produtos por requisição em uma de suas filiais. Cada item é processado de forma independente: o resultado de cada um vem no campo status da resposta, e um item recusado não impede os demais.

O corpo e a resposta são idênticos aos do envio para a própria loja, a diferença é a filial de destino, que vem na rota e é validada contra os vínculos da sua matriz.

Parâmetros de Rota

Parâmetro	Tipo	Obrigatório	Descrição
`partnerId`	integer	Sim	Id da filial que vai receber o estoque. Precisa estar vinculada à matriz do token.

Corpo da Requisição (JSON)

Campo	Tipo	Obrigatório	Descrição
`stockRequest`	array	Sim	De 1 a 50 itens.
`stockRequest[].warehouseId`	integer	Sim	Depósito onde o estoque é alocado.
`stockRequest[].price`	number	Sim	Preço de venda. Não pode ser negativo.
`stockRequest[].quantity`	integer	Sim	Quantidade em estoque. Não pode ser negativa.
`stockRequest[].virtualQuantity`	integer	Sim	Estoque virtual. Não pode ser negativo. Envie `0` quando não trabalhar com estoque virtual.
`stockRequest[].leadTime`	integer	Sim	Tempo de preparação em dias. Não pode ser negativo.
Identificação do produto, não é um campo, é um grupo	-	Sim	Uma das três combinações da seção Como identificar o produto: `productId` · `brand` + `mfrPartCode` + `composition` · `skuAttributeName` + `skuAttributeValue`.
`stockRequest[].byRequest`	boolean	Não	Produto disponível apenas para orçamento.
`stockRequest[].leadTimeByRequest`	boolean	Não	Prazo de preparação sob consulta. Veja Lead time e estoque virtual.
`stockRequest[].leadTimeDate`	datetime	Não	Data prevista de disponibilidade do produto. ISO-8601 completo, com fuso, `2026-09-10T00:00:00-03:00`. Veja Data de disponibilidade.
`stockRequest[].profitMargin`	number	Não	Margem de lucro, de 0 a 100.
`stockRequest[].targetMargin`	number	Não	Margem alvo, de 0 a 100.
`stockRequest[].totalCost`	number	Não	Custo total do item. Não pode ser negativo.
`stockRequest[].multipleQuantity`	integer	Não	Múltiplo de venda. `0` é normalizado para `1`.
`stockRequest[].partnerPartCode`	string	Não	Seu código de produto.
`stockRequest[].partnerPartCodeUnique`	boolean	Não	Torna o `partnerPartCode` único no depósito. Veja Código de produto único no depósito.
`stockRequest[].priceRuleTags`	array	Não	Tags de regra de preço a vincular ao produto: `[{"name":"promocao"}]`. Tag inexistente na sua loja é ignorada.
`stockRequest[].deleteTag`	boolean	Não	`true` remove todas as tags de regra de preço do produto, mesmo que você não envie nenhuma tag nova em `priceRuleTags`. Enviando os dois, as tags antigas saem e ficam só as de `priceRuleTags`.

Como identificar o produto

Cada item precisa trazer uma das três formas, nesta ordem de precedência:

Forma	Campos	Quando usar
Por id	`productId`	Você já guardou o id do SKU na CWS.
Por dados do fabricante	`brand` + `mfrPartCode` + `composition`	Os três juntos; nenhum sozinho identifica. `composition` aceita `UNITARY`, `PAIR`, `KIT`, `WARRANTY` e `SET`, sempre em maiúsculas.
Por atributo	`skuAttributeName` + `skuAttributeValue`	Você contratou o serviço de catálogo de produtos com atributo próprio.

Todos os itens do mesmo lote precisam usar a mesma forma. Misturar formas numa requisição recusa o lote inteiro com 400 e a mensagem mixed request types in list, separe em uma requisição por forma.

Regras de negócio

Lead time e estoque virtual

Duas combinações são recusadas: leadTimeByRequest: true junto com leadTime maior que zero; e leadTimeByRequest: false com leadTime zerado ou ausente quando há virtualQuantity maior que zero.

Data de disponibilidade

leadTimeDate é convertida para o fuso da plataforma (-03:00) antes de ser gravada, 2026-09-10T00:00:00Z vira 09/09 às 21:00, um dia antes do que você quis. Envie sempre com o offset -03:00.

O formato precisa ser a data e hora completas: 2026-09-10 ou 10/09/2026 recusam a requisição inteira com 400, antes de qualquer item ser processado.

Com a data preenchida e a quantidade real em zero, o estoque virtual passa a ser oferecido, mesmo efeito de leadTime e de leadTimeByRequest.

O envio é sempre completo

Na atualização, os campos opcionais que você não reenviar são apagados: leadTimeDate, leadTimeByRequest, profitMargin, totalCost e targetMargin voltam a vazio. partnerPartCode e multipleQuantity não têm esse comportamento, só mudam quando você os envia. Reenvie o item inteiro a cada atualização.

Itens repetidos no mesmo lote

Itens com o mesmo depósito e o mesmo identificador são deduplicados antes do processamento. Se as duplicatas trouxerem valores diferentes, o conflito não é processado, envie cada produto uma única vez por requisição.

Código de produto único no depósito

Com partnerPartCodeUnique: true, os estoques do mesmo depósito que já têm aquele código gravado em partnerPartCode são zerados (preço, quantidade e estoque virtual) e o código antigo recebe o sufixo _i. Use quando você reaproveita um código de produto para outro SKU.

Resposta · 200

Lista com um objeto por item enviado, na mesma ordem do envio. Campos zerados ou vazios são omitidos, se virtualQuantity volta ausente, ele é 0.

Campo	Descrição
`id`	Id do estoque criado ou atualizado. Vem `0` quando o item falhou.
`productId`	Id do SKU resolvido pela plataforma.
`warehouseId`	Depósito do item.
`price`	Preço gravado.
`status`	`CREATED` · `UPDATED` · `ERROR`
`error`	Motivo da recusa. Presente só quando `status` é `ERROR`.
`quantity` · `virtualQuantity` · `leadTime` · `byRequest` · `leadTimeByRequest` · `leadTimeDate`	Valores gravados. Omitidos quando zerados, falsos ou ausentes.
`brand` · `mfrPartCode` · `composition` · `skuAttributeName` · `skuAttributeValue`	Eco dos campos de identificação que você enviou. Omitidos quando não usados.
`partCode`	Eco do `partnerPartCode` que você enviou, na resposta ele volta com este nome.
`profitMargin` · `targetMargin` · `totalCost` · `multipleQuantity`	Valores gravados, quando enviados.
`priceRuleTags` · `deleteTag`	Tags aplicadas e o pedido de remoção, quando usados.

Quando o lote responde 200

Sempre que o envelope é válido, inclusive quando todos os itens falharam. Item recusado não impede os demais: o resultado de cada um vem no seu próprio status, e a recusa por campo faltando, valor fora de faixa ou produto não encontrado aparece como status: ERROR com o motivo em error. Percorra a lista sempre, mesmo com HTTP 200.

Erros

Código	Quando
400	`partnerId` da rota não é numérico: `{"error":"Invalid target partner ID"}`.
400	O corpo não é um JSON válido. O detalhe vem em `error`.
400	Falha que atinge o lote inteiro: formas de identificação misturadas (`mixed request types in list`) ou o depósito informado não é da filial. Aqui o envelope é diferente do resto, `code`, `message` e `errorDescription`, em vez de `error`. Trate os dois formatos.
401	Token ausente, malformado ou expirado: `{"error":"Authentication required for this route"}`.
403	A filial não está vinculada à sua matriz: `{"error":"Access denied: Invalid partnership"}`. Diferente de 400, aqui o payload está certo, o que falta é o vínculo.
422	Problema no envelope: `stockRequest` vazio ou com mais de 50 itens. O detalhe vem em `error`.

Recusa de item, campo faltando, valor fora de faixa, produto inexistente, não é erro de requisição: vem em 200, item a item. Veja Quando o lote responde 200.

Exemplo de requisição

curl --request PUT 'https://ws.autorei.net/v1/stock/batch/:partnerId' \
  --header 'Authorization: Bearer {{access_token}}' \
  --header 'Content-Type: application/json' \
  --data '{
  "stockRequest": [
    {
      "skuAttributeName": "codigo-interno",
      "skuAttributeValue": "SKU-A-001",
      "warehouseId": 4970,
      "price": 58.62,
      "quantity": 1123,
      "virtualQuantity": 0,
      "leadTime": 2
    },
    {
      "skuAttributeName": "codigo-interno",
      "skuAttributeValue": "SKU-B-002",
      "warehouseId": 4970,
      "price": 150.0,
      "quantity": 5,
      "virtualQuantity": 0,
      "leadTime": 2
    }
  ]
}'

Respostas de exemplo

200Sucesso: identificação por dados do fabricante

[
  {
    "id": 4410001,
    "productId": 500101,
    "warehouseId": 4970,
    "brand": "Fabricante Exemplo",
    "mfrPartCode": "FE-500101",
    "composition": "UNITARY",
    "price": 58.62,
    "quantity": 1123,
    "leadTime": 2,
    "status": "UPDATED"
  }
]

200Sucesso: identificação por atributo, com item recusado no lote

[
  {
    "id": 4410001,
    "productId": 500101,
    "warehouseId": 4970,
    "skuAttributeName": "codigo-interno",
    "skuAttributeValue": "SKU-A-001",
    "price": 58.62,
    "quantity": 1123,
    "leadTime": 2,
    "status": "UPDATED"
  },
  {
    "id": 0,
    "warehouseId": 4970,
    "price": 0,
    "quantity": 5,
    "status": "ERROR",
    "error": "price is required; virtualQuantity is required; leadTime is required; missing product identifier: provide productId OR (brand+mfrPartCode+composition) OR (skuAttributeName+skuAttributeValue)"
  }
]

Usado em

Casos de usoIntegração ERP: o caminho típico pela API
Casos de usoPortal B2B próprio: o caminho típico pela API
Casos de usoMarketplace B2B: o caminho típico pela API
Casos de usoVarejo complexo e B2B2C: o caminho típico pela API

Endpoints relacionados

PUT Atualizar ou Criar Estoque em Lote /v1/stock/batch

← Ver o grupo: Estoque e Preço

Gerado a partir da coleção pública da API, publicada em 04/09/2026: api-docs.cws.digital.