@hed-hog/billing

1. Visão geral do módulo

O módulo @hed-hog/billing é responsável pela gestão completa do sistema de faturamento, incluindo produtos, preços, ofertas, cupons, pedidos, assinaturas, faturas, pagamentos, reembolsos, direitos (entitlements), contratos, gateways de pagamento, webhooks e dashboard de métricas. Ele oferece uma API RESTful protegida por roles para administração e manipulação dos dados relacionados ao billing.

2. Escopo e responsabilidades

• Gerenciar produtos e seus preços.
• Controlar ofertas e cupons de desconto.
• Registrar e consultar pedidos e assinaturas.
• Emitir e consultar faturas e pagamentos.
• Gerenciar reembolsos e direitos de acesso (entitlements).
• Administrar contratos e alocações de assentos.
• Configurar gateways de pagamento.
• Registrar eventos de webhooks.
• Fornecer dados resumidos para dashboard de billing.
• Garantir autenticação e autorização via roles específicas.

3. Endpoints

Todos os endpoints são protegidos e requerem autenticação com roles admin ou admin-billing.

Dashboard

• GET /billing/dashboard
  Retorna dados resumidos do dashboard de billing, incluindo assinaturas ativas, pagamentos falhados, faturas em atraso, receita do mês e pagamentos recentes.

Produtos

• GET /billing/products
  Lista produtos com paginação.

• GET /billing/products/:id
  Obtém detalhes de um produto pelo ID, incluindo preços associados.

• POST /billing/products
  Cria um novo produto.
  Body: CreateProductDto

• PATCH /billing/products/:id
  Atualiza um produto existente.
  Body: UpdateProductDto

• DELETE /billing/products/:id
  Remove um produto pelo ID.

Preços

• GET /billing/prices
  Lista preços com paginação, incluindo dados básicos do produto.

• GET /billing/prices/:id
  Obtém detalhes de um preço pelo ID, incluindo o produto associado.

• POST /billing/prices
  Cria um novo preço.
  Body: CreatePriceDto

• PATCH /billing/prices/:id
  Atualiza um preço existente.
  Body: UpdatePriceDto

• DELETE /billing/prices/:id
  Remove um preço pelo ID.

Ofertas

• GET /billing/offers
  Lista ofertas com paginação.

• GET /billing/offers/:id
  Obtém detalhes de uma oferta pelo ID, incluindo preços associados.

• POST /billing/offers
  Cria uma nova oferta.
  Body: CreateOfferDto

• PATCH /billing/offers/:id
  Atualiza uma oferta existente.
  Body: UpdateOfferDto

• DELETE /billing/offers/:id
  Remove uma oferta pelo ID.

Cupons

• GET /billing/coupons
  Lista cupons com paginação.

• GET /billing/coupons/:id
  Obtém detalhes de um cupom pelo ID.

• POST /billing/coupons
  Cria um novo cupom.
  Body: CreateCouponDto

• PATCH /billing/coupons/:id
  Atualiza um cupom existente.
  Body: UpdateCouponDto

• DELETE /billing/coupons/:id
  Remove um cupom pelo ID.

Pedidos

• GET /billing/orders
  Lista pedidos com paginação.

• GET /billing/orders/:id
  Obtém detalhes de um pedido pelo ID, incluindo itens do pedido.

• POST /billing/orders
  Cria um novo pedido.
  Body: CreateOrderDto

Assinaturas

• GET /billing/subscriptions
  Lista assinaturas com paginação, incluindo dados básicos do produto e preço.

• GET /billing/subscriptions/:id
  Obtém detalhes de uma assinatura pelo ID, incluindo itens, produto, preço e últimas faturas.

• POST /billing/subscriptions
  Cria uma nova assinatura.
  Body: CreateSubscriptionDto

• PATCH /billing/subscriptions/:id/cancel
  Cancela uma assinatura.

• PATCH /billing/subscriptions/:id/pause
  Pausa uma assinatura.

• PATCH /billing/subscriptions/:id/resume
  Retoma uma assinatura pausada.

Faturas

• GET /billing/invoices
  Lista faturas com paginação.

• GET /billing/invoices/:id
  Obtém detalhes de uma fatura pelo ID, incluindo itens e pagamentos relacionados.

• POST /billing/invoices
  Cria uma nova fatura.
  Body: Objeto genérico com dados da fatura.

Pagamentos

• GET /billing/payments
  Lista pagamentos com paginação.

• GET /billing/payments/:id
  Obtém detalhes de um pagamento pelo ID.

Reembolsos

• GET /billing/refunds
  Lista reembolsos com paginação.

Direitos (Entitlements)

• GET /billing/entitlements
  Lista direitos com paginação.

• POST /billing/entitlements
  Cria um novo direito.
  Body: CreateEntitlementDto

• DELETE /billing/entitlements/:id
  Revoga um direito (status alterado para "revoked").

Contratos

• GET /billing/contracts
  Lista contratos com paginação.

• GET /billing/contracts/:id
  Obtém detalhes de um contrato pelo ID, incluindo assentos e alocações.

• POST /billing/contracts
  Cria um novo contrato.
  Body: CreateContractDto

• PATCH /billing/contracts/:id
  Atualiza um contrato existente.
  Body: UpdateContractDto

• DELETE /billing/contracts/:id
  Remove um contrato pelo ID.

Gateways de Pagamento

• GET /billing/gateways
  Lista gateways de pagamento ativos.

• PATCH /billing/gateways/:slug
  Atualiza ou cria um gateway pelo slug.
  Body: Objeto genérico com dados do gateway.

Webhooks

• GET /billing/webhooks
  Lista eventos de webhooks com paginação.

4. Regras de autenticação e autorização

• Todos os endpoints requerem autenticação.
• Acesso restrito a usuários com roles admin ou admin-billing.
• Roles definidas no sistema:
  • admin-billing: Administrador com acesso total ao billing, pagamentos, assinaturas e faturamento.

5. Estruturas de request/response

DTOs principais para criação e atualização

• CreateProductDto / UpdateProductDto
  Campos: name (string, obrigatório), code (string, opcional), description (string, opcional), product_type (enum: saas, physical, service, addon), category (string, opcional), is_active (boolean, opcional).

• CreatePriceDto / UpdatePriceDto
  Campos: product_id (number, obrigatório), name (string, obrigatório), billing_type (enum: one_time, recurring), currency (string, opcional), amount_cents (number, opcional), interval_unit (enum: day, week, month, year), interval_count (number, opcional), trial_days (number, opcional), setup_fee_cents (number, opcional), is_active (boolean, opcional), starts_at (string datetime, opcional), ends_at (string datetime, opcional).

• CreateOfferDto / UpdateOfferDto
  Campos: code (string, obrigatório), name (string, obrigatório), description (string, opcional), status (string, opcional).

• CreateCouponDto / UpdateCouponDto
  Campos: code (string, obrigatório), name (string, obrigatório), discount_type (enum: percentage, fixed), discount_value (number, opcional), currency (string, opcional), max_uses (number, opcional), starts_at (string datetime, opcional), ends_at (string datetime, opcional), status (enum: active, inactive, expired).

• CreateOrderDto
  Campos opcionais: contact_id, company_contact_id, status (enum: draft, pending, paid, canceled, refunded), currency, subtotal_cents, discount_cents, total_cents, source, notes.

• CreateSubscriptionDto
  Campos opcionais: contact_id, product_id, price_id, gateway, gateway_subscription_id, status (enum: trialing, active, past_due, canceled, paused, unpaid), started_at, trial_ends_at, current_period_start, current_period_end, cancel_at_period_end.

• CreateContractDto / UpdateContractDto
  Campos: contact_id (number, obrigatório), name (string, obrigatório), description (string, opcional), starts_at (string datetime, obrigatório), ends_at (string datetime, opcional), total_seats (number, opcional), status (enum: draft, active, expired, terminated), signed_at (string datetime, opcional).

• CreateEntitlementDto
  Campos: contact_id (number, obrigatório), source_type (string), source_id (number), target_type (string), target_id (number), access_type (string), starts_at (string datetime, opcional), ends_at (string datetime, opcional), status (enum: active, revoked, expired).

Respostas

• Listagens retornam objetos paginados com dados conforme entidade.
• Consultas por ID retornam o objeto completo com relacionamentos conforme descrito nos endpoints.
• Criações e atualizações retornam o objeto criado/atualizado.
• Exclusões retornam o objeto excluído ou confirmação da operação.

6. Erros comuns

• 404 Not Found: Quando o recurso solicitado não existe (ex: produto, preço, oferta, cupom, pedido, assinatura, fatura, pagamento, contrato).
• 401 Unauthorized: Quando o usuário não está autenticado.
• 403 Forbidden: Quando o usuário não possui a role necessária para acessar o recurso.
• 400 Bad Request: Dados inválidos ou faltantes nos DTOs de criação/atualização.

7. Banco de dados (tabelas YAML)

billing_contract

• Finalidade: Armazena contratos de billing vinculados a contatos.
• Colunas principais: id (PK), contact_id (FK para person), name, description (nullable), starts_at, ends_at (nullable), total_seats (nullable), status (enum: draft, active, expired, terminated; default draft), signed_at (nullable), timestamps.
• Índices: contact_id, status, ends_at.

billing_coupon

• Finalidade: Cupons de desconto para billing.
• Colunas principais: id (PK), code (varchar 64, único), name, discount_type (enum: percentage, fixed; default percentage), discount_value (int, default 0), currency (char 3, nullable), max_uses (nullable), uses_count (default 0), starts_at (nullable), ends_at (nullable), status (enum: active, inactive, expired; default active), timestamps.
• Índices: code (único), status.

billing_entitlement

• Finalidade: Direitos de acesso concedidos a contatos.
• Colunas principais: id (PK), contact_id (FK para person), source_type, source_id, target_type, target_id, access_type, starts_at (nullable), ends_at (nullable), status (enum: active, revoked, expired; default active), timestamps.
• Índices: contact_id, source_type+source_id, target_type+target_id, status, ends_at.

billing_invoice

• Finalidade: Faturas geradas para assinaturas ou pedidos.
• Colunas principais: id (PK), subscription_id (FK nullable), order_id (FK nullable), contact_id (FK nullable), invoice_number (nullable), status (enum: draft, open, paid, void, uncollectible; default draft), currency (char 3; default BRL), subtotal_cents (default 0), total_cents (default 0), due_date (nullable), paid_at (nullable), timestamps.
• Índices: subscription_id, order_id, contact_id, invoice_number, status, due_date.

billing_payment

• Finalidade: Registra pagamentos realizados.
• Colunas principais: id (PK), invoice_id (FK nullable), order_id (FK nullable), contact_id (FK nullable), provider (nullable), method_type (enum: card, pix, boleto, bank_transfer, wallet, other; default card), status (enum: pending, processing, paid, failed, canceled, refunded; default pending), amount_cents (default 0), currency (char 3; default BRL), external_transaction_id (nullable), paid_at (nullable), raw_response (nullable), timestamps.
• Índices: invoice_id, order_id, contact_id, provider, status, external_transaction_id, paid_at.

billing_product

• Finalidade: Produtos disponíveis para venda.
• Colunas principais: id (PK), code (nullable, único), name, description (nullable), product_type (enum: saas, physical, service, addon; default saas), category (nullable), is_active (default true), timestamps.
• Índices: code (único), product_type, is_active.

billing_subscription

• Finalidade: Assinaturas de produtos por contatos.
• Colunas principais: id (PK), contact_id (FK nullable), product_id (FK nullable), price_id (FK nullable), gateway (nullable), gateway_subscription_id (nullable), status (enum: trialing, active, past_due, canceled, paused, unpaid; default active), started_at (nullable), trial_ends_at (nullable), current_period_start (nullable), current_period_end (nullable), cancel_at_period_end (boolean; default false), canceled_at (nullable), timestamps.
• Índices: contact_id, product_id, price_id, gateway, gateway_subscription_id, status.

billing_order

• Finalidade: Pedidos realizados.
• Colunas principais: id (PK), contact_id (FK nullable), company_contact_id (FK nullable), status (enum: draft, pending, paid, canceled, refunded; default draft), currency (char 3; default BRL), subtotal_cents (default 0), discount_cents (default 0), total_cents (default 0), source (nullable), notes (nullable), timestamps.
• Índices: contact_id, company_contact_id, status, created_at.

billing_refund

• Finalidade: Reembolsos de pagamentos.
• Colunas principais: id (PK), payment_id (FK), contact_id (FK nullable), amount_cents (default 0), reason (nullable), status (enum: pending, completed, failed; default pending), external_refund_id (nullable), completed_at (nullable), timestamps.
• Índices: payment_id, contact_id, status.

billing_payment_provider

• Finalidade: Gateways de pagamento configurados.
• Colunas principais: id (PK), slug (varchar 64, único), name, is_active (boolean, default true), config_json (nullable), timestamps.
• Índices: slug (único), is_active.

billing_provider_event

• Finalidade: Eventos recebidos via webhook dos provedores.
• Colunas principais: id (PK), provider_id (FK), event_type, external_event_id (nullable), payload, processed (boolean, default false), processed_at (nullable), created_at.
• Índices: provider_id, event_type, processed, external_event_id.

(Outras tabelas seguem padrão similar com chaves primárias, estrangeiras, enums e timestamps.)

8. Regras de negócio relevantes

• Status de entidades são controlados via enums específicos para cada tipo (ex: contratos, cupons, assinaturas).
• Exclusão de contratos, produtos, preços, ofertas, cupons e outros remove o registro do banco.
• Revogação de direitos altera status para "revoked" sem exclusão física.
• Atualização de gateways pode criar ou atualizar registros via upsert pelo slug.
• Dashboard agrega dados importantes para monitoramento do sistema de billing.
• Paginação é aplicada em todas as listagens para controle de volume de dados.
• Assinaturas podem ser canceladas, pausadas e retomadas via endpoints específicos.
• Faturas podem ser criadas manualmente via API.

9. Guia rápido de uso (exemplos)

Listar produtos paginados

GET /billing/products
Authorization: Bearer <token>

Resposta:

{
  "items": [
    {
      "id": 1,
      "name": "Produto A",
      "code": "PROD_A",
      "description": "Descrição do produto A",
      "product_type": "saas",
      "is_active": true,
      "created_at": "...",
      "updated_at": "..."
    }
  ],
  "total": 100,
  "page": 1,
  "pageSize": 10
}

Criar um novo cupom

POST /billing/coupons
Authorization: Bearer <token>
Content-Type: application/json

{
  "code": "DESCONTO10",
  "name": "Desconto 10%",
  "discount_type": "percentage",
  "discount_value": 10,
  "status": "active"
}

Resposta:

{
  "id": 5,
  "code": "DESCONTO10",
  "name": "Desconto 10%",
  "discount_type": "percentage",
  "discount_value": 10,
  "status": "active",
  "created_at": "...",
  "updated_at": "..."
}

Cancelar uma assinatura

PATCH /billing/subscriptions/123/cancel
Authorization: Bearer <token>

Resposta:

{
  "id": 123,
  "status": "canceled",
  "canceled_at": "2024-06-01T12:00:00Z",
  ...
}

Este módulo é fundamental para a gestão financeira e comercial da plataforma, garantindo controle rigoroso e flexível sobre faturamento, assinaturas e pagamentos.