Estoque

Integração Básica do RUB — entidade obrigatória, de contexto Loja.

O que é o Estoque

O Estoque é a fotografia do saldo total de um produto em uma loja: quantas unidades (ou gramas, para produtos de peso variável) existem fisicamente naquele momento, opcionalmente detalhadas por Local dentro da loja (depósito, câmara fria, gôndola).

Diferente do Movimento, que registra eventos (uma venda, uma entrada, um ajuste), o Estoque registra estado: o saldo consolidado que resulta de todos os movimentos já ocorridos. É a partir dele — combinado com o histórico de vendas — que o RUB estima quando um produto vai rupturar na gôndola e antecipa a necessidade de reposição.

Os estoques são sempre informados com base na menor unidade comercializada do produto: latas para um refrigerante, gramas para uma peça de mussarela fatiada. Se o ERP controla estoque em caixas ou fardos, é necessário converter para a menor unidade antes de enviar ao RUB.

Estoque como reflexo do ERP

graph LR
    ERP["Estoque no ERP<br/>(saldo por depósito)"] -->|snapshot periódico<br/>ou por evento| RUB["Estoque no RUB<br/>por Loja + Produto (+ Local)"]
    RUB --> TASK["Estimativa de ruptura<br/>e tarefas de reposição"]

O RUB não calcula o estoque de forma independente do ERP — ele reflete o que a retaguarda informa. Cabe ao sistema corporativo manter esse saldo atualizado com a frequência necessária para que as estimativas de ruptura sejam confiáveis (idealmente após cada evento relevante: venda, recebimento, ajuste de inventário).

Estoque por Local

O campo opcional LOCAL permite detalhar o estoque dentro da loja — por exemplo, separar o que está na gôndola (exposto ao cliente) do que está no depósito (reserva). Essa separação é o que permite ao RUB diferenciar "o produto tem estoque, mas está todo no depósito" (situação de ruptura de exposição) de "o produto realmente acabou" — dois problemas com soluções operacionais bem diferentes (reposição rápida vs. compra/recebimento).

Modelo de dados

CampoTipoObrigatórioDescrição
ID_LOJAINTEIROSimCódigo de identificação da Loja.
PRODUTOTEXTO(32)SimCódigo do Produto a que se refere o Estoque.
QTDDECIMALSimQuantidade em estoque para o Produto, na menor unidade comercializada (aceita fração, ex.: 100.5).
LOCALTEXTO(32)NãoLocal (endereço) ao qual se refere o Estoque informado; quando omitido, usa o endereço padrão da loja.

Chave e identidade

A chave é composta por ID_LOJA + PRODUTO (+ LOCAL, quando informado). Reenviar a mesma chave substitui o saldo anterior — o Estoque não é cumulativo como o Movimento; cada envio representa o saldo atual, não um incremento.

Relacionamentos

graph LR
    EST["Estoque<br/>ID_LOJA, PRODUTO, QTD, LOCAL"] -->|ID_LOJA + PRODUTO| PROD["Produto (Loja)"]
  • Um Estoque pertence a um Produto (Loja) e, opcionalmente, a um Local dentro da loja.
  • Um Produto (Loja) pode ter um registro de Estoque total e/ou vários registros por Local.
  • Depende do Produto já existir na loja em questão.

Exemplos de uso

Cenário 1 — Saldo total, sem detalhamento por Local

A loja 30001 tem 500 unidades do produto 4482 em estoque, sem distinção de onde estão fisicamente:

  • ID_LOJA = 30001, PRODUTO = 4482, QTD = 500, LOCAL não informado.

Cenário 2 — Saldo detalhado por Local

A mesma loja controla separadamente o depósito e a gôndola: 350 unidades no depósito e 20 na gôndola (total real de 370, refletindo que parte do estoque contábil já foi consumida sem ainda ter sido lançada como venda):

  • ID_LOJA = 30001, PRODUTO = 4482, LOCAL = DEPOSITO, QTD = 350.
  • ID_LOJA = 30001, PRODUTO = 4482, LOCAL = GONDOLA, QTD = 20.

Com essa granularidade, o RUB percebe que a gôndola está com pouca quantidade mesmo havendo estoque no depósito, e gera uma tarefa de reposição em vez de uma tarefa de compra.

Cenário 3 — Produto de peso variável

Para a mussarela fatiada (produto 7301), o estoque é sempre informado em gramas: uma peça de 3,2 kg em exposição é enviada como QTD = 3200.

Cenário 4 — Atualização de saldo após inventário

Após uma contagem física, o ERP identifica uma diferença entre o saldo contábil e o real. O novo saldo (já ajustado) é reenviado para a mesma chave (ID_LOJA + PRODUTO [+ LOCAL]), substituindo o valor anterior — o ajuste em si também deve ser refletido como um Movimento do tipo adequado (ex.: "Outras Saídas"/"Outras Entradas"), para que o histórico de causas fique registrado, e não apenas o saldo final.

Boas práticas

  • Informe o estoque na menor unidade comercializada do produto, sempre a mesma unidade usada no Produto Empresa (PESO_VARIAVEL).
  • Envie o saldo com a maior frequência possível — quanto mais próximo do tempo real, mais precisas são as estimativas de ruptura e as tarefas geradas.
  • Prefira detalhar por LOCAL sempre que o ERP tiver essa granularidade; é o que permite diferenciar ruptura de exposição de falta real de mercadoria.
  • Trate o Estoque como saldo, não como incremento: cada envio deve refletir a quantidade atual total, não somar à anterior.
  • Sempre que possível, complemente atualizações de estoque decorrentes de ajustes/inventário com o Movimento correspondente, para preservar o histórico de causas.

Referência na API

O contrato técnico completo dos endpoints de Estoque (parâmetros de rota, consulta de saldos, ajuste unitário JSON 1:1 e importação massiva CSV) encontra-se documentado no Swagger oficial: