Sistema de Pagamentos - Vanguru

Visão Geral

O sistema de pagamentos do Vanguru permite o controle financeiro completo, desde a geração de cobranças até o recebimento e conciliação, suportando tanto gestão manual (Free) quanto automação completa (Premium).

Diferença Fundamental: Free vs Premium

FREE = MANUAL

✋ Geração de cobranças: Manual (dono cria quando quiser)
✋ Registro de pagamento: Manual (dono marca como pago após receber)
✋ Compartilhamento: Manual (dono envia dados via WhatsApp/email)
✋ Notificações: Manual (dono avisa o responsável)
✋ Comprovantes: Upload de foto (opcional)

PREMIUM = AUTOMÁTICO

🤖 Geração de cobranças: Automático (Asaas gera 40 dias antes)
🤖 Registro de pagamento: Automático (webhook atualiza status)
🤖 Compartilhamento: Automático (boleto/PIX enviado por email/SMS)
🤖 Notificações: Automático (Asaas envia lembretes)
🤖 Comprovantes: Gerado pelo Asaas (boleto, recibo)

Entidade Payment

Estrutura de Dados

class Payment {
  // Identificação
  final String? id;
  final String contractId;
  final String passengerId;

  // Valores
  final double value;
  final DateTime dueDate;
  final DateTime? paidDate;

  // Status
  final PaymentStatus status;

  // Tier-specific
  final String? asaasPaymentId;  // Premium apenas
  final ManualPaymentMethod? manualMethod;  // Free apenas
  final String? proofImageUrl;  // Free apenas

  // Metadados
  final DateTime createdAt;
  final DateTime? updatedAt;
}

Enums

PaymentStatus

enum PaymentStatus {
  pending,      // Aguardando pagamento
  confirmed,    // Pagamento confirmado (aguardando compensação)
  received,     // Pagamento recebido e compensado
  overdue,      // Vencido
  refunded,     // Estornado
  canceled,     // Cancelado
}

ManualPaymentMethod (Free)

enum ManualPaymentMethod {
  cash,           // Dinheiro
  bankTransfer,   // Transferência bancária
  pix,            // PIX manual
  check,          // Cheque
  other,          // Outro
}

Funcionalidades por Tier

Free Tier

Geração Manual de Cobranças

1. Sistema gera cobranças baseado no contrato:
   - Frequência (mensal, bimestral, etc.)
   - Dia de vencimento
   - Valor definido
2. Cobrança criada no Firestore (status: pending)
3. Notificação in-app para o dono do negócio
4. Dono pode:
   - Copiar dados para envio manual
   - Enviar lembrete ao responsável
   - Aguardar pagamento

Registro Manual de Pagamento

1. Responsável paga (dinheiro, PIX manual, etc.)
2. Dono do negócio marca como pago:
   - Seleciona método de pagamento
   - Opcionalmente anexa comprovante (foto)
   - Confirma pagamento
3. Sistema atualiza:
   - Payment.status = received
   - Payment.paidDate = now
   - Payment.manualMethod = [método escolhido]
   - Contract.paidInstallments++

Comprovantes

Upload de foto do comprovante
Armazenamento no Firebase Storage
Visualização na tela de detalhes
Opcional (não obrigatório)

Premium Tier

Geração Automática (Asaas)

1. Asaas Subscription gera cobrança automaticamente
   - 40 dias antes do vencimento
   - Baseado no ciclo definido (monthly, etc.)
2. Webhook PAYMENT_CREATED recebido
3. Sistema:
   - Cria Payment no Firestore
   - Vincula asaasPaymentId
   - Status = pending
4. Asaas envia boleto/PIX por email ao responsável

Atualização Automática via Webhooks

PAYMENT_RECEIVED:

1. Webhook recebido do Asaas
2. Sistema busca Payment por asaasPaymentId
3. Atualiza:
   - status = received
   - paidDate = webhook.paymentDate
   - Contract.paidInstallments++
4. Notificação in-app para dono do negócio

PAYMENT_OVERDUE:

1. Webhook recebido (pagamento vencido)
2. Sistema atualiza status = overdue
3. Asaas envia lembrete automático ao responsável
4. Notificação in-app para dono do negócio

Formas de Pagamento

Forma	Taxa Asaas	Prazo Compensação
Boleto	R$ 3,49	D+1 útil
PIX	0,99%	Imediato
Cartão Crédito	4,99%	D+30
Cartão Débito	2,99%	D+1 útil

Observação: Taxas são repassadas ao responsável (passageiro).

Fluxos de Uso

Free: Criar e Registrar Pagamento

1. Sistema gera cobrança automaticamente (job local)
2. Dono visualiza cobrança pendente no dashboard
3. Dono envia dados ao responsável (WhatsApp manual):
   - Valor: R$ 450,00
   - Vencimento: 10/02/2026
   - Dados bancários ou PIX
4. Responsável paga
5. Dono recebe comprovante (foto via WhatsApp)
6. Dono marca pagamento como recebido no app:
   - Seleciona método: PIX
   - Anexa foto do comprovante
   - Confirma
7. Sistema atualiza contrato e dashboard

Premium: Fluxo Automático

1. Asaas gera cobrança (40 dias antes)
2. Webhook PAYMENT_CREATED → Sistema cria Payment
3. Asaas envia boleto/PIX por email ao responsável
4. Responsável paga via boleto/PIX/cartão
5. Webhook PAYMENT_RECEIVED → Sistema atualiza Payment
6. Dono visualiza pagamento recebido no dashboard
7. Asaas faz split de pagamento (se configurado)
8. Valor cai na conta do dono (D+1 ou D+30)

Dashboard Financeiro

Visão Geral

Métricas Principais: - Receita do mês (recebida) - Receita prevista (pendente) - Inadimplência (vencidos) - Taxa de recebimento

Gráficos: - Receita mensal (últimos 12 meses) - Status de pagamentos (pizza) - Inadimplência por passageiro

Listagem de Pagamentos

Filtros: - Status (Todos, Pendente, Recebido, Vencido) - Período (Mês atual, Últimos 3 meses, Personalizado) - Passageiro - Contrato

Ordenação: - Data de vencimento - Data de pagamento - Valor - Status

Detalhes do Pagamento

Informações Exibidas: - Passageiro e responsável - Contrato vinculado - Valor e vencimento - Status e data de pagamento - Método de pagamento - Comprovante (se houver) - Histórico de alterações

Relatórios

Relatórios Básicos (Free + Premium)

Inadimplentes: - Lista de passageiros com pagamentos vencidos - Valor total em atraso - Dias de atraso - Exportação CSV

Pagamentos do Mês: - Lista de todos os pagamentos do mês - Agrupado por status - Total recebido vs previsto

Relatórios Avançados (Premium)

Receita Mensal: - Comparativo mês a mês - Gráfico de evolução - Projeção para próximos meses

Performance por Passageiro: - Histórico de pagamentos - Taxa de pontualidade - Valor total pago

Exportação: - CSV, PDF, Excel - Período customizável - Filtros avançados

Integração com Asaas (Premium)

Configuração Inicial

Requisitos: - Conta Asaas (PF ou PJ) - Documentos enviados e aprovados - API Key gerada

Processo: 1. Usuário completa perfil de pagamento 2. Envia documentos (RG, selfie, comprovante) 3. Aguarda aprovação (1-3 dias úteis) 4. Sistema armazena API Key (criptografada) 5. Cria Customer no Asaas para cada responsável

Webhooks

Eventos Processados: - PAYMENT_CREATED: Cobrança gerada - PAYMENT_RECEIVED: Pagamento recebido - PAYMENT_CONFIRMED: Pagamento confirmado - PAYMENT_OVERDUE: Pagamento vencido - PAYMENT_REFUNDED: Pagamento estornado - SUBSCRIPTION_UPDATED: Assinatura atualizada - SUBSCRIPTION_DELETED: Assinatura cancelada

Segurança: - Validação de assinatura do webhook - Processamento idempotente - Retry automático em caso de falha

Split de Pagamento (Futuro)

Conceito: - Divisão automática do valor recebido - Percentual ou valor fixo para Vanguru - Repasse automático para conta do dono

Exemplo: - Pagamento: R$ 450,00 - Split Vanguru: 2% = R$ 9,00 - Repasse Dono: R$ 441,00

Migração Free → Premium

Processo

1. Usuário decide migrar para premium
2. Completa perfil de pagamento
3. Envia documentos ao Asaas
4. Aguarda aprovação
5. Sistema oferece migração de contratos:
   - Contratos ativos migrados
   - Pagamentos futuros via Asaas
   - Histórico manual preservado
6. Próximas cobranças são automáticas

Dados Preservados

✅ Histórico de pagamentos manuais
✅ Comprovantes anexados
✅ Observações e notas
✅ Datas e métodos de pagamento

Segurança

Dados Sensíveis

Armazenamento: - API Key Asaas: Criptografada (AES-256) - Dados bancários: Não armazenados (Asaas cuida) - Comprovantes: Firebase Storage (acesso restrito)

Acesso: - Security Rules granulares - Apenas dono do negócio acessa - Logs de auditoria

Compliance

✅ PCI DSS: Asaas é certificado
✅ LGPD: Dados mínimos necessários
✅ Auditoria: Histórico completo de operações

Melhorias Futuras

Roadmap

Q2 2026: - [ ] Reconciliação bancária automática - [ ] Integração com bancos (Open Banking) - [ ] Relatórios fiscais (IRPF, CNPJ)

Q3 2026: - [ ] Split de pagamento - [ ] Programa de cashback - [ ] Parcelamento de mensalidades

Q4 2026: - [ ] Múltiplas contas bancárias - [ ] Antecipação de recebíveis - [ ] API de integração contábil

Métricas de Sucesso

Taxa de Recebimento: > 95%
Inadimplência: < 5%
Tempo de Reconciliação: < 1 dia (Premium)
Satisfação: NPS > 8
Conversão Free → Premium: 20%+

Documento: Sistema de Pagamentos
Versão: 1.0
Data: Janeiro 2026