Appearance
Billing & Assinaturas
Visao Geral
O modulo de Billing (Domain/Billing) gerencia assinaturas SaaS e cobrancas via Asaas (gateway brasileiro). Igrejas pagam mensalidade por PIX ou cartao de credito. O sistema detecta inadimplencia e aplica restricoes graduais automaticamente.
AsaasService
App\Domain\Billing\Services\AsaasService — cliente HTTP para a API Asaas v3.
| Metodo | Endpoint Asaas | Uso |
|---|---|---|
createCustomer(data) | POST /customers | Cadastrar igreja como customer |
createSubscription(customerId, data) | POST /subscriptions | Criar assinatura recorrente |
updateSubscription(id, data) | PUT /subscriptions/ | Alterar plano/valor |
cancelSubscription(id) | DELETE /subscriptions/ | Cancelar assinatura |
createPayment(customerId, data) | POST /payments | Cobranca avulsa |
getPaymentStatus(id) | GET /payments/ | Consultar status |
getPixQrCode(id) | GET /payments/{id}/pixQrCode | QR code PIX |
createSubAccount(data) | POST /accounts | Sub-conta para igreja (13B-2) |
get(path) | GET | Consulta generica |
Configuracao via Http::asaas() macro (retry 3x em 5xx, header access_token).
Models (Banco Central)
Subscription
| Campo | Tipo | Descricao |
|---|---|---|
| ulid | string(26) | Identificador publico |
| tenant_id | FK → tenants | Igreja |
| plan_id | FK → plans | Plano |
| asaas_subscription_id | string | ID no Asaas |
| asaas_customer_id | string | Customer ID no Asaas |
| status | enum | trialing, active, past_due, suspended, cancelled |
| billing_cycle | enum | monthly, yearly |
| price | decimal(8,2) | Valor |
| trial_ends_at | timestamp | Fim do trial |
| current_period_start/end | timestamp | Periodo atual |
| cancelled_at | timestamp | Data cancelamento |
Invoice
| Campo | Tipo | Descricao |
|---|---|---|
| ulid | string(26) | Identificador publico |
| subscription_id | FK | Assinatura |
| tenant_id | FK | Igreja |
| asaas_payment_id | string | ID pagamento no Asaas |
| status | enum | pending, confirmed, overdue, refunded, cancelled |
| amount | decimal(8,2) | Valor |
| payment_method | enum | pix, credit_card, boleto |
| due_date | date | Vencimento |
| paid_at | timestamp | Data pagamento |
Enums
- SubscriptionStatus: Trialing, Active, PastDue, Suspended, Cancelled
- InvoiceStatus: Pending, Confirmed, Overdue, Refunded, Cancelled
- BillingCycle: Monthly, Yearly
- PaymentMethod: Pix, CreditCard, Boleto
Actions
| Action | Descricao |
|---|---|
| CreateSubscriptionAction | Cria customer + subscription no Asaas (ou local-only para plano free) |
| ChangeSubscriptionPlanAction | Upgrade/downgrade — atualiza Asaas + Subscription + Tenant |
| CancelSubscriptionAction | Cancela no Asaas, marca cancelled_at |
| HandlePaymentConfirmedAction | Webhook — marca Invoice paga, reverte restricoes |
| HandlePaymentOverdueAction | Webhook — marca Invoice vencida, subscription past_due |
| RevertOverdueRestrictionsAction | Remove banner, read_only, suspended_at |
| ActivateOverdueBannerAction | Ativa flag show_overdue_banner no tenant |
| ActivateReadOnlyModeAction | Ativa read_only + banner no tenant |
Webhooks
Rota publica: POST /webhooks/asaas (validado por asaas-access-token header).
| Evento Asaas | Action |
|---|---|
| PAYMENT_CONFIRMED | HandlePaymentConfirmedAction |
| PAYMENT_RECEIVED | HandlePaymentConfirmedAction |
| PAYMENT_OVERDUE | HandlePaymentOverdueAction |
Pipeline de Inadimplencia
Job diario ProcessOverdueSubscriptionsJob (06:00):
| Dias apos vencimento | Acao | Impacto |
|---|---|---|
| 1-3 | Email lembrete | Nenhum |
| 4-7 | Banner de aviso | Visual |
| 8-15 | Modo somente leitura | Bloqueia escrita |
| 16+ | Suspensao total | Login bloqueado |
Pagamento reverte tudo automaticamente.
Middleware
- EnsureNotReadOnly — bloqueia POST/PUT/PATCH/DELETE quando tenant
read_only = true - Billing status no Inertia shared props:
billing.show_overdue_banner,billing.read_only
Endpoints (Tenant)
| Metodo | Rota | Descricao |
|---|---|---|
| GET | /settings/subscription | Painel de assinatura |
| POST | /settings/subscription/change-plan | Trocar plano |
| POST | /settings/subscription/cancel | Cancelar assinatura |
Endpoints (Admin Central)
| Metodo | Rota | Descricao |
|---|---|---|
| GET | /admin/billing | Dashboard KPIs |
| GET | /admin/billing/subscriptions | Listagem assinaturas |
| GET | /admin/billing/invoices | Listagem faturas |
| POST | /admin/billing/subscriptions/{ulid}/cancel | Cancelar assinatura |
Permissions
| Permissao | Roles |
|---|---|
| manage-billing | admin-igreja |
Painel Central Financeiro
O dashboard do admin central (/admin) exibe KPIs financeiros consolidados da plataforma:
Receita:
| KPI | Fonte | Descricao |
|---|---|---|
| MRR (Assinaturas) | Subscription::active()->sum('price') | Receita recorrente mensal de assinaturas |
| Receita de Split | Doacoes * 3% | Receita do Decaelo sobre doacoes processadas |
| Receita Total | MRR + Split | Receita combinada da plataforma |
Volume:
| KPI | Descricao |
|---|---|
| Doacoes Processadas | Valor total de doacoes confirmadas cross-tenant |
| Doacoes no Mes | Quantidade de doacoes confirmadas no mes atual |
| Recorrencias Ativas | Dizimos recorrentes ativos em todos os tenants |
Cada KPI de receita exibe variacao percentual vs mes anterior.
Variaveis de Ambiente
env
ASAAS_API_KEY=
ASAAS_ENVIRONMENT=sandbox
ASAAS_WEBHOOK_TOKEN=
ASAAS_WALLET_ID=
ASAAS_SPLIT_PERCENTAGE=3.0