Canal PDV — Vendas

Capturamos as vendas registradas no módulo PDV — transações de saída com NF-e autorizada/cancelada quando existir vínculo em movimentacao_nfe. Cada venda pode ter um ou mais itens; nossa query retorna uma linha por item e o método agruparItensDasVendas() os agrupa em um array aninhado itens.

Métodos: consultarVendasPdv() → agruparItensDasVendas()

Relacionamento das tabelas

movimentacao id, data_emissao, situacao modulo = PDV, tipo = SAIDA id_pessoa, id_vendedor, id_entidade movimentacao_nfe numero, serie, situacao movimentacao_detalhe codigo, EAN, qtde, valor_rateio entidade loja da venda juridica cnpjLoja pessoa codigo vendedor nf.id_movimentacao md.id_movimentacao m.id_entidade e.id_pessoa m.id_vendedor Figura 5 - Tabelas MySQL envolvidas no canal PDV e seus relacionamentos.

Filtros aplicados

Campo	Valor / Condição	Motivo
`m.modulo`	`= 'PDV'`	Apenas transações do módulo de caixa
`m.tipo`	`= 'SAIDA'`	Apenas saídas (vendas)
`m.situacao`	`<> 'Cancelado'`	Excluímos movimentações canceladas no cabeçalho
`m.data_emissao`	`BETWEEN :dataInicio AND :dataFim`	Filtro de período normalizado
`j.cnpj`	`= :cnpjLoja`	Restringe à loja da requisição
`nf.situacao`	`IN ('AUTORIZADO','CANCELADO')`	NF-e com situação definida no SEFAZ
`md.situacao`	`= 'ATIVO'`	Apenas linhas de detalhe ativas

Estrutura da query (2 CTEs)

CTEs utilizados

movimentacoes — agrupa dados do cabeçalho: vendedor, NF-e, entidade, CNPJ
itens — junta os detalhes de produto aos cabeçalhos

O SELECT final une os dois CTEs retornando uma linha por item, depois agrupamos em PHP.

Retorno da API

// Um elemento do array "vendas"
{
  "codigo_cliente":  123,
  "cod_vendedor":    "V001",
  "cnpj_emp":        "12345678000190",
  "data_documento":  "2026-05-15T10:30:00-03:00",   // ISO 8601
  "identificador":   9001,
  "transacao":       9001,
  "usuario":         42,
  "documento":       "000001234",   // Número NF-e
  "serie":           "001",
  "operacao":        "S",
  "tipo_transacao":  "VENDA",       // Fixo neste canal
  "cancelado":       "N",           // Derivado de movimentacao.situacao; na query atual tende a "N"
  "delivery":        false,
  "itens": [
    {
      "cod_produto":        "PROD-001",
      "descricao_produto":  "Camiseta Branca M",
      "cod_barra":          "7891234567890",
      "quantidade":         2,
      "preco_unitario":     89.90,
      "valor_total":        179.80
    }
  ]
}

Dicionário de campos

Campo	Origem no banco	Descrição
`identificador`	`movimentacao.id`	Chave da venda — usada no agrupamento
`data_documento`	`movimentacao.data_emissao`	Data/hora da venda em ISO 8601
`cod_vendedor`	`pessoa.codigo`	Código do vendedor responsável
`codigo_cliente`	`movimentacao.id_pessoa`	ID do cliente
`cnpj_emp`	`juridica.cnpj`	CNPJ da loja
`documento`	`movimentacao_nfe.numero`	Número da NF-e
`serie`	`movimentacao_nfe.serie`	Série da NF-e
`cancelado`	Derivado de `movimentacao.situacao`	Como a query filtra `m.situacao <> 'Cancelado'`, na prática tende a `"N"`
`tipo_transacao`	Hardcoded	Sempre `"VENDA"` neste canal
`itens[].cod_barra`	`movimentacao_detalhe.codigo_ean`	EAN do produto
`itens[].valor_total`	`movimentacao_detalhe.valor_rateio`	Valor rateado retornado como total do item

Cancelamentos no cabeçalho são filtrados O campo cancelado é calculado a partir de movimentacao.situacao, não de movimentacao_nfe.situacao; portanto, NF-e cancelada pode aparecer no join, mas esse cancelamento não altera automaticamente o flag retornado.