Guia de Desenvolvimento de Pagamentos (Vanguru)

1. Visão Geral

Este documento define o guideline para o desenvolvimento da funcionalidade de pagamento no aplicativo Vanguru, integrando: - Backend API: Nossa API de pagamentos (conforme api/payments.md) - Asaas Platform: Plataforma de pagamento e split de valores - Regras de Negócio: Requisitos específicos do projeto

2. Arquitetura da Solução

2.1. Fluxo Geral

┌─────────────────┐
│   Flutter App   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Backend API    │ ◄──────► Asaas API
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│    Firestore    │
└─────────────────┘

2.2. Entidades Principais

2.2.1. Payment (Firestore Collection: `payments`)

Entidade separada do Passageiro para garantir independência e escalabilidade.

enum PaymentStatus {
  pending,
  confirmed,
  received,
  overdue,
  refunded,
  canceled,
}

enum PaymentBillingType {
  creditCard,
  boleto,
  pix,
  debitCard,
}

2.2.2. PaymentProfile (Subcoleção de Passenger: `passengers/{id}/paymentProfile`)

Dados de perfil de pagamento do usuário, separados para segurança.

3. Integração com Backend API

3.1. Endpoints Principais

POST /v1/customer: Criar cliente no Asaas.
POST /v1/payment: Criar novo pagamento.
POST /v1/subaccount: Criar subconta Asaas para split de pagamentos.
GET /v1/document/pending: Verificar documentos da subconta.

4. Integração com Asaas

4.1. Fluxo de Split

Cada usuário (Motorista/Condutor) precisa de uma subconta Asaas.
A subconta permite o split automático dos valores recebidos.
É necessário o envio de documentos para verificação da subconta para liberação de saques.

5. Implementação Flutter

5.1. Estrutura de Pastas

O projeto segue a Clean Architecture com a funcionalidade de pagamentos isolada em lib/features/payments/.

5.2. Mock vs Real

Sempre use o PaymentApiServiceMock durante o desenvolvimento para evitar consumo de créditos/APIs reais desnecessariamente.

6. Roadmap de Implementação

Fase 1: Estrutura Base (Mock) - Modelos e Repositories.
Fase 2: Perfil de Pagamento - Cadastro e Opt-in.
Fase 3: Documentos - Upload e Verificação.
Fase 4: Gestão de Pagamentos - Listagem e Detalhes.
Fase 5: Integração Real Sandsbox/Prod.