Documentation Index
Fetch the complete documentation index at: https://docs.usealpa.com/llms.txt
Use this file to discover all available pages before exploring further.
O sistema de assinaturas permite cobrar clientes de forma recorrente com planos configuráveis, retry automático em caso de falha e métricas em tempo real de MRR e churn.
Como funciona
- O merchant cria um plano com nome, valor, intervalo e período de trial opcional.
- O cliente se inscreve via checkout público (sem autenticação) ou via API.
- A Alpa gera cobranças automáticas no intervalo do plano.
- Em caso de falha, o sistema realiza retry automático.
- O merchant acompanha MRR, churn rate e assinantes ativos em tempo real.
Modelos
Plano (SubscriptionPlan)
| Campo | Tipo | Descrição |
|---|---|---|
id | uuid | Identificador único do plano |
name | string | Nome do plano |
description | string? | Descrição opcional |
amountCents | integer | Valor da cobrança em centavos |
interval | enum | MONTHLY, QUARTERLY, SEMIANNUAL, ANNUAL |
trialDays | integer? | Dias de trial gratuito |
maxSubscribers | integer? | Limite de assinantes (null = ilimitado) |
active | boolean | Se o plano aceita novas inscrições |
createdAt | datetime | Data de criação |
Assinatura (Subscription)
| Campo | Tipo | Descrição |
|---|---|---|
id | uuid | Identificador único |
planId | uuid | Plano vinculado |
status | enum | ACTIVE, TRIAL, PAUSED, CANCELLED, PAST_DUE |
nextBillingDate | datetime | Próxima data de cobrança |
cancelledAt | datetime? | Data de cancelamento |
Status da assinatura
| Status | Descrição |
|---|---|
TRIAL | Período de trial ativo — ainda não foi cobrado |
ACTIVE | Assinatura ativa e em dia |
PAST_DUE | Último pagamento falhou — retry pendente |
PAUSED | Assinatura pausada pelo assinante |
CANCELLED | Assinatura cancelada |
Endpoints disponíveis
Gestão de planos (API Key)
| Método | Endpoint | Descrição |
|---|---|---|
GET | /api/subscriptions/plans | Listar planos |
POST | /api/subscriptions/plans | Criar plano |
GET | /api/subscriptions/plans/:id | Obter plano específico |
PATCH | /api/subscriptions/plans/:id | Atualizar plano |
DELETE | /api/subscriptions/plans/:id | Remover plano |
GET | /api/subscriptions/metrics | MRR, churn rate, assinantes ativos |
GET | /api/subscriptions/subscribers | Listar todos os assinantes |
POST | /api/subscriptions/:id/retry | Reprocessar cobrança falha |
Endpoints públicos (sem autenticação)
| Método | Endpoint | Descrição |
|---|---|---|
GET | /api/subscriptions/public/:planId | Detalhes do plano para landing pages |
POST | /api/subscriptions/checkout | Inscrever cliente em um plano |
GET | /api/subscriptions/customer?email=... | Listar assinaturas do cliente por email |
PATCH | /api/subscriptions/customer/:id/cancel | Assinante cancela assinatura |
PATCH | /api/subscriptions/customer/:id/pause | Assinante pausa assinatura |
PATCH | /api/subscriptions/customer/:id/resume | Assinante retoma assinatura |
PATCH | /api/subscriptions/customer/:id/card | Assinante atualiza cartão de cobrança |
Criar plano
Configure nome, valor, intervalo e trial.
Listar planos
Consulte todos os planos do seu merchant.
Checkout público
Inscreva clientes sem autenticação.
Self-service do assinante
Rotas para o assinante gerenciar a própria assinatura.