> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zappway.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API de faturamento e distribuição

> Referência interna para a API de faturamento — Stripe checkout, portal do cliente, webhooks, preços, rateio, créditos de uso e validação de plano.

> **Documentação interna para desenvolvedores.** Esta página aborda padrões de integração do Stripe, manipulação de webhook, fluxos de checkout e lógica de controle de planejamento. Não se destina a usuários finais.

***

## Mapa de rotas

| Método | Ponto final                           | Arquivo manipulador                       | Descrição                                                  |
| ------ | ------------------------------------- | ----------------------------------------- | ---------------------------------------------------------- |
| `POST` | `/api/stripe/create-checkout-session` | `stripe/create-checkout-session/route.ts` | Crie uma sessão Stripe Checkout                            |
| `POST` | `/api/stripe/customer-portal`         | `stripe/customer-portal/route.ts`         | Crie uma sessão do Stripe Customer Portal                  |
| `GET`  | `/api/stripe/get-checkout-session`    | `stripe/get-checkout-session/route.ts`    | Recuperar o resultado de uma sessão de checkout            |
| `GET`  | `/api/stripe/prices`                  | `stripe/prices/route.ts`                  | Listar os preços dos planos disponíveis                    |
| `POST` | `/api/stripe/proration-preview`       | `stripe/proration-preview/route.ts`       | Pré-visualizar o rateio da assinatura antes da atualização |
| `POST` | `/api/stripe/usage-credits`           | `stripe/usage-credits/route.ts`           | Adicionar/gerenciar créditos de uso                        |
| `POST` | `/api/stripe/validate-downgrade`      | `stripe/validate-downgrade/route.ts`      | Valide se o downgrade é seguro                             |
| `POST` | `/api/stripe/referral`                | `stripe/referral/route.ts`                | Aplicar desconto de referência                             |
| `POST` | `/api/stripe/webhook`                 | `stripe/webhook/route.ts`                 | Receber eventos de webhook do Stripe                       |

***

## Configuração do cliente Stripe

O cliente Stripe é inicializado em `@zappway/lib/stripe` (ou similar). A chave de API é carregada da variável de ambiente `STRIPE_SECRET_KEY`.

```ts theme={null}
import { stripe } from '@zappway/lib/stripe';
```

***

## Fluxo de check-out

```
1. User selects a plan in the UI
   POST /api/stripe/create-checkout-session { priceId, successUrl, cancelUrl }
   → Creates Stripe Checkout Session
   → Returns { url } for redirect

2. User completes payment on Stripe-hosted page
   → Stripe redirects to successUrl with ?session_id=...

3. App fetches session result
   GET /api/stripe/get-checkout-session?session_id=...
   → Validates payment success
   → Returns subscription status

4. Stripe fires webhook
   POST /api/stripe/webhook
   → Updates organization subscription in DB
```

***

## Manipulador de webhook

O webhook é a **fonte da verdade** para o estado da assinatura. Todas as alterações no plano devem passar pelo webhook, não pela resposta da sessão de checkout.

```ts theme={null}
// Webhook signature verification (mandatory)
const event = stripe.webhooks.constructEvent(
  body,
  req.headers.get('stripe-signature'),
  process.env.STRIPE_WEBHOOK_SECRET
);
```

**Principais eventos tratados:**

| Evento de listra                | Ação                                               |
| ------------------------------- | -------------------------------------------------- |
| `checkout.session.completed`    | Ativar assinatura                                  |
| `customer.subscription.updated` | Atualizar recursos do plano                        |
| `customer.subscription.deleted` | Downgrade para o nível gratuito                    |
| `invoice.payment_failed`        | Sinalizar falha no pagamento e notificar o usuário |
| `invoice.paid`                  | Redefinir contadores de uso para novo período      |

***

## Planejar portão

Os planos bloqueiam o acesso aos recursos por meio dos metadados de assinatura da sessão. O padrão usado em todo o aplicativo:

```ts theme={null}
// Example: Personal Assistant plan gate
import { assertPersonalAssistantPlan } from '@zappway/lib/personal-assistant';
assertPersonalAssistantPlan(req.session); // throws 403 if plan doesn't include feature
```

Existem auxiliares `assertXxxPlan` semelhantes para outros recursos premium. Eles lêem `req.session.organization.subscription` (carregado do banco de dados por meio de retornos de chamada NextAuth).

***

## Visualização do rateio

Antes da atualização, a IU chama a visualização do rateio para mostrar ao usuário a cobrança exata:

```ts theme={null}
// POST /api/stripe/proration-preview
// Body: { newPriceId: string }
// Returns: Stripe InvoicePreviewParams result
```

***

## Créditos de uso

O endpoint `usage-credits` gerencia créditos pré-pagos para cobrança baseada no uso (por exemplo, volume de mensagens). Os créditos são armazenados no banco de dados e decrementados a cada evento faturável.

***

## Validar downgrade

Verifica se o uso atual de recursos da organização é compatível com um plano inferior:

```ts theme={null}
// POST /api/stripe/validate-downgrade
// Body: { targetPriceId: string }
// Returns: { canDowngrade: boolean, blockers: string[] }
// blockers example: ['You have 15 active agents, plan limit is 5']
```

***

## Variáveis ​​de ambiente necessárias

| Variável                             | Descrição                                                     |
| ------------------------------------ | ------------------------------------------------------------- |
| `STRIPE_SECRET_KEY`                  | Chave secreta de distribuição (somente no lado do servidor)   |
| `STRIPE_WEBHOOK_SECRET`              | Segredo do endpoint do Webhook para verificação de assinatura |
| `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY` | Chave publicável Stripe (lado do cliente)                     |

***

## Problemas conhecidos/pegadinhas

* **Idempotência do Webhook:** Stripe pode entregar o mesmo evento várias vezes. Todos os manipuladores de webhook devem ser idempotentes — use `stripe_event_id` como uma chave de desduplicação armazenada no banco de dados.
* **Expiração da sessão de checkout:** As sessões expiram após 24 horas. Se o usuário abandonar o checkout e retornar mais tarde, ele precisará de uma nova sessão.
* **`validate-downgrade`** deve verificar TODOS os tipos de recursos que possuem limites de plano (agentes, habilidades, datastores, membros da equipe, etc.). Se um novo tipo de recurso obtiver um limite de plano, esse ponto final deverá ser atualizado.
* **URL do Portal do Cliente** expira após 5 minutos — gere-o sob demanda, nunca armazene-o em cache.