Doacoes Online

Visao Geral

Modulo de doacoes online integrado ao Asaas, permitindo que membros logados e visitantes faca doacoes via PIX ou cartao de credito. Cada igreja possui uma sub-conta Asaas com split automatico (3% Decaelo, 97% igreja). Suporta doacoes avulsas e dizimo recorrente mensal.

Fluxo

1. Admin ativa feature online_donations no tenant
2. Pastor configura dados bancarios e CNPJ em /donations/settings
3. Sistema cria sub-conta Asaas automaticamente
4. Membros doam via /doar (logado) ou visitantes via link publico
5. PIX gera QR code; cartao processa via Asaas
6. Webhook confirma pagamento, cria Transaction no financeiro e envia recibo PDF por e-mail

Models

DonationSettings

Namespace: App\Domain\Donation\Models\DonationSettings

Tabela singleton (1 registro por tenant) com dados da sub-conta Asaas.

Campo	Tipo	Descricao
asaas_sub_account_id	string	ID da sub-conta no Asaas
asaas_sub_account_key	string	API key da sub-conta
cnpj	string(14)	CNPJ da igreja
banco	string	Nome do banco
agencia	string	Agencia
conta	string	Numero da conta
tipo_conta	string	corrente ou poupanca
responsavel_nome	string	Nome do responsavel financeiro
responsavel_email	string	E-mail do responsavel
is_active	boolean	Sub-conta ativa e configurada

DonationPayment

Namespace: App\Domain\Donation\Models\DonationPayment

Cada doacao individual. Usa ULID, SoftDeletes.

Campo	Tipo	Descricao
ulid	string	Identificador publico
member_id	FK nullable	Membro doador (null para visitantes)
transaction_id	FK nullable	Transaction criada apos confirmacao
asaas_payment_id	string	ID do pagamento no Asaas
asaas_subscription_id	string nullable	ID da subscription (recorrente)
donor_name	string	Nome do doador
donor_cpf	string nullable	CPF do doador
donor_email	string	E-mail do doador
category_id	FK	Categoria (Dizimo, Oferta, etc)
valor	decimal	Valor da doacao
payment_method	string	pix ou credit_card
status	DonationStatus	pending, confirmed, overdue, refunded, cancelled
is_recurring	boolean	Se e recorrencia mensal
pix_qrcode	text nullable	QR code base64 (PIX)
pix_copy_paste	text nullable	Codigo copia-e-cola (PIX)
receipt_path	string nullable	Caminho do PDF do recibo
paid_at	timestamp nullable	Data de confirmacao

Relationships: member(), transaction(), category(), congregation() Scopes: confirmed(), byMember(), recurring()

Actions

Action	Descricao
SetupDonationAccountAction	Cria sub-conta Asaas, salva DonationSettings
CreateDonationPaymentAction	Cria pagamento avulso (PIX ou cartao) com split 3%
CreateDonationSubscriptionAction	Cria assinatura recorrente mensal (cartao)
HandleDonationConfirmedAction	Webhook: confirma doacao, cria Transaction, gera recibo
HandleDonationRefundedAction	Webhook: marca como estornado, cancela Transaction
CancelDonationSubscriptionAction	Cancela assinatura no Asaas
GenerateDonationReceiptAction	Gera PDF recibo via Gotenberg e envia por e-mail

Rotas

Autenticadas (feature: online_donations)

Metodo	Rota	Controller	Permissao
GET	/donations/settings	DonationSettingsController@edit	finance.view
PUT	/donations/settings	DonationSettingsController@update	finance.create
GET	/donations	DonationController@index	finance.view
POST	/donations	DonationController@memberDonate	autenticado
GET	/donations/my	DonationController@myDonations	autenticado
DELETE	/donations/subscriptions/	DonationController@cancelSubscription	autenticado (owner)

Publicas

Metodo	Rota	Controller
GET	/doar	PublicDonationController@show
POST	/doar	PublicDonationController@store (throttle:10,1)

Split Automatico

Cada pagamento inclui configuracao de split Asaas: 3% para wallet Decaelo (ASAAS_WALLET_ID), 97% fica na sub-conta da igreja. Configuravel via ASAAS_SPLIT_PERCENTAGE.

Webhook

O webhook /webhooks/asaas roteia entre billing e doacoes via externalReference:

• Prefixo donation: → HandleDonationConfirmedAction / HandleDonationRefundedAction
• Sem prefixo → fluxo billing existente

Frontend

Pagina	Rota	Descricao
Donations/Settings.vue	/donations/settings	Setup: CNPJ, banco, categorias online
Donations/Index.vue	/donations	Painel admin: KPIs + tabela de doacoes
Donations/MyDonations.vue	/donations/my	Historico do membro + recorrencias
Donations/PublicDonate.vue	/doar	Pagina publica com logo da igreja

Feature Flag

online_donations — disponivel para TODOS os planos. Cada doacao gera receita de split para o Decaelo.