Sistema de Pagamentos - Visão Geral

Conceito Fundamental: Free vs Premium

O sistema de pagamentos do Vanguru foi projetado para atender dois perfis distintos de usuários através de uma arquitetura unificada que suporta tanto gestão manual (Free) quanto automação completa (Premium).

Diferença Fundamental

FREE = MANUAL - ✋ Registro de contrato: Manual (sem envio automático de termos) - ✋ Aceite de contrato: Manual (responsável não recebe link, aceite é registrado pelo dono) - ✋ Geração de cobranças: Manual (dono cria cada cobrança quando quiser) - ✋ Registro de pagamento: Manual (dono marca como pago após receber) - ✋ Compartilhamento de dados: Manual (dono envia dados via WhatsApp/email) - ✋ Notificações: Manual (dono avisa o responsável quando quiser)

PREMIUM = AUTOMÁTICO - 🤖 Registro de contrato: Automático (sistema envia link de aceite) - 🤖 Aceite de contrato: Automático (responsável acessa link e aceita) - 🤖 Geração de cobranças: Automático (Asaas gera 40 dias antes) - 🤖 Registro de pagamento: Automático (webhook atualiza status) - 🤖 Compartilhamento de dados: Automático (boleto/PIX enviado por email/SMS) - 🤖 Notificações: Automático (Asaas envia lembretes)

Estado Atual da Implementação

✅ O Que Está Implementado

Estrutura de Dados (Fase 1 - Completa)

Enums: - ✅ payment_status.dart - Status de pagamentos (pending, confirmed, received, overdue, refunded, canceled) - ✅ payment_frequency.dart - Frequência de pagamentos (monthly, bimonthly, quarterly, etc.)

Exceções: - ✅ payment_exceptions.dart - Hierarquia completa de exceções customizadas

Modelos: - ✅ payment.dart - Modelo de pagamento com campos básicos e métodos auxiliares - ✅ payment_profile.dart - Perfil de pagamento (subcoleção de Passenger)

Serviços: - ✅ payment_api_service.dart - Interface abstrata para API de pagamentos - ✅ payment_api_service_mock.dart - Implementação mock completa para desenvolvimento

UI: - ✅ payment_placeholder_screen.dart - Tela de listagem de passageiros com indicadores de contrato - ✅ payment_passenger_tile.dart - Widget de exibição de passageiro com status de pagamento

❌ O Que NÃO Está Implementado

  • ❌ Entidade Contract (Contrato)
  • ❌ Repositories de Payment e PaymentProfile
  • ❌ Controllers Riverpod para gestão de estado
  • ❌ Telas de criação/edição de contratos
  • ❌ Telas de gestão de pagamentos
  • ❌ Integração real com backend/Asaas
  • ❌ Sistema de webhooks
  • ❌ Upload de documentos
  • ❌ Processamento de pagamentos

Arquitetura Técnica

Estrutura de Dados Unificada

contracts/
  {contractId}/
    - tier: 'free' | 'premium'
    - passengerId
    - responsibleId
    - monthlyValue
    - contractedMonths
    - status
    - asaasSubscriptionId (null se tier = free)
    - paidInstallments
    - ...

payments/
  {paymentId}/
    - contractId
    - passengerId
    - value
    - dueDate
    - status
    - asaasPaymentId (null se tier = free)
    - manualMethod (null se tier = premium)
    - proofImageUrl (null se tier = premium)
    - ...

Modelo Híbrido: Contrato + Asaas Subscription

┌─────────────────────────────────────────────────────────┐
│                    CONTRATO (Nosso)                     │
│  - Formalização jurídica                                │
│  - Snapshots de passageiro e responsável                │
│  - Termos contratuais (meses, valor total, período)     │
│  - Aceite de termos e opt-in                            │
│  - Status do contrato (draft, pending, active, etc.)    │
│  - Observações e histórico                              │
└─────────────────┬───────────────────────────────────────┘
                  │
                  │ Cria e gerencia (Premium)
                  ▼
┌─────────────────────────────────────────────────────────┐
│              SUBSCRIPTION (Asaas)                       │
│  - Agendamento de cobranças recorrentes                 │
│  - Geração automática de payments                       │
│  - Integração com gateway de pagamento                  │
│  - Webhooks de eventos                                  │
└─────────────────┬───────────────────────────────────────┘
                  │
                  │ Gera automaticamente
                  ▼
┌─────────────────────────────────────────────────────────┐
│                 PAYMENT (Asaas)                         │
│  - Cobrança individual                                  │
│  - Boleto/PIX/Cartão                                    │
│  - Status de pagamento                                  │
│  - Vinculado ao subscription                            │
└─────────────────────────────────────────────────────────┘

Funcionalidades por Tier

Free Tier

✅ Gestão de Contratos (Completa)

  • Criar contratos com todos os termos
  • Enviar para aceite do responsável
  • Visualizar histórico completo
  • Suspender/reativar/cancelar
  • Snapshots e auditoria

✅ Controle de Pagamentos (Manual)

  • Criar cobranças manualmente
  • Marcar como pago/pendente/atrasado
  • Adicionar comprovantes (fotos)
  • Histórico de pagamentos
  • Notificações de vencimento (in-app)

✅ Relatórios Básicos

  • Lista de inadimplentes
  • Pagamentos do mês
  • Histórico por passageiro
  • Exportação básica (CSV)

Premium Tier

✅ Gestão de Contratos (Automática)

  • Tudo do Free
  • Integração com Asaas Subscription
  • Envio automático de termos
  • Link de aceite para responsável

✅ Cobranças Automáticas

  • Asaas gera cobranças automaticamente
  • Suporte a boleto, PIX, cartão de crédito/débito
  • Notificações automáticas de vencimento
  • Webhooks para atualização de status

✅ Split de Pagamento

  • Divisão automática de valores recebidos
  • Configuração de percentual ou valor fixo
  • Repasse para conta do dono do negócio
  • Reversível em caso de estorno

✅ Documentação e Compliance

  • Snapshots de dados no momento da assinatura
  • Registro de aceite de termos
  • Histórico completo de alterações
  • Auditoria de todas as operações

✅ Relatórios Financeiros

  • Visão consolidada de recebimentos
  • Inadimplência por passageiro
  • Projeção de receitas
  • Exportação de dados

Casos de Uso

Quando Usar Free

  • Pequeno prestador (1-10 passageiros)
  • Prefere receber em dinheiro/PIX manual
  • Não quer pagar taxas de gateway
  • Testando o aplicativo
  • Região com baixa adoção de pagamentos digitais

Quando Usar Premium

  • Médio/grande prestador (10+ passageiros)
  • Quer automatizar cobranças
  • Precisa de comprovantes oficiais
  • Quer oferecer múltiplas formas de pagamento
  • Necessita de split de pagamento
  • Busca profissionalização

Migração Free → Premium

Processo

  1. Usuário decide migrar para premium
  2. Completa perfil de pagamento
  3. Envia documentos
  4. Aguarda aprovação Asaas
  5. Sistema oferece migração de contratos:
  6. Contratos ativos podem ser migrados
  7. Cria Subscription no Asaas
  8. Mantém histórico de pagamentos anteriores
  9. Próximas cobranças são automáticas

Dados Preservados

  • ✅ Histórico completo de contratos
  • ✅ Pagamentos já registrados
  • ✅ Snapshots e aceites
  • ✅ Comunicações anteriores

Roadmap de Implementação

Fase 1: Estrutura Base Unificada (1-2 semanas)

  • [ ] Atualizar modelo Contract com campo tier
  • [ ] Atualizar modelo Payment com campos manuais
  • [ ] Criar enum ContractTier
  • [ ] Criar enum ManualPaymentMethod
  • [ ] Criar repositories unificados
  • [ ] Testes unitários

Fase 2: Funcionalidade Free (2-3 semanas)

  • [ ] Tela de criação de contrato (tier: free)
  • [ ] Tela de listagem de contratos
  • [ ] Tela de detalhes do contrato
  • [ ] Tela de listagem de pagamentos
  • [ ] Tela de registro manual de pagamento
  • [ ] Upload de comprovantes
  • [ ] Job de geração de cobranças free
  • [ ] Notificações in-app
  • [ ] Testes de integração

Fase 3: Funcionalidade Premium (3-4 semanas)

  • [ ] Implementar PaymentApiServiceImpl (real)
  • [ ] Integração com Asaas Subscription API
  • [ ] Webhook handlers
  • [ ] Tela de completar perfil
  • [ ] Tela de upload de documentos
  • [ ] Tela de opt-in
  • [ ] Migração free → premium
  • [ ] Testes em sandbox Asaas

Fase 4: Refinamentos e Lançamento (1-2 semanas)

  • [ ] Relatórios financeiros
  • [ ] Exportação de dados
  • [ ] Melhorias de UX
  • [ ] Documentação de usuário
  • [ ] Testes de carga
  • [ ] Deploy em produção

Total Estimado: 7-11 semanas

Métricas de Sucesso

Free

  • Adoção: 80%+ dos novos usuários começam no free
  • Engajamento: 60%+ criam pelo menos 1 contrato
  • Retenção: 70%+ ativos após 30 dias

Premium

  • Conversão: 20%+ dos usuários free migram para premium
  • Tempo para Conversão: Média de 60 dias
  • Satisfação: NPS > 8

Geral

  • Crescimento: 30%+ MoM em usuários ativos
  • Receita: R$ 10k+ MRR em 6 meses (premium)
  • Suporte: < 5% de tickets relacionados a pagamentos

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