# @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, alocações de assentos, 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 requerem autenticação e acesso restrito a usuários com roles `admin` ou `admin-billing`, exceto o endpoint de recebimento de webhooks que é público.

### Dashboard

- **GET** `/billing/dashboard`  
  **Autenticação:** Sim (roles: admin, admin-billing)  
  **Descrição:** Retorna dados resumidos do dashboard de billing, incluindo assinaturas ativas, pagamentos falhados, faturas em atraso, receita do mês e pagamentos recentes.  
  **Parâmetros:** Query para paginação não aplicável.  
  **Resposta:** Objeto com métricas e listas resumidas.  
  **Erros:** 401, 403.

- **GET** `/billing/reports`  
  **Autenticação:** Sim (roles: admin, admin-billing)  
  **Descrição:** Retorna dados para relatórios de receitas e assinaturas.  
  **Resposta:** Dados agregados para gráficos e coortes.  
  **Erros:** 401, 403.

### Produtos

- **GET** `/billing/products`  
  **Autenticação:** Sim (roles: admin, admin-billing)  
  **Descrição:** Lista produtos com paginação.  
  **Parâmetros:** Query de paginação padrão.  
  **Resposta:** Lista paginada de produtos.  
  **Erros:** 401, 403.

- **GET** `/billing/products/:id`  
  **Autenticação:** Sim (roles: admin, admin-billing)  
  **Descrição:** Obtém detalhes de um produto pelo ID, incluindo preços associados.  
  **Parâmetros:** `id` (path) - ID do produto.  
  **Resposta:** Objeto produto com preços.  
  **Erros:** 401, 403, 404.

- **POST** `/billing/products`  
  **Autenticação:** Sim (roles: admin, admin-billing)  
  **Descrição:** Cria um novo produto.  
  **Body:** `CreateProductDto`  
  **Resposta:** Produto criado.  
  **Erros:** 400, 401, 403.

- **PATCH** `/billing/products/:id`  
  **Autenticação:** Sim (roles: admin, admin-billing)  
  **Descrição:** Atualiza um produto existente.  
  **Parâmetros:** `id` (path) - ID do produto.  
  **Body:** `UpdateProductDto`  
  **Resposta:** Produto atualizado.  
  **Erros:** 400, 401, 403, 404.

- **DELETE** `/billing/products/:id`  
  **Autenticação:** Sim (roles: admin, admin-billing)  
  **Descrição:** Remove um produto pelo ID.  
  **Parâmetros:** `id` (path) - ID do produto.  
  **Resposta:** Produto removido.  
  **Erros:** 401, 403, 404.

### Preços

- **GET** `/billing/prices`  
  **Autenticação:** Sim (roles: admin, admin-billing)  
  **Descrição:** Lista preços com paginação, incluindo dados básicos do produto.  
  **Resposta:** Lista paginada de preços.  
  **Erros:** 401, 403.

- **GET** `/billing/prices/:id`  
  **Autenticação:** Sim (roles: admin, admin-billing)  
  **Descrição:** Obtém detalhes de um preço pelo ID, incluindo o produto associado.  
  **Parâmetros:** `id` (path) - ID do preço.  
  **Resposta:** Objeto preço com produto.  
  **Erros:** 401, 403, 404.

- **POST** `/billing/prices`  
  **Autenticação:** Sim (roles: admin, admin-billing)  
  **Descrição:** Cria um novo preço.  
  **Body:** `CreatePriceDto`  
  **Resposta:** Preço criado.  
  **Erros:** 400, 401, 403.

- **PATCH** `/billing/prices/:id`  
  **Autenticação:** Sim (roles: admin, admin-billing)  
  **Descrição:** Atualiza um preço existente.  
  **Parâmetros:** `id` (path) - ID do preço.  
  **Body:** `UpdatePriceDto`  
  **Resposta:** Preço atualizado.  
  **Erros:** 400, 401, 403, 404.

- **DELETE** `/billing/prices/:id`  
  **Autenticação:** Sim (roles: admin, admin-billing)  
  **Descrição:** Remove um preço pelo ID.  
  **Parâmetros:** `id` (path) - ID do preço.  
  **Resposta:** Preço removido.  
  **Erros:** 401, 403, 404.

### Ofertas

- **GET** `/billing/offers`  
  **Autenticação:** Sim (roles: admin, admin-billing)  
  **Descrição:** Lista ofertas com paginação.  
  **Resposta:** Lista paginada de ofertas.  
  **Erros:** 401, 403.

- **GET** `/billing/offers/:id`  
  **Autenticação:** Sim (roles: admin, admin-billing)  
  **Descrição:** Obtém detalhes de uma oferta pelo ID, incluindo preços associados.  
  **Parâmetros:** `id` (path) - ID da oferta.  
  **Resposta:** Objeto oferta com preços.  
  **Erros:** 401, 403, 404.

- **POST** `/billing/offers`  
  **Autenticação:** Sim (roles: admin, admin-billing)  
  **Descrição:** Cria uma nova oferta.  
  **Body:** `CreateOfferDto`  
  **Resposta:** Oferta criada.  
  **Erros:** 400, 401, 403.

- **PATCH** `/billing/offers/:id`  
  **Autenticação:** Sim (roles: admin, admin-billing)  
  **Descrição:** Atualiza uma oferta existente.  
  **Parâmetros:** `id` (path) - ID da oferta.  
  **Body:** `UpdateOfferDto`  
  **Resposta:** Oferta atualizada.  
  **Erros:** 400, 401, 403, 404.

- **DELETE** `/billing/offers/:id`  
  **Autenticação:** Sim (roles: admin, admin-billing)  
  **Descrição:** Remove uma oferta pelo ID.  
  **Parâmetros:** `id` (path) - ID da oferta.  
  **Resposta:** Oferta removida.  
  **Erros:** 401, 403, 404.

### Cupons

- **GET** `/billing/coupons`  
  **Autenticação:** Sim (roles: admin, admin-billing)  
  **Descrição:** Lista cupons com paginação.  
  **Resposta:** Lista paginada de cupons.  
  **Erros:** 401, 403.

- **GET** `/billing/coupons/:id`  
  **Autenticação:** Sim (roles: admin, admin-billing)  
  **Descrição:** Obtém detalhes de um cupom pelo ID.  
  **Parâmetros:** `id` (path) - ID do cupom.  
  **Resposta:** Objeto cupom.  
  **Erros:** 401, 403, 404.

- **POST** `/billing/coupons`  
  **Autenticação:** Sim (roles: admin, admin-billing)  
  **Descrição:** Cria um novo cupom.  
  **Body:** `CreateCouponDto`  
  **Resposta:** Cupom criado.  
  **Erros:** 400, 401, 403.

- **PATCH** `/billing/coupons/:id`  
  **Autenticação:** Sim (roles: admin, admin-billing)  
  **Descrição:** Atualiza um cupom existente.  
  **Parâmetros:** `id` (path) - ID do cupom.  
  **Body:** `UpdateCouponDto`  
  **Resposta:** Cupom atualizado.  
  **Erros:** 400, 401, 403, 404.

- **DELETE** `/billing/coupons/:id`  
  **Autenticação:** Sim (roles: admin, admin-billing)  
  **Descrição:** Remove um cupom pelo ID.  
  **Parâmetros:** `id` (path) - ID do cupom.  
  **Resposta:** Cupom removido.  
  **Erros:** 401, 403, 404.

### Pedidos

- **GET** `/billing/orders`  
  **Autenticação:** Sim (roles: admin, admin-billing)  
  **Descrição:** Lista pedidos com paginação.  
  **Resposta:** Lista paginada de pedidos.  
  **Erros:** 401, 403.

- **GET** `/billing/orders/:id`  
  **Autenticação:** Sim (roles: admin, admin-billing)  
  **Descrição:** Obtém detalhes de um pedido pelo ID, incluindo itens do pedido.  
  **Parâmetros:** `id` (path) - ID do pedido.  
  **Resposta:** Objeto pedido com itens.  
  **Erros:** 401, 403, 404.

- **POST** `/billing/orders`  
  **Autenticação:** Sim (roles: admin, admin-billing)  
  **Descrição:** Cria um novo pedido.  
  **Body:** `CreateOrderDto`  
  **Resposta:** Pedido criado.  
  **Erros:** 400, 401, 403.

- **POST** `/billing/orders/:id/checkout`  
  **Autenticação:** Sim (roles: admin, admin-billing)  
  **Descrição:** Inicia o checkout de um pedido.  
  **Parâmetros:** `id` (path) - ID do pedido.  
  **Body:** `StartOrderCheckoutDto`  
  **Resposta:** Dados da sessão de checkout e pagamento.  
  **Erros:** 400, 401, 403, 404.

- **POST** `/billing/orders/:id/checkout/confirm`  
  **Autenticação:** Sim (roles: admin, admin-billing)  
  **Descrição:** Confirma o checkout de um pedido.  
  **Parâmetros:** `id` (path) - ID do pedido.  
  **Body:** `ConfirmOrderCheckoutDto`  
  **Resposta:** Dados atualizados do pagamento e gateway.  
  **Erros:** 400, 401, 403, 404.

### Assinaturas

- **GET** `/billing/subscriptions`  
  **Autenticação:** Sim (roles: admin, admin-billing)  
  **Descrição:** Lista assinaturas com paginação, incluindo dados básicos do produto e preço.  
  **Resposta:** Lista paginada de assinaturas.  
  **Erros:** 401, 403.

- **GET** `/billing/subscriptions/:id`  
  **Autenticação:** Sim (roles: admin, admin-billing)  
  **Descrição:** Obtém detalhes de uma assinatura pelo ID, incluindo itens, produto, preço e últimas faturas.  
  **Parâmetros:** `id` (path) - ID da assinatura.  
  **Resposta:** Objeto assinatura completo.  
  **Erros:** 401, 403, 404.

- **POST** `/billing/subscriptions`  
  **Autenticação:** Sim (roles: admin, admin-billing)  
  **Descrição:** Cria uma nova assinatura.  
  **Body:** `CreateSubscriptionDto`  
  **Resposta:** Assinatura criada com possível resposta do gateway.  
  **Erros:** 400, 401, 403.

- **PATCH** `/billing/subscriptions/:id/cancel`  
  **Autenticação:** Sim (roles: admin, admin-billing)  
  **Descrição:** Cancela uma assinatura.  
  **Parâmetros:** `id` (path) - ID da assinatura.  
  **Resposta:** Assinatura atualizada com status cancelado.  
  **Erros:** 401, 403, 404.

- **PATCH** `/billing/subscriptions/:id/pause`  
  **Autenticação:** Sim (roles: admin, admin-billing)  
  **Descrição:** Pausa uma assinatura.  
  **Parâmetros:** `id` (path) - ID da assinatura.  
  **Resposta:** Assinatura atualizada com status pausado.  
  **Erros:** 401, 403, 404.

- **PATCH** `/billing/subscriptions/:id/resume`  
  **Autenticação:** Sim (roles: admin, admin-billing)  
  **Descrição:** Retoma uma assinatura pausada.  
  **Parâmetros:** `id` (path) - ID da assinatura.  
  **Resposta:** Assinatura atualizada com status ativo.  
  **Erros:** 401, 403, 404.

### Faturas

- **GET** `/billing/invoices`  
  **Autenticação:** Sim (roles: admin, admin-billing)  
  **Descrição:** Lista faturas com paginação.  
  **Resposta:** Lista paginada de faturas.  
  **Erros:** 401, 403.

- **GET** `/billing/invoices/:id`  
  **Autenticação:** Sim (roles: admin, admin-billing)  
  **Descrição:** Obtém detalhes de uma fatura pelo ID, incluindo itens e pagamentos relacionados.  
  **Parâmetros:** `id` (path) - ID da fatura.  
  **Resposta:** Objeto fatura completo.  
  **Erros:** 401, 403, 404.

- **POST** `/billing/invoices`  
  **Autenticação:** Sim (roles: admin, admin-billing)  
  **Descrição:** Cria uma nova fatura.  
  **Body:** Objeto genérico com dados da fatura.  
  **Resposta:** Fatura criada.  
  **Erros:** 400, 401, 403.

### Pagamentos

- **GET** `/billing/payments`  
  **Autenticação:** Sim (roles: admin, admin-billing)  
  **Descrição:** Lista pagamentos com paginação.  
  **Resposta:** Lista paginada de pagamentos.  
  **Erros:** 401, 403.

- **GET** `/billing/payments/:id`  
  **Autenticação:** Sim (roles: admin, admin-billing)  
  **Descrição:** Obtém detalhes de um pagamento pelo ID.  
  **Parâmetros:** `id` (path) - ID do pagamento.  
  **Resposta:** Objeto pagamento.  
  **Erros:** 401, 403, 404.

### Reembolsos

- **GET** `/billing/refunds`  
  **Autenticação:** Sim (roles: admin, admin-billing)  
  **Descrição:** Lista reembolsos com paginação.  
  **Resposta:** Lista paginada de reembolsos.  
  **Erros:** 401, 403.

### Direitos (Entitlements)

- **GET** `/billing/entitlements`  
  **Autenticação:** Sim (roles: admin, admin-billing)  
  **Descrição:** Lista direitos com paginação.  
  **Resposta:** Lista paginada de direitos.  
  **Erros:** 401, 403.

- **POST** `/billing/entitlements`  
  **Autenticação:** Sim (roles: admin, admin-billing)  
  **Descrição:** Cria um novo direito.  
  **Body:** `CreateEntitlementDto`  
  **Resposta:** Direito criado.  
  **Erros:** 400, 401, 403.

- **DELETE** `/billing/entitlements/:id`  
  **Autenticação:** Sim (roles: admin, admin-billing)  
  **Descrição:** Revoga um direito (status alterado para "revoked").  
  **Parâmetros:** `id` (path) - ID do direito.  
  **Resposta:** Direito atualizado com status revogado.  
  **Erros:** 401, 403, 404.

### Contratos

- **GET** `/billing/contracts`  
  **Autenticação:** Sim (roles: admin, admin-billing)  
  **Descrição:** Lista contratos com paginação.  
  **Resposta:** Lista paginada de contratos.  
  **Erros:** 401, 403.

- **GET** `/billing/contracts/:id`  
  **Autenticação:** Sim (roles: admin, admin-billing)  
  **Descrição:** Obtém detalhes de um contrato pelo ID, incluindo assentos e alocações.  
  **Parâmetros:** `id` (path) - ID do contrato.  
  **Resposta:** Objeto contrato completo.  
  **Erros:** 401, 403, 404.

- **POST** `/billing/contracts`  
  **Autenticação:** Sim (roles: admin, admin-billing)  
  **Descrição:** Cria um novo contrato.  
  **Body:** `CreateContractDto`  
  **Resposta:** Contrato criado.  
  **Erros:** 400, 401, 403.

- **PATCH** `/billing/contracts/:id`  
  **Autenticação:** Sim (roles: admin, admin-billing)  
  **Descrição:** Atualiza um contrato existente.  
  **Parâmetros:** `id` (path) - ID do contrato.  
  **Body:** `UpdateContractDto`  
  **Resposta:** Contrato atualizado.  
  **Erros:** 400, 401, 403, 404.

- **DELETE** `/billing/contracts/:id`  
  **Autenticação:** Sim (roles: admin, admin-billing)  
  **Descrição:** Remove um contrato pelo ID.  
  **Parâmetros:** `id` (path) - ID do contrato.  
  **Resposta:** Contrato removido.  
  **Erros:** 401, 403, 404.

### Alocações de Assentos (Seats)

- **GET** `/billing/seats`  
  **Autenticação:** Sim (roles: admin, admin-billing)  
  **Descrição:** Retorna dados de contratos, assentos, alocações e estatísticas.  
  **Resposta:** Objeto com listas e estatísticas de assentos e alocações.  
  **Erros:** 401, 403.

- **POST** `/billing/seats`  
  **Autenticação:** Sim (roles: admin, admin-billing)  
  **Descrição:** Cria uma alocação de assento.  
  **Body:** `UpsertSeatAllocationDto`  
  **Resposta:** Alocação criada com dados detalhados.  
  **Erros:** 400, 401, 403.

- **PATCH** `/billing/seats/:id`  
  **Autenticação:** Sim (roles: admin, admin-billing)  
  **Descrição:** Atualiza uma alocação de assento.  
  **Parâmetros:** `id` (path) - ID da alocação.  
  **Body:** `UpsertSeatAllocationDto`  
  **Resposta:** Alocação atualizada com dados detalhados.  
  **Erros:** 400, 401, 403, 404.

- **PATCH** `/billing/seats/:id/release`  
  **Autenticação:** Sim (roles: admin, admin-billing)  
  **Descrição:** Libera uma alocação de assento (status para "released").  
  **Parâmetros:** `id` (path) - ID da alocação.  
  **Resposta:** Alocação atualizada com status liberado.  
  **Erros:** 401, 403, 404.

### Gateways de Pagamento

- **GET** `/billing/gateways`  
  **Autenticação:** Sim (roles: admin, admin-billing)  
  **Descrição:** Lista gateways de pagamento ativos e conhecidos, com configurações.  
  **Resposta:** Lista de gateways com status e configurações.  
  **Erros:** 401, 403.

- **PATCH** `/billing/gateways/:slug`  
  **Autenticação:** Sim (roles: admin, admin-billing)  
  **Descrição:** Atualiza ou cria um gateway pelo slug.  
  **Parâmetros:** `slug` (path) - Identificador do gateway.  
  **Body:** Objeto genérico com dados do gateway.  
  **Resposta:** Gateway atualizado ou criado.  
  **Erros:** 400, 401, 403.

### Webhooks

- **GET** `/billing/webhooks`  
  **Autenticação:** Sim (roles: admin, admin-billing)  
  **Descrição:** Lista eventos de webhooks com paginação.  
  **Resposta:** Lista paginada de eventos de webhook.  
  **Erros:** 401, 403.

- **POST** `/billing/webhooks/:provider`  
  **Autenticação:** Pública  
  **Descrição:** Recebe eventos de webhook dos provedores de pagamento.  
  **Parâmetros:** `provider` (path) - Identificador do provedor (ex: stripe, mercadopago, pagarme).  
  **Body:** Payload do webhook.  
  **Headers:** Pode conter cabeçalhos de assinatura para validação.  
  **Resposta:** Confirmação do recebimento e processamento do evento.  
  **Erros:** 400.

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

- Todos os endpoints, exceto o recebimento de webhooks, 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`  
  - `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`  
  - `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`  
  - `code` (string, obrigatório)  
  - `name` (string, obrigatório)  
  - `description` (string, opcional)  
  - `status` (string, opcional)

- `CreateCouponDto` / `UpdateCouponDto`  
  - `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`  
  - `contact_id` (number, opcional)  
  - `company_contact_id` (number, opcional)  
  - `status` (enum: draft, pending, paid, canceled, refunded, opcional)  
  - `currency` (string, opcional)  
  - `subtotal_cents` (number, opcional)  
  - `discount_cents` (number, opcional)  
  - `total_cents` (number, opcional)  
  - `source` (string, opcional)  
  - `notes` (string, opcional)

- `CreateSubscriptionDto`  
  - `contact_id` (number, opcional)  
  - `product_id` (number, opcional)  
  - `price_id` (number, opcional)  
  - `gateway` (string, opcional)  
  - `gateway_subscription_id` (string, opcional)  
  - `status` (enum: trialing, active, past_due, canceled, paused, unpaid, opcional)  
  - `started_at` (string datetime, opcional)  
  - `trial_ends_at` (string datetime, opcional)  
  - `current_period_start` (string datetime, opcional)  
  - `current_period_end` (string datetime, opcional)  
  - `cancel_at_period_end` (boolean, opcional)  
  - `customer_email` (string, opcional)  
  - `customer_name` (string, opcional)  
  - `payment_method_id` (string, opcional)  
  - `gateway_customer_id` (string, opcional)  
  - `gateway_token` (string, opcional)  
  - `success_url` (string, opcional)  
  - `cancel_url` (string, opcional)  
  - `metadata` (object, opcional)

- `CreateContractDto` / `UpdateContractDto`  
  - `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, opcional)  
  - `signed_at` (string datetime, opcional)

- `CreateEntitlementDto`  
  - `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, opcional)

- `StartOrderCheckoutDto`  
  - `provider` (string, obrigatório, enum: stripe, mercadopago, pagarme)  
  - `success_url` (string, opcional)  
  - `cancel_url` (string, opcional)  
  - `return_url` (string, opcional)  
  - `customer_email` (string, opcional)  
  - `customer_name` (string, opcional)  
  - `locale` (string, opcional)  
  - `method_type` (string, opcional, enum: card, pix, boleto)  
  - `metadata` (object, opcional)

- `ConfirmOrderCheckoutDto`  
  - `provider` (string, obrigatório, enum: stripe, mercadopago, pagarme)  
  - `payment_intent_id` (string, opcional)  
  - `gateway_transaction_id` (string, opcional)  
  - `payment_method_id` (string, opcional)  
  - `payment_method` (string, opcional)  
  - `token` (string, opcional)  
  - `issuer_id` (string, opcional)  
  - `installments` (number, opcional)  
  - `customer_email` (string, opcional)  
  - `customer_name` (string, opcional)  
  - `payer_identification_type` (string, opcional)  
  - `payer_identification_number` (string, opcional)  
  - `return_url` (string, opcional)  
  - `metadata` (object, opcional)

- `UpsertSeatAllocationDto`  
  - `contract_id` (number, obrigatório)  
  - `seat_id` (number, obrigatório)  
  - `assigned_to` (string, obrigatório)  
  - `assigned_email` (string, obrigatório, email)  
  - `status` (enum: active, pending, released, opcional)  
  - `allocated_at` (string datetime, opcional)  
  - `notes` (string, opcional)

### 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, RESTRICT onDelete)  
  - `name` (varchar 255)  
  - `description` (text, nullable)  
  - `starts_at` (datetime)  
  - `ends_at` (datetime, nullable)  
  - `total_seats` (int, nullable)  
  - `status` (enum: draft, active, expired, terminated; default draft)  
  - `signed_at` (datetime, nullable)  
  - timestamps (`created_at`, `updated_at`)  
- **Índices:** `contact_id`, `status`, `ends_at`

### billing_coupon

- **Finalidade:** Cupons de desconto para billing.
- **Colunas principais:**  
  - `id` (PK)  
  - `code` (varchar 64, único)  
  - `name` (varchar 255)  
  - `discount_type` (enum: percentage, fixed; default percentage)  
  - `discount_value` (int; default 0)  
  - `currency` (char 3, nullable)  
  - `max_uses` (int, nullable)  
  - `uses_count` (int; default 0)  
  - `starts_at` (datetime, nullable)  
  - `ends_at` (datetime, 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, CASCADE onDelete)  
  - `source_type` (varchar 64)  
  - `source_id` (int)  
  - `target_type` (varchar 64)  
  - `target_id` (int)  
  - `access_type` (varchar 120)  
  - `starts_at` (datetime, nullable)  
  - `ends_at` (datetime, 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, SET NULL onDelete)  
  - `order_id` (FK nullable, SET NULL onDelete)  
  - `contact_id` (FK nullable, SET NULL onDelete)  
  - `invoice_number` (varchar 64, nullable)  
  - `status` (enum: draft, open, paid, void, uncollectible; default draft)  
  - `currency` (char 3; default BRL)  
  - `subtotal_cents` (int; default 0)  
  - `total_cents` (int; default 0)  
  - `due_date` (datetime, nullable)  
  - `paid_at` (datetime, 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, SET NULL onDelete)  
  - `order_id` (FK nullable, SET NULL onDelete)  
  - `contact_id` (FK nullable, SET NULL onDelete)  
  - `provider` (varchar 64, 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` (int; default 0)  
  - `currency` (char 3; default BRL)  
  - `external_transaction_id` (varchar 255, nullable)  
  - `paid_at` (datetime, nullable)  
  - `raw_response` (text, 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` (varchar 64, nullable, único)  
  - `name` (varchar 255)  
  - `description` (text, nullable)  
  - `product_type` (enum: saas, physical, service, addon; default saas)  
  - `category` (varchar 120, nullable)  
  - `is_active` (boolean; 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, SET NULL onDelete)  
  - `product_id` (FK nullable, SET NULL onDelete)  
  - `price_id` (FK nullable, SET NULL onDelete)  
  - `gateway` (varchar 64, nullable)  
  - `gateway_subscription_id` (varchar 255, nullable)  
  - `status` (enum: trialing, active, past_due, canceled, paused, unpaid; default active)  
  - `started_at` (datetime, nullable)  
  - `trial_ends_at` (datetime, nullable)  
  - `current_period_start` (datetime, nullable)  
  - `current_period_end` (datetime, nullable)  
  - `cancel_at_period_end` (boolean; default false)  
  - `canceled_at` (datetime, 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, SET NULL onDelete)  
  - `company_contact_id` (FK nullable, SET NULL onDelete)  
  - `status` (enum: draft, pending, paid, canceled, refunded; default draft)  
  - `currency` (char 3; default BRL)  
  - `subtotal_cents` (int; default 0)  
  - `discount_cents` (int; default 0)  
  - `total_cents` (int; default 0)  
  - `source` (varchar 120, nullable)  
  - `notes` (text, nullable)  
  - timestamps  
- **Índices:** `contact_id`, `company_contact_id`, `status`, `created_at`

### billing_refund

- **Finalidade:** Reembolsos de pagamentos.
- **Colunas principais:**  
  - `id` (PK)  
  - `payment_id` (FK, CASCADE onDelete)  
  - `contact_id` (FK nullable, SET NULL onDelete)  
  - `amount_cents` (int; default 0)  
  - `reason` (text, nullable)  
  - `status` (enum: pending, completed, failed; default pending)  
  - `external_refund_id` (varchar 255, nullable)  
  - `completed_at` (datetime, 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` (varchar 180)  
  - `is_active` (boolean; default true)  
  - `config_json` (text, nullable)  
  - timestamps  
- **Índices:** `slug` (único), `is_active`

### billing_provider_event

- **Finalidade:** Eventos recebidos via webhook dos provedores.
- **Colunas principais:**  
  - `id` (PK)  
  - `provider_id` (FK, CASCADE onDelete)  
  - `event_type` (varchar 120)  
  - `external_event_id` (varchar 255, nullable)  
  - `payload` (text)  
  - `processed` (boolean; default false)  
  - `processed_at` (datetime, nullable)  
  - `created_at` (datetime)  
- **Í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.
- Checkout de pedidos integra com gateways de pagamento (Stripe, MercadoPago, Pagarme).
- Eventos de webhook são processados para sincronizar estados de pagamentos e assinaturas.
- Notificações por email são enviadas para eventos importantes como pagamento aprovado, falha e cancelamento de assinatura.
- Alocações de assentos são vinculadas a contratos e pessoas, com controle de status e datas.

## 9. Guia rápido de uso (exemplos)

### Listar produtos paginados

```http
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.