VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API legada/Referência completa/Armazéns e estoque

Estoque do armazém

Consulte e atualize os níveis de estoque dos produtos em um armazém específico, com as quantidades reservadas e as quantidades por variante.

A API de estoque do armazém permite gerenciar os níveis de estoque dos produtos nos armazéns da loja. Você pode atualizar, consultar e administrar o estoque de um produto específico em um armazém específico, o que dá controle preciso sobre a alocação e a distribuição do estoque.

Use-a depois de criar um armazém (veja Armazéns), por exemplo quando um ERP envia uma nova contagem ou quando você quer ver o que há para vender em um local. As rotas ficam em $BASE_URL/api/2.0/warehouses/{warehouse_id}/stock, exigem uma conta de administrador e usam credenciais HTTP Basic ($EMAIL:$API_KEY).

Pontos principais
  • O mesmo produto pode ter um estoque diferente em cada armazém.
  • available_amount é a quantidade disponível para venda: amount menos reserved_amount.
  • As quantidades reservadas são calculadas automaticamente a partir dos pedidos pendentes e das reservas manuais.
  • Em produtos com opções (variantes), envie a quantidade de cada variante. O sistema calcula o estoque total do produto a partir das variantes.
  • Todas as operações de estoque são registradas com data e hora e informações do usuário, formando uma trilha de auditoria completa.

Estrutura do estoque

Esta é a estrutura de um objeto de estoque de um produto em um armazém:

json
{
  "warehouse_id": "12",
  "product_id": "423",
  "product_code": "LAPTOP-PRO-15",
  "product_name": "Professional Laptop 15\"",
  "amount": 150,              // Current stock quantity
  "reserved_amount": 25,     // Reserved for pending orders
  "available_amount": 125,   // Available for sale (amount - reserved)
  "min_amount": 10,          // Minimum stock level alert
  "max_amount": 500,         // Maximum stock capacity
  "cost_price": "899.99",    // Unit cost price
  "tracking": "B",           // B - track with options, O - track without options, D - don't track
  "status": "A",             // A - active, D - disabled
  "location": "A-12-34",     // Physical location within warehouse
  "batch_number": "LOT2024001", // Batch/lot tracking
  "last_updated": "2024-06-24T14:30:00Z",
  "options": [
    {
      "option_id": "15",
      "option_name": "Color",
      "variant_id": "45",
      "variant_name": "Silver",
      "amount": 75,
      "reserved_amount": 10
    },
    {
      "option_id": "15",
      "option_name": "Color",
      "variant_id": "46",
      "variant_name": "Black",
      "amount": 75,
      "reserved_amount": 15
    }
  ]
}

Campos do estoque

warehouse_idstring
Identificador do armazém.
product_idstring
Identificador do produto.
product_codestring
Código do produto.
product_namestring
Nome do produto.
amountinteger
Quantidade atual em estoque.
reserved_amountinteger
Quantidade reservada para pedidos pendentes.
available_amountinteger
Quantidade disponível para venda (quantidade menos reservada).
min_amountinteger
Alerta de nível mínimo de estoque.
max_amountinteger
Capacidade máxima de estoque.
cost_pricestring
Preço de custo unitário, como texto decimal.
trackingstring
BOD
B controlar com opções, O controlar sem opções, D não controlar.
statusstring
AD
A para ativo, D para desativado.
locationstring
Localização física dentro do armazém.
batch_numberstring
Controle por lote.
last_updatedstring
Quando o estoque foi atualizado pela última vez.
optionsarray
Estoque por variante de opção, cada uma com option_id, option_name, variant_id, variant_name, amount e reserved_amount.

Operações principais de estoque

Listar o estoque de um armazém

GET/api/2.0/warehouses/{warehouse_id}/stockAdmin

Recupera os níveis de estoque de todos os produtos de um armazém

Parâmetros de caminho

warehouse_idintegerobrigatório
Identificador do armazém.
bash
curl -u "$EMAIL:$API_KEY" "$BASE_URL/api/2.0/warehouses/12/stock"

Consultar o estoque de um produto

GET/api/2.0/warehouses/{warehouse_id}/stock/{product_id}Admin

Recupera as informações de estoque de um produto em um armazém

Parâmetros de caminho

warehouse_idintegerobrigatório
Identificador do armazém.
product_idintegerobrigatório
Identificador do produto.
bash
curl -u "$EMAIL:$API_KEY" "$BASE_URL/api/2.0/warehouses/12/stock/423"

Atualizar o estoque de um produto

PUT/api/2.0/warehouses/{warehouse_id}/stock/{product_id}Admin

Atualiza os níveis de estoque de um produto em um armazém

Parâmetros de caminho

warehouse_idintegerobrigatório
Identificador do armazém.
product_idintegerobrigatório
Identificador do produto.

Corpo da requisição

amountinteger
Quantidade atual em estoque.
reserved_amountinteger
Quantidade reservada.
min_amountinteger
Alerta de nível mínimo de estoque.
max_amountinteger
Capacidade máxima de estoque.
cost_pricestring
Preço de custo unitário.
locationstring
Localização física dentro do armazém.
batch_numberstring
Número do lote.
optionsarray

Quantidades por variante do produto.

variant_idstring
Identificador da variante da opção.
amountinteger
Quantidade em estoque da variante.
reserved_amountinteger
Quantidade da variante que está reservada.

Exemplo de requisição para atualizar o estoque de um produto específico em um armazém:

bash
curl -X PUT "$BASE_URL/api/2.0/warehouses/12/stock/423" \
  -H "Content-Type: application/json" \
  -u "$EMAIL:$API_KEY" \
  -d '{
    "amount": 200,
    "reserved_amount": 30,
    "min_amount": 15,
    "max_amount": 600,
    "cost_price": "899.99",
    "location": "A-12-35",
    "batch_number": "LOT2024002",
    "options": [
      {
        "variant_id": "45",
        "amount": 100,
        "reserved_amount": 15
      },
      {
        "variant_id": "46", 
        "amount": 100,
        "reserved_amount": 15
      }
    ]
  }'
Nota

Todas as operações de estoque são registradas com data e hora e informações do usuário, para uma trilha de auditoria completa. As quantidades reservadas são calculadas automaticamente a partir dos pedidos pendentes e das reservas manuais.

Dica

Ao atualizar o estoque de produtos com opções ou variantes, inclua sempre as quantidades de cada variante para manter o controle de estoque correto. O sistema calcula automaticamente o estoque total do produto a partir do total das variantes.

Melhores práticas

  • Sincronização em tempo real: implemente webhooks para manter os sistemas externos sincronizados com as mudanças de estoque.
  • Níveis mínimos: defina níveis mínimos de estoque adequados para receber alertas automáticos.
  • Localização: use códigos de localização física para uma gestão eficiente do armazém.
  • Controle por opção: gerencie o estoque no nível da variante em produtos com várias opções.

Veja também

Armazéns
Armazéns, áreas de entrega e grupos de usuários.
Métodos de envio
As opções de entrega da loja.
Anterior
Armazéns
Próxima
Áreas de entrega
Nesta página
  • Estrutura do estoque
  • Operações principais de estoque
  • Listar o estoque de um armazém
  • Consultar o estoque de um produto
  • Atualizar o estoque de um produto
  • Melhores práticas
  • Veja também