Módulo: Serviços da Agenda (Recebíveis)

Este documento descreve o módulo Serviços da Agenda do painel administrativo — a camada que administra os recebíveis gerados por serviços associados a agendamentos/comandas. Aqui ficam os fluxos de listar, editar, baixar (marcar como pago) e excluir, além do reflexo em caixa e comissões.

Visão do módulo

Tabela base

O módulo opera principalmente sobre a tabela receber (lançamentos a receber), exibindo e controlando o ciclo de vida do pagamento.

$tabela = "receber"

Origem dos registros

Registros em receber são criados quando um serviço é vinculado ao agendamento (ex.: agenda/inserir-servico.php ou agendamentos/inserir-servico.php) e também podem vir de comandas/vendas.

Agenda/Comanda → Receber

Estrutura de arquivos

Local no projeto (painel admin): sistema/painel/paginas/

sistema/painel/paginas/
  ├─ servicos_agenda.php
  └─ servicos_agenda/
      ├─ listar.php
      ├─ salvar.php
      ├─ baixar.php
      └─ excluir.php

servicos_agenda.php: tela (filtros, tabela, modal de edição, JS do módulo).
listar.php: lista recebíveis (normalmente filtrado por data/status).
salvar.php: cria/edita lançamento em receber (dados e status).
baixar.php: marca recebível como pago e faz reflexos (caixa/comissão, quando aplicável).
excluir.php: exclusão do lançamento (alto impacto — use com cuidado).

Modelo de dados e status

Campos variam conforme a instalação, mas o módulo assume, na prática, um conjunto de informações: cliente, descrição, valor, status de pagamento, data/hora e vínculo com usuário/profissional.

pago: status do recebimento (ex.: Sim / Não).
pgto: forma de pagamento (Dinheiro, PIX, Cartão, etc.).
data_pgto: data de pagamento (quando baixado).
caixa: id do caixa aberto usado na baixa (quando o sistema exige caixa).
hash: identificador auxiliar usado para rastrear itens do mesmo fluxo (alterações/migração).

Integrações comuns: consulta de dados do cliente em clientes, dados do usuário/profissional em usuarios, vínculo com agendamento em agendamentos e reflexos de comissão em pagar.

Endpoints (AJAX)

Os endpoints retornam strings exatas. O módulo servicos_agenda.php usa o padrão com separador * em alguns retornos.

Listagem

servicos_agenda/listar.php — POST: dataInicial, dataFinal, status
SESSION usada no filtro/auditoria: id

Criar/Editar

servicos_agenda/salvar.php — POST (principais): id, valor, descricao, pessoa, data, hora, pgto
Retorno: Salvo com Sucesso*<id>

Baixar (pagar)

servicos_agenda/baixar.php — POST: id, valor, data_pgto, pgto
Retorno: Baixado com Sucesso

Excluir

servicos_agenda/excluir.php — POST: id
Retorno: Excluído com Sucesso

Fluxo de baixa e caixa

A baixa (pagamento) é o ponto mais sensível do módulo, pois altera o financeiro. Em geral, o fluxo:

Recebe id, valor, pgto e data_pgto.
Atualiza o registro em receber para pago (campos de pagamento e data).
Se houver controle de caixa, tenta vincular a baixa a um caixas aberto.
Quando existe comissão configurada, pode gerar/atualizar lançamento em pagar para o profissional.

Dica de dev: se a baixa “não aparece no caixa”, valide primeiro se existe caixa aberto e depois a lógica de vínculo (campo caixa).

Pontos críticos (manutenção)

Alto impacto: excluir recebível pode quebrar relatório e conciliação — ideal exigir permissão e registrar log.
Transações: ao baixar, prefira transação (UPDATE em receber + INSERT/UPDATE em caixas/pagar).
Contrato do front: mensagens e separador * não podem mudar sem ajuste no JS.
Validação: conferir se valor é numérico e se o id pertence ao contexto/empresa do usuário.
SQL Injection: sempre usar prepare() com binds para inputs.

↑ voltar ao topo