1. O Gargalo do Billing em Novos SaaS
Mais de 60% do tempo de desenvolvimento de um novo SaaS é gasto em código que o cliente não vê: rotinas de renovação de cartão, cancelamento suave, recuperação de boletos não pagos, controle de dias de carência antes do bloqueio e conciliação de planos antigos com novos.
A Brief App isola essa complexidade em um módulo independente de faturamento, expondo endpoints REST diretos para criar planos, assinar e consultar permissões.
2. Ciclo de Vida da Assinatura e Carência
O ciclo de vida da assinatura no PostgreSQL trata automaticamente transições de status com base em webhooks dos gateways:
- Ativa: Pagamento em dia. O usuário possui acesso aos recursos contratados e à cota mensal de créditos.
- Em Carência (Inadimplente): Ocorreu falha no cartão ou PIX expirado. O sistema concede de 3 a 7 dias de tolerância antes de bloquear as funcionalidades, enviando notificações ao cliente.
- Cancelada: O cliente solicitou o cancelamento. O acesso permanece ativo até o fim do ciclo vigente já pago.
- Encerrada: Sem renovação ou cancelada definitivamente.
3. Modelo Híbrido: Recorrência + Créditos Pré-Pagos
Além da mensalidade fixa, a API possui um ledger imutável de créditos. Isso permite modelos modernos de cobrança:
- O cliente paga R$ 99/mês e recebe 100 créditos para usar em agendamentos, geração de relatórios ou consultas de IA.
- Ao consumir um serviço, chame
POST /api/billing/credits/{clienteId}/debit. - Se o serviço for cancelado com antecedência, chame
POST /api/billing/credits/{clienteId}/refundpara estorno seguro. - Créditos adicionais avulsos podem ser adquiridos a qualquer momento via
POST /api/billing/credits/{clienteId}/add.
4. Endpoints Principais de Faturamento
| Método & Rota | Papel | Finalidade |
|---|---|---|
GET /api/billing/plans |
Público / Autenticado | Lista os planos disponíveis para novas contratações. |
POST /api/billing/plans |
Admin, Financeiro | Cria um novo plano com preço, periodicidade e créditos inclusos. |
POST /api/billing/subscriptions |
Autenticado | Cria uma nova assinatura para o cliente com cartão ou PIX. |
GET /api/billing/subscriptions/client/{id} |
Dono ou Admin | Histórico completo de assinaturas e faturas do usuário. |
POST /api/billing/subscriptions/{id}/cancel |
Dono ou Admin | Cancela a assinatura (no fim do período ou imediatamente). |
GET /api/billing/credits/{clienteId} |
Dono ou Admin | Consulta o saldo em tempo real de créditos disponíveis. |
5. Exemplo de Criação de Assinatura via API
POST /api/billing/subscriptions
Authorization: Bearer <token_do_usuario>
X-Idempotency-Key: f92a101b-c128-482a-9e10-91823abce128
Content-Type: application/json
{
"clienteId": "7b1c4912-9c02-4a0b-9321-df54129031ef",
"planoId": "plan_starter_pro_monthly",
"metodoPagamento": "CreditCard",
"cartaoToken": "tok_card_asaas_88291039"
}