Skip to main content

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 da Alpa permite cobrar clientes de forma recorrente com retry automático, período de trial e métricas em tempo real — sem precisar gerenciar cobranças manualmente.

​
O que você pode fazer

Criar planos

Configure nome, valor, intervalo (mensal, trimestral, semestral, anual) e dias de trial.

Checkout público

Clientes se inscrevem sem autenticação — ideal para landing pages e funis de vendas.

Retry automático

Cobranças falhas são retentadas automaticamente, reduzindo o churn involuntário.

Métricas MRR/Churn

Acompanhe Receita Mensal Recorrente, taxa de cancelamento e assinantes ativos em tempo real.

​
Fluxo do assinante

1

Descobre o plano

O cliente acessa a página pública do plano via GET /api/subscriptions/public/:planId ou uma landing page customizada.
2

Se inscreve

O cliente preenche nome, email, CPF/CNPJ e dados de pagamento. A inscrição é feita via POST /api/subscriptions/checkout — sem necessidade de conta na Alpa.
3

Trial (se configurado)

Se o plano tem trialDays > 0, o cliente fica em status TRIAL e a primeira cobrança só ocorre após o período de trial.
4

Cobranças automáticas

A Alpa processa a cobrança no intervalo do plano. Em caso de falha, o status muda para PAST_DUE e o retry é disparado automaticamente.
5

Gestão pelo assinante

O assinante pode pausar, retomar ou cancelar a assinatura, e atualizar o cartão de cobrança.

​
Criando seu primeiro plano

curl --request POST \
  --url https://alpa-sistema-api.onrender.com/api/subscriptions/plans \
  --header 'Authorization: Bearer SUA_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Plano Mensal",
    "amountCents": 9900,
    "interval": "MONTHLY",
    "trialDays": 7
  }'

​
Intervalos disponíveis

ValorDescriçãoCobrança a cada
MONTHLYMensal30 dias
QUARTERLYTrimestral90 dias
SEMIANNUALSemestral180 dias
ANNUALAnual365 dias

​
Métricas em tempo real

curl https://alpa-sistema-api.onrender.com/api/subscriptions/metrics \
  -H 'Authorization: Bearer SUA_API_KEY'

{
  "success": true,
  "data": {
    "mrr": 99000,
    "activeSubscribers": 42,
    "churnRate": 0.048
  }
}
  • MRR: soma das cobranças mensais de todos os assinantes ativos (em centavos)
  • activeSubscribers: assinantes com status ACTIVE ou TRIAL
  • churnRate: cancelamentos do mês ÷ assinantes do início do mês (0–1)

​
Webhooks de assinatura

Configure um webhook para receber notificações automáticas:
EventoQuando disparado
subscription.createdNova inscrição
subscription.activatedPrimeira cobrança aprovada
subscription.charge_failedCobrança falhou
subscription.cancelledAssinante cancelou
subscription.pausedAssinante pausou

Configurar webhooks

Receba notificações em tempo real sobre eventos de assinatura.

​
Boas práticas

  • Use trialDays para reduzir a barreira de entrada — trials convertem melhor
  • Configure webhooks para subscription.charge_failed e entre em contato proativamente com o assinante
  • Utilize maxSubscribers para criar planos com vagas limitadas e gerar urgência
  • Ofereça desconto no plano anual para reduzir o churn (ex: 2 meses grátis)

Criar plano

Referência completa do endpoint de criação.

Checkout público

Como inscrever clientes sem autenticação.