npm package: @hed-hog/billing
Description: 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, webhoo
Latest version: 0.0.303

# @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

```http
GET /billing/products
Authorization: Bearer <token>
```

Resposta:

```json
{
  "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

```http
POST /billing/coupons
Authorization: Bearer <token>
Content-Type: application/json

{
  "code": "DESCONTO10",
  "name": "Desconto 10%",
  "discount_type": "percentage",
  "discount_value": 10,
  "status": "active"
}
```

Resposta:

```json
{
  "id": 5,
  "code": "DESCONTO10",
  "name": "Desconto 10%",
  "discount_type": "percentage",
  "discount_value": 10,
  "status": "active",
  "created_at": "...",
  "updated_at": "..."
}
```

### Cancelar uma assinatura

```http
PATCH /billing/subscriptions/123/cancel
Authorization: Bearer <token>
```

Resposta:

```json
{
  "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.