Movimento

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

O que é um Movimento

O Movimento é o registro de um evento que altera a quantidade de um produto em uma loja: uma venda, uma compra (recebimento), uma transferência entre locais, um bloqueio, um estorno. Enquanto o Estoque diz "quanto tem agora", o Movimento diz "o que aconteceu" — é o histórico de causas por trás de cada variação de saldo.

É a partir do fluxo contínuo de Movimentos que o RUB entende a velocidade de consumo de cada produto em cada loja (quantas unidades saem por dia, em que horários, com que sazonalidade) e antecipa quando a gôndola vai ficar vazia — o coração da geração proativa de tarefas de reposição.

Todas as movimentações devem ser informadas, preferencialmente logo após ocorrerem, na menor unidade comercializada do produto. Quanto mais próximo do tempo real, mais cedo o RUB percebe uma mudança de padrão de consumo e antecipa a tarefa correspondente.

Movimento × Estoque

graph LR
    M1["Movimento<br/>Venda de 3 un"] --> EST["Estoque<br/>saldo atualizado"]
    M2["Movimento<br/>Compra de 24 un"] --> EST
    M3["Movimento<br/>Transferência<br/>Depósito → Gôndola"] --> EST
    EST --> TASK["Estimativa de consumo<br/>e tarefas de reposição"]

O Movimento não substitui o envio do Estoque: são duas informações complementares. O Estoque garante que o RUB sempre tenha um saldo confiável mesmo que algum evento não tenha sido integrado; o Movimento garante que o RUB entenda o porquê e o ritmo das mudanças desse saldo.

Tipos de Movimento

O campo TIPO classifica a natureza do evento:

Bloqueio/Desbloqueio não representam entrada ou saída física — servem para marcar quantidade reservada (ex.: separada para um pedido, aguardando conferência) que não deve ser considerada disponível para venda, mas também não saiu fisicamente da loja.

Origem e Destino

Os campos opcionais ORIGEM e DESTINO identificam Locais (endereços) envolvidos no movimento — por exemplo, uma transferência interna do depósito para a gôndola tem ORIGEM = DEPOSITO e DESTINO = GONDOLA. Eles também dão suporte a relatórios de "quanto tempo um produto leva do recebimento até a exposição".

Modelo de dados

Chave e identidade

A chave é o CODIGO, único para cada movimento — normalmente o próprio número/identificador do documento de origem (número do cupom fiscal, número da nota de entrada, id interno do ERP). É esse código que garante a idempotência: reenviar o mesmo CODIGO não duplica a movimentação, o que é essencial em cenários de reprocessamento ou reenvio após falha de comunicação.

Relacionamentos

graph LR
    MOV["Movimento<br/>ID_LOJA, PRODUTO, CODIGO,<br/>QTD, TIPO, DATA_HORA"] -->|ID_LOJA + PRODUTO| PROD["Produto (Loja)"]

• Um Movimento pertence a um Produto (Loja) e ocorre em um instante específico (DATA_HORA).
• Um Produto (Loja) tem zero ou muitos Movimentos ao longo do tempo — é o histórico contínuo de tudo que aconteceu com ele naquela loja.
• Depende do Produto já existir na loja em questão.

Exemplos de uso

Cenário 1 — Venda no PDV

O cliente compra 3 unidades do produto 4482 no caixa. O PDV gera um Movimento do tipo 1 (Venda) assim que o cupom é fechado:

• ID_LOJA = 30001, PRODUTO = 4482, QTD = 3, TIPO = 1, CODIGO = número do cupom fiscal, DATA_HORA = instante da venda.

Cenário 2 — Estorno de venda

O mesmo cliente devolve 1 unidade minutos depois. Em vez de "desfazer" o movimento original, é lançado um novo Movimento do tipo 3 (Estorno de Venda), preservando o histórico de que a venda e o estorno de fato aconteceram:

• ID_LOJA = 30001, PRODUTO = 4482, QTD = 1, TIPO = 3, CODIGO = identificador do estorno.

Cenário 3 — Recebimento de mercadoria (compra)

Um fardo com 6 unidades do produto 4482 é recebido conforme a nota fiscal de entrada, totalizando 6 unidades adicionadas ao estoque da loja:

• ID_LOJA = 30001, PRODUTO = 4482, QTD = 6, TIPO = 4, CODIGO = chave da nota fiscal.

Cenário 4 — Transferência interna (depósito → gôndola)

Um colaborador leva 10 unidades do depósito para a gôndola durante a reposição. Não há entrada nem saída de estoque total da loja, mas o RUB precisa saber que o produto saiu do depósito e chegou na gôndola:

• ID_LOJA = 30001, PRODUTO = 4482, QTD = 10, TIPO = 19 (Outras Entradas, no destino) com ORIGEM = DEPOSITO, DESTINO = GONDOLA.

Cenário 5 — Produto de peso variável

Uma venda de 350 g de mussarela fatiada (produto 7301) é lançada em gramas, e não em "peças":

• ID_LOJA = 30001, PRODUTO = 7301, QTD = 350, TIPO = 1, CODIGO = número do cupom fiscal.

Cenário 6 — Reenvio após falha de comunicação

O ERP perde a confirmação de que um Movimento foi recebido e o reenvia por segurança, com o mesmo CODIGO de antes. Como a chave já existe, o RUB não duplica a movimentação — o reenvio é seguro e não distorce o histórico de consumo.

Boas práticas

• Gere um CODIGO verdadeiramente único por movimento (idealmente o identificador do documento de origem) — é a única defesa contra duplicidade em reenvios.
• Envie o Movimento assim que ele ocorrer; atrasos em lote (ex.: apenas no fechamento do dia) atrasam igualmente a percepção de ruptura pelo RUB.
• Use sempre a menor unidade comercializada (gramas para peso variável), consistente com o que é informado no Estoque.
• Utilize ORIGEM/DESTINO para transferências internas — é o que permite diferenciar "o produto saiu da loja" de "o produto só mudou de lugar dentro da loja".
• Prefira Bloqueio/Desbloqueio a ajustar o Estoque diretamente quando a quantidade está apenas reservada, preservando o saldo físico real.

Referência na API

O contrato técnico completo dos endpoints de Movimentações (parâmetros de rota, tipos de eventos, payload JSON 1:1 e importação massiva CSV) encontra-se documentado no Swagger oficial:

• Swagger da API: https://api.docs.rub.gicbrasil.com (tag Movimentações)
• Diretrizes da API REST: consulte a Referência da API REST para regras de tenancy, autenticação e fluxo de processamento de lotes.