Sistema de Billing Desacoplado: A Abordagem do SaaS Boilerplate

Olá! Felipe aqui. Hoje quero compartilhar uma das partes mais importantes do SaaS Boilerplate: o sistema de billing. Depois de anos implementando sistemas de pagamento para clientes (e cometendo muitos erros pelo caminho), desenvolvi uma abordagem que é ao mesmo tempo poderosa e desacoplada de qualquer provedor de pagamento específico.

Por que um Sistema de Billing Desacoplado?

A maioria dos boilerplates amarra você a um provedor de pagamento específico. Isso pode ser problemático quando:

• Você precisa mudar de provedor (por exemplo, do Stripe para o PayPal)
• Você opera em regiões onde certos provedores não estão disponíveis
• Você quer implementar lógicas de billing personalizadas

No SaaS Boilerplate, o sistema de billing é totalmente desacoplado do provedor de pagamento. Isso significa que você pode trocar de provedor sem alterar sua lógica de negócio ou reescrever seu código.

A Estrutura de Planos e Recursos

O coração do sistema de billing é a definição de planos. Cada plano é definido como um objeto JSON com metadados que incluem recursos, limites e ciclos:

{
  "plans": [
    {
      "slug": "free",
      "name": "Gratuito",
      "description": "Para começar a explorar",
      "metadata": {
        "features": [
          {
            "slug": "projects",
            "name": "Projetos",
            "enabled": true,
            "limit": 3,
            "cycle": "month"
          },
          {
            "slug": "api-calls",
            "name": "Chamadas de API",
            "enabled": true,
            "limit": 1000,
            "cycle": "month"
          },
          {
            "slug": "team-members",
            "name": "Membros da Equipe",
            "enabled": false
          }
        ]
      },
      "prices": [
        {
          "slug": "free-monthly",
          "amount": 0,
          "currency": "BRL",
          "interval": "month",
          "intervalCount": 1
        }
      ]
    },
    {
      "slug": "pro",
      "name": "Profissional",
      "description": "Para equipes em crescimento",
      "metadata": {
        "features": [
          {
            "slug": "projects",
            "name": "Projetos",
            "enabled": true,
            "limit": 10,
            "cycle": "month"
          },
          {
            "slug": "api-calls",
            "name": "Chamadas de API",
            "enabled": true,
            "limit": 10000,
            "cycle": "month"
          },
          {
            "slug": "team-members",
            "name": "Membros da Equipe",
            "enabled": true,
            "limit": 5,
            "cycle": "month"
          }
        ]
      },
      "prices": [
        {
          "slug": "pro-monthly",
          "amount": 9900,
          "currency": "BRL",
          "interval": "month",
          "intervalCount": 1
        },
        {
          "slug": "pro-yearly",
          "amount": 99900,
          "currency": "BRL",
          "interval": "year",
          "intervalCount": 1
        }
      ]
    }
  ]
}

Esta estrutura permite:

1. Definir recursos por plano: Cada plano tem sua própria lista de recursos habilitados
2. Estabelecer limites por recurso: Defina quantidades máximas para cada recurso
3. Configurar ciclos de renovação: Especifique quando os limites são renovados (mensal, anual, etc.)
4. Oferecer múltiplas opções de preço: Cada plano pode ter várias opções de preço (mensal, anual, etc.)

Sistema Automático de Cotas e Limites

Uma das partes mais poderosas do sistema de billing é o gerenciamento automático de cotas e limites. O Boilerplate rastreia automaticamente o uso de recursos para cada organização e aplica os limites conforme definido nos planos.

Como Funciona o Rastreamento de Uso

O sistema é projetado para ser extremamente simples de usar. Para qualquer tabela no seu banco de dados que tenha um campo organizationId, o sistema pode rastrear automaticamente o uso:

1. Definição de Recursos no Plano: Você define um recurso no plano com um slug que corresponde à tabela que deseja rastrear
2. Rastreamento Automático: O sistema conta automaticamente as entradas na tabela para cada organização
3. Verificação de Limites: Quando um usuário tenta criar um novo registro, o sistema verifica se está dentro do limite

Por exemplo, se você tem uma tabela Project e definiu um limite de 3 projetos no plano gratuito, o sistema automaticamente:

• Conta quantos projetos a organização já tem
• Compara com o limite definido no plano
• Permite ou bloqueia a criação de novos projetos

Ciclos de Renovação

Cada recurso pode ter seu próprio ciclo de renovação:

• Mensal: Limites são renovados a cada mês
• Anual: Limites são renovados anualmente
• Semanal: Limites são renovados semanalmente
• Diário: Limites são renovados diariamente

O sistema rastreia automaticamente quando o último reset ocorreu e quando o próximo está programado.

Isolamento Multi-tenant por Organization ID

O sistema de billing aproveita a arquitetura multi-tenant do SaaS Boilerplate, onde tudo é filtrado pelo organizationId. Isso garante:

• Isolamento Completo: Os dados de uma organização nunca são acessíveis por outra
• Rastreamento Preciso: O uso é rastreado corretamente por organização
• Faturamento Separado: Cada organização tem seu próprio ciclo de faturamento

O organizationId é automaticamente incluído em todas as consultas ao banco de dados, garantindo que os limites e cotas sejam aplicados corretamente.

Adaptadores de Pagamento Intercambiáveis

O sistema de billing usa uma arquitetura de adaptadores que permite trocar facilmente entre diferentes provedores de pagamento:

// Configuração com o Stripe
const paymentProvider = new PaymentProvider({
  adapter: stripeAdapter({
    secret: process.env.STRIPE_SECRET_KEY,
    webhook: process.env.STRIPE_WEBHOOK_SECRET
  }),
  database: prismaAdapter(prisma),
  events: {
    onSubscriptionCreated: async (subscription) => {
      // Lógica personalizada quando uma assinatura é criada
    }
  }
});

// Para mudar para outro provedor, basta trocar o adaptador
// const paymentProvider = new PaymentProvider({
//   adapter: paypalAdapter({
//     clientId: process.env.PAYPAL_CLIENT_ID,
//     secret: process.env.PAYPAL_SECRET
//   }),
//   database: prismaAdapter(prisma)
// });

Isso significa que você pode:

• Começar com o Stripe e mudar para outro provedor mais tarde
• Usar diferentes provedores em diferentes regiões
• Implementar seu próprio adaptador para um provedor personalizado

Webhooks e Sincronização

O sistema de billing inclui um gerenciador de webhooks robusto que:

• Processa eventos do provedor de pagamento: Assinaturas criadas, atualizadas, canceladas, etc.
• Sincroniza o banco de dados: Mantém seus dados locais atualizados com o provedor de pagamento
• Evita duplicações: Trata eventos duplicados de forma segura
• Lida com falhas: Recupera-se de erros durante o processamento

Tudo isso é gerenciado automaticamente pelo sistema, sem necessidade de código adicional.

Portal de Billing para Usuários

O SaaS Boilerplate inclui um portal de billing completo que permite aos usuários:

• Visualizar planos disponíveis: Compare recursos e preços
• Gerenciar assinaturas: Fazer upgrade, downgrade ou cancelar
• Atualizar métodos de pagamento: Adicionar ou remover cartões
• Acessar faturas: Ver histórico de pagamentos

O portal é totalmente personalizável e se integra perfeitamente ao seu aplicativo.

Comece a Usar o Sistema de Billing Hoje

Para implementar o sistema de billing em seu SaaS, confira a documentação completa. Incluí guias passo a passo para configurar seus planos, definir recursos e limites, e integrar com provedores de pagamento.

Com este sistema implementado, você pode se concentrar na construção dos recursos principais do seu produto, enquanto oferece uma experiência de billing profissional e flexível para seus clientes.

Boas construções, Felipe