Billing

O Building Block Billing fornece funcionalidades completas para gerenciamento de faturamento, assinaturas e cobrança na Catalisa Platform.

Visão Geral

O Billing é um módulo tenant-scoped, ou seja, requer um token com organizationId. Ele é responsável por:

Contas de faturamento (Billing Accounts) - cadastro de clientes para cobrança
Produtos de cobrança (Billing Products) - catálogo de produtos com diferentes modelos de precificação
Planos de assinatura (Subscription Plans) - configuração de planos recorrentes
Assinaturas (Subscriptions) - gestão do ciclo de vida de assinaturas
Medidores de uso (Usage Meters) - rastreamento de consumo para cobrança por uso
Eventos de uso (Usage Events) - registro de consumo em tempo real
Faturas (Invoices) - geração e gestão de faturas
Pagamentos (Payments) - registro de pagamentos e reembolsos

Base URL

https://api.catalisa.io/billing

Recursos

Recurso	Descrição
Contas	Gerenciamento de contas de faturamento
Planos	Planos de assinatura
Assinaturas	Gestão de assinaturas
Faturamento	Faturas e pagamentos

Permissões

Permissão	Descrição
`BILLING_ACCOUNTS_CREATE`	Criar contas de faturamento
`BILLING_ACCOUNTS_READ`	Listar e visualizar contas
`BILLING_ACCOUNTS_UPDATE`	Atualizar contas
`BILLING_ACCOUNTS_DELETE`	Excluir contas
`BILLING_PRODUCTS_CREATE`	Criar produtos de cobrança
`BILLING_PRODUCTS_READ`	Listar e visualizar produtos
`BILLING_PRODUCTS_UPDATE`	Atualizar produtos
`BILLING_PRODUCTS_DELETE`	Excluir produtos
`SUBSCRIPTION_PLANS_CREATE`	Criar planos de assinatura
`SUBSCRIPTION_PLANS_READ`	Listar e visualizar planos
`SUBSCRIPTION_PLANS_UPDATE`	Atualizar planos
`SUBSCRIPTION_PLANS_DELETE`	Excluir planos
`SUBSCRIPTIONS_CREATE`	Criar assinaturas
`SUBSCRIPTIONS_READ`	Listar e visualizar assinaturas
`SUBSCRIPTIONS_UPDATE`	Atualizar assinaturas
`SUBSCRIPTIONS_CANCEL`	Cancelar assinaturas
`USAGE_METERS_CREATE`	Criar medidores de uso
`USAGE_METERS_READ`	Listar e visualizar medidores
`USAGE_METERS_UPDATE`	Atualizar medidores
`USAGE_METERS_DELETE`	Excluir medidores
`USAGE_EVENTS_CREATE`	Registrar eventos de uso
`USAGE_EVENTS_READ`	Visualizar eventos e resumos
`INVOICES_CREATE`	Criar faturas
`INVOICES_READ`	Listar e visualizar faturas
`INVOICES_UPDATE`	Atualizar faturas
`INVOICES_FINALIZE`	Finalizar faturas
`INVOICES_VOID`	Anular faturas
`PAYMENTS_CREATE`	Registrar pagamentos
`PAYMENTS_READ`	Listar e visualizar pagamentos
`PAYMENTS_REFUND`	Processar reembolsos

Exemplo Rápido

Fluxo completo para criar uma assinatura e gerar fatura:

// 1. Criar uma conta de faturamento
const accountResponse = await fetch('https://api.catalisa.io/billing/api/v1/billing-accounts', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    data: {
      type: 'billing-accounts',
      attributes: {
        name: 'Empresa ABC Ltda',
        email: 'financeiro@empresa-abc.com.br',
        currency: 'BRL',
        taxId: '12.345.678/0001-90',
        taxIdType: 'CNPJ',
      },
    },
  }),
});

const { data: account } = await accountResponse.json();

// 2. Criar um plano de assinatura
const planResponse = await fetch('https://api.catalisa.io/billing/api/v1/subscription-plans', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    data: {
      type: 'subscription-plans',
      attributes: {
        name: 'Plano Pro',
        description: 'Acesso completo a todos os recursos',
        billingInterval: 'MONTHLY',
        billingCycleType: 'ANNIVERSARY',
        basePrice: 299.90,
        currency: 'BRL',
        trialDays: 14,
      },
    },
  }),
});

const { data: plan } = await planResponse.json();

// 3. Criar uma assinatura
const subscriptionResponse = await fetch('https://api.catalisa.io/billing/api/v1/subscriptions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    data: {
      type: 'subscriptions',
      attributes: {
        billingAccountId: account.id,
        planId: plan.id,
        quantity: 1,
      },
    },
  }),
});

const { data: subscription } = await subscriptionResponse.json();
console.log(`Assinatura criada: ${subscription.id}`);
console.log(`Status: ${subscription.attributes.status}`);

// 4. Gerar fatura da assinatura
const invoiceResponse = await fetch('https://api.catalisa.io/billing/api/v1/invoices', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    data: {
      type: 'invoices',
      attributes: {
        billingAccountId: account.id,
        periodStart: subscription.attributes.currentPeriodStart,
        periodEnd: subscription.attributes.currentPeriodEnd,
      },
    },
  }),
});

const { data: invoice } = await invoiceResponse.json();

// 5. Finalizar a fatura
await fetch(`https://api.catalisa.io/billing/api/v1/invoices/${invoice.id}/finalize`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

// 6. Registrar pagamento
await fetch('https://api.catalisa.io/billing/api/v1/payments', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    data: {
      type: 'payments',
      attributes: {
        billingAccountId: account.id,
        invoiceId: invoice.id,
        amount: invoice.attributes.total,
        paymentMethod: 'PIX',
        externalRef: 'E12345678901234567890123456789012',
      },
    },
  }),
});

console.log('Pagamento registrado com sucesso!');

Arquitetura

┌─────────────────────────────────────────────────────────────────────┐
│                           Billing                                    │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐          │
│  │   Billing    │    │   Billing    │    │ Subscription │          │
│  │   Accounts   │    │   Products   │    │    Plans     │          │
│  │              │    │              │    │              │          │
│  │  - name      │    │  - pricing   │    │  - interval  │          │
│  │  - email     │    │    model     │    │  - basePrice │          │
│  │  - balance   │    │  - tiers     │    │  - trialDays │          │
│  └──────────────┘    └──────────────┘    └──────────────┘          │
│         │                   │                   │                   │
│         │                   │                   │                   │
│         └───────────────────┼───────────────────┘                   │
│                             │                                       │
│                    ┌────────▼────────┐                              │
│                    │  Subscriptions  │                              │
│                    │                 │                              │
│                    │  - status       │                              │
│                    │  - quantity     │                              │
│                    │  - period       │                              │
│                    └────────┬────────┘                              │
│                             │                                       │
│         ┌───────────────────┼───────────────────┐                   │
│         │                   │                   │                   │
│  ┌──────▼──────┐    ┌──────▼──────┐    ┌──────▼──────┐            │
│  │   Usage     │    │   Invoices  │    │  Payments   │            │
│  │   Metering  │    │             │    │             │            │
│  │             │    │  - lines    │    │  - refunds  │            │
│  │  - events   │    │  - finalize │    │  - status   │            │
│  │  - summary  │    │  - void     │    │             │            │
│  └─────────────┘    └─────────────┘    └─────────────┘            │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

Conceitos Importantes

Status da Conta de Faturamento

Status	Descrição
`ACTIVE`	Conta ativa, pode criar assinaturas e receber cobranças
`SUSPENDED`	Conta suspensa, assinaturas pausadas
`CLOSED`	Conta encerrada, não aceita novas operações

Modelos de Precificação

Modelo	Descrição
`FLAT_FEE`	Taxa fixa independente do uso
`TIERED`	Preço por faixa de uso (cada faixa tem seu preço)
`VOLUME`	Preço único baseado no volume total
`PER_UNIT`	Preço por unidade consumida
`PACKAGE`	Preço por pacote de unidades

Intervalos de Cobrança

Intervalo	Descrição
`DAILY`	Cobrança diária
`WEEKLY`	Cobrança semanal
`MONTHLY`	Cobrança mensal
`QUARTERLY`	Cobrança trimestral
`YEARLY`	Cobrança anual

Tipos de Ciclo de Cobrança

Tipo	Descrição
`CALENDAR_ALIGNED`	Alinhado ao calendário (ex: dia 1 de cada mês)
`ANNIVERSARY`	Baseado na data de início da assinatura

Status da Assinatura

Status	Descrição
`TRIAL`	Em período de teste
`ACTIVE`	Assinatura ativa
`PAUSED`	Assinatura pausada temporariamente
`CANCELED`	Assinatura cancelada
`EXPIRED`	Assinatura expirada

Status da Fatura

Status	Descrição
`DRAFT`	Rascunho, pode ser editada
`PENDING`	Finalizada, aguardando pagamento
`PAID`	Paga integralmente
`OVERDUE`	Vencida, pagamento atrasado
`CANCELED`	Cancelada antes da finalização
`VOID`	Anulada após finalização

Status do Pagamento

Status	Descrição
`PENDING`	Aguardando processamento
`PROCESSING`	Em processamento
`COMPLETED`	Concluído com sucesso
`FAILED`	Falhou
`REFUNDED`	Reembolsado

Tipos de Agregação de Uso

Tipo	Descrição
`SUM`	Soma de todos os valores
`MAX`	Valor máximo no período
`LAST`	Último valor registrado
`AVERAGE`	Média dos valores
`COUNT_DISTINCT`	Contagem de valores únicos

Eventos do Billing

O módulo publica eventos via Redis para integração com outros módulos:

Evento	Descrição
`billing.account.created`	Conta de faturamento criada
`billing.subscription.created`	Assinatura criada
`billing.subscription.activated`	Assinatura ativada
`billing.subscription.paused`	Assinatura pausada
`billing.subscription.canceled`	Assinatura cancelada
`billing.invoice.created`	Fatura criada
`billing.invoice.finalized`	Fatura finalizada
`billing.invoice.paid`	Fatura paga
`billing.payment.completed`	Pagamento concluído
`billing.payment.refunded`	Pagamento reembolsado

Visão Geral​

Base URL​

Recursos​

Permissões​

Exemplo Rápido​

Arquitetura​

Conceitos Importantes​

Status da Conta de Faturamento​

Modelos de Precificação​

Intervalos de Cobrança​

Tipos de Ciclo de Cobrança​

Status da Assinatura​

Status da Fatura​

Status do Pagamento​

Tipos de Agregação de Uso​

Eventos do Billing​