Fontes de dados para APIs (EC, propostas, dashboard, comissões, aluguel)

Documentação de quais tabelas usar para expor os dados descritos no produto, com base nos scripts PHP existentes em config/ e nas páginas do dashboard/. Não há no repositório um dump completo de schema; a referência são estes ficheiros e o estado real da base MySQL (DESCRIBE tabela).

---

Visão geral por domínio

Domínio	Tabelas principais	Observação
Cadastro EC	estabelecimentos_locais, users, white_labels	EC → representante: estabelecimentos_locais.user_id → users.id.
Propostas	propostas, proposta_taxas	Valores do formulário da proposta; não confundir com TPV.
Transações / dashboard	transacoes_locais, estabelecimentos_locais	TPV e métricas operacionais; referência: config/graficos/dashboard/buscar_transacoes_locais.php.
Comissões	transacoes_locais + tabelas de taxas	Ver config/financeiro/comissoes/buscar_comissoes_financeiras.php e funcoes_taxas.php.
Aluguel de máquinas	entrepay_dispositivos, terminais_locais, estabelecimentos_locais, users, white_labels	Totais globais: apenas entrepay_dispositivos.status = 'ATIVO' — ver config/financeiro/listar_alugueis_dispositivos.php.

---

1. Estabelecimento (cadastro e detalhes)

Tabela central: estabelecimentos_locais

Campos alinhados ao modal de cadastro/detalhe de EC e declarados no formulário (não calculados pelo sistema):

Campo	Uso
razao_social, nome_fantasia	Razão social e nome fantasia
cpf_cnpj	CPF/CNPJ
mcc, cnae	MCC e CNAE
status, situacao	Situação operacional/compliance (rótulos na UI podem compor texto a partir destes campos)
faturamento_mensal	Faturamento mensal declarado
valor_patrimonio	Valor de património declarado

Outros campos úteis no mesmo registo: ec_id_api, user_id, tipo, contato_principal, endereços/financeiros conforme o ecrã.

Relações

• Representante: estabelecimentos_locais.user_id → users (ex.: nome_completo).
• White label: users.white_label_id → white_labels (nome com lógica PF/PJ em vários SQLs do projeto).

Scripts de referência

• config/estabelecimentos/buscar_estabelecimento_por_id.php — detalhe por estabelecimento_id.
• config/estabelecimentos/listar_estabelecimentos_locais.php — listagem com valor_patrimonio, faturamento_mensal.
• config/estabelecimentos/atualizar_estabelecimento_local.php — persistência de valores declarados (atenção à conversão centavos/reais no script).

Regra de produto

Para APIs de cadastro/detalhe de EC, usar sempre faturamento_mensal e valor_patrimonio em estabelecimentos_locais. Não usar totais agregados de transacoes_locais como substituto destes campos.

---

2. Propostas / clientes de proposta

Tabela: propostas

Campos gravados no insert (config/propostas/salvar_proposta.php), alinhados ao formulário de proposta:

Campo	Uso
nome_fantasia, nome, cnpj, cpf, tipo_pessoa	Identificação do cliente
faturamento	Faturamento informado na proposta (tipo no código: inteiro — validar unidade no ambiente real)
tem_maquina, quantidade_maquina	Se tem máquina e quantidade
tem_gateway, limite_gateway	Gateway/TEF: sim/não e limite numérico
cnae, mcc	CNAE e MCC da proposta
white_label_id, representante_cpf, etc.	Contexto de canal / representante

Tabela auxiliar: proposta_taxas

Taxas por proposta: proposta_id, bandeira, tipo, parcela, taxa — usada ao gravar proposta com taxas.

Gateway com nome (ex.: Stone, Cielo)

No salvar_proposta.php não aparece coluna de texto com o nome da adquirente/gateway; só tem_gateway e limite_gateway. Se a UI de mock mostra “Stone/Cielo”, isso pode exigir:

• coluna extra em propostas na base real, ou
• mapeamento noutra tabela — confirmar com SHOW COLUMNS FROM propostas no MySQL.

Regra de produto

Métricas desta área são por linha de propostas (ou join controlado), não totais consolidados do ecossistema nem TPV.

Identificador “P-xxxxx”

Costuma ser o id da proposta formatado no frontend; na API pode expor-se id numérico e, se necessário, um campo derivado codigo_exibicao.

---

3. Indicadores operacionais (dashboard) — TPV realizado

Tabela principal: transacoes_locais

Ligação ao EC local:

• transacoes_locais.merchant_id = estabelecimentos_locais.ec_id_api

Campos relevantes

Métrica / painel	Origem
Total bruto (TPV)	amount (em centavos no PHP atual; somar apenas status = 'APPR' para volume “realizado”)
Valor líquido	valor_liquido se a coluna existir; senão fallback documentado no PHP para registos antigos
Contagens por status	status (APPR, DENY, PEND, CANC, …)
Distribuição por bandeira	card_brand; PIX pode usar payment_method
Ticket médio	Soma bruta APPR ÷ contagem APPR
Amostra / tabela	start_date, card_brand, installments, payment_method, amount, valor_liquido, status, nome do EC via join
Nome do estabelecimento	Join estabelecimentos_locais em ec_id_api, ou campo derivado merchant_name

Top N estabelecimentos por TPV no período

Agrupar por merchant_id (ou por estabelecimentos_locais.id), filtro de datas em start_date, status = 'APPR', SUM(amount), ordenar, LIMIT N.

Script de referência

• config/graficos/dashboard/buscar_transacoes_locais.php — permissões (dashboard.ver_todos), hierarquia WL/representante, conversão de datas São Paulo ↔ UTC.

Regra de produto

Aqui é TPV de transações (e líquido quando existir), não faturamento_mensal do cadastro do EC.

---

4. Financeiro — comissões

Fonte transacional

• transacoes_locais com tl.status = 'APPR' no intervalo start_date.
• Join obrigatório com estabelecimentos_locais em tl.merchant_id = el.ec_id_api.
• Representante / marketplace / WL: users (u_rep, u_mkt) e white_labels — ver query em config/financeiro/comissoes/buscar_comissoes_financeiras.php.

Cálculo de comissões

• config/financeiro/comissoes/funcoes_taxas.php — hierarquia de taxas: plano (estabelecimentos_locais.plano_id → plano_taxas_cet), user_taxas, taxas de white label, taxa padrão; uso de bandeiras e tipo de pagamento/parcelas.

Tabela resumo na UI

Volume, número de transações e comissão por estabelecimento são derivados do processamento transação a transação no PHP, salvo existir tabela materializada noutro ambiente.

Detalhes por nível (spreads)

• config/financeiro/comissoes/buscar_detalhes_estabelecimento.php — mesmo núcleo (transacoes_locais + taxas).

Permissão

• financeiros.ver_todos — amplia visão na lógica de comissões.

---

5. Financeiro — aluguel de máquinas

Tabelas

Tabela	Papel
entrepay_dispositivos	Contrato de aluguel: estabelecimento_id, dispositivo_id, valor_aluguel, status, datas, etc.
terminais_locais	Equipamento físico (id = entrepay_dispositivos.dispositivo_id)
estabelecimentos_locais	Dados do EC
users	Representante do EC (el.user_id)
white_labels	Nome do WL do representante

Regra de totais globais

Conforme config/financeiro/listar_alugueis_dispositivos.php:

• Contar máquinas e somar aluguel só quando entrepay_dispositivos.status = 'ATIVO'.
• Agrupamentos por estabelecimento seguem a mesma regra para totais; listas podem incluir outros status conforme o endpoint.

Resumo agregado por EC

Agrupar por estabelecimento_id: soma de valor_aluguel e contagem de linhas ATIVO; média = total aluguel ÷ nº de máquinas ativas do grupo.

---

Chaves e dependências cruzadas

De	Para	Campo
Transação	EC local	transacoes_locais.merchant_id = estabelecimentos_locais.ec_id_api
EC	Representante	estabelecimentos_locais.user_id = users.id
Transação	WL (quando aplicável)	transacoes_locais.white_label_id pode ser NULL; o código completa visão via users.white_label_id do EC/representante

---

Mapa rápido para implementação de APIs

1. API EC (valores declarados): estabelecimentos_locais + users + white_labels.
2. API listagem de propostas / linha de proposta: propostas (+ proposta_taxas se necessário).
3. API dashboard / TPV / top estabelecimentos / bandeira / status: agregações em transacoes_locais com filtros de período e status; nomes via estabelecimentos_locais.
4. API comissões: mesma base transacional APPR + funcoes_taxas.php (ou reimplementar a mesma hierarquia no Nest).
5. API aluguel: entrepay_dispositivos com joins a terminais_locais, estabelecimentos_locais, users, white_labels; totais só ATIVO.

---

Próximos passos sugeridos no ambiente real

• Validar tipos exatos e unidades (amount, faturamento, limite_gateway) com DESCRIBE nas tabelas.
• Se o back Nest usar outro schema, alinhar mapeamentos ou views com estas tabelas MySQL legadas.