Canal Trocas e Devoluções

Capturamos movimentações de entrada do tipo TROCA. Quando o cliente devolve ou troca uma peça, o sistema OSK registra uma nova movimentação de entrada e a vincula à venda original via tabela movimentacao_movimentacao.

Métodos: getTrocas() → agruparTrocasPorDocumento()

Vínculo troca ↔ venda original

Troca ENTRADA / TROCA situacao = FINALIZADO movimentacao_movimentacao id_movimentacao_pai = troca id_movimentacao = venda original Venda original SAIDA / PDV movimentacao ms NF-e numero serie mm.id_mov_pai mm.id_movimentacao nfe Figura 6 - movimentacao_movimentacao conecta a troca a venda original.

Filtros aplicados

Campo	Valor	Motivo
`m.modulo`	`'PDV'`	Apenas trocas do PDV
`m.tipo`	`'ENTRADA'`	Mercadoria retornando ao estoque
`m.tipo_estoque`	`'TROCA'`	Distingue de compras e outras entradas
`m.situacao`	`'FINALIZADO'`	Apenas trocas concluídas
`m.data_emissao`	`BETWEEN :dataInicio AND :dataFim`	Período da requisição
`j.cnpj`	`= :cnpjLoja`	Restringe à loja

Estrutura da query (3 CTEs)

CTEs em ordem de execução

e — filtra a entidade (loja) pelo CNPJ informado
m — agrega movimentações de troca: soma valores e quantidades por movimentação
tr — junta ao documento original via movimentacao_movimentacao e busca a NF de venda

Agrupamento por documento

A mesma NF pode ter múltiplas trocas (cliente troca um item hoje e outro amanhã). Em agruparTrocasPorDocumento() consolidamos assim:

Somamos valor_vale e valor_original
A implementação atual não soma quantidade ao agrupar documentos repetidos; mantém a quantidade do primeiro registro do grupo
Mantemos o timestamp mais recente
Trocas sem vínculo com NF original são incluídas individualmente

Retorno da API

// Um elemento do array "trocas"
{
  "motivo":         "Defeito no produto",
  "doc_venda":      "000001234",             // NF da venda original
  "serie_venda":    "001",
  "cod_cliente":    123,
  "cnpj_emp":       "12345678000190",
  "valor_vale":     89.90,                   // Crédito gerado para o cliente
  "valor_original": 89.90,                   // Mesmo valor agregado da troca na implementação atual
  "timestamp":      "2026-05-18T14:22:00-03:00",
  "cod_vendedor":   "V001",
  "quantidade":     1
}

Dicionário de campos

Campo	Origem	Descrição
`doc_venda`	`movimentacao_nfe.numero` da venda	NF da venda que originou a troca
`serie_venda`	`movimentacao_nfe.serie` da venda	Série da NF original
`valor_vale`	Soma dos itens da troca	Crédito gerado para o cliente
`valor_original`	`SUM(md.valor_rateio)` da movimentação de troca	Na implementação atual, recebe o mesmo agregado usado em `valor_vale`
`timestamp`	`movimentacao.data_emissao`	Data/hora da troca — ISO 8601
`cod_vendedor`	`pessoa.codigo`	Vendedor que registrou a troca
`quantidade`	`SUM(md.qtde)` por movimentação de troca	Não é acumulado novamente quando múltiplas trocas são agrupadas pelo mesmo documento

Trocas sem documento original Se a troca não encontrar uma NF de venda (doc_venda nulo), ela é incluída individualmente sem agrupamento. Isso ocorre quando a venda foi feita antes da implantação do controle de vínculos no sistema.