Assinaturas Recorrentes - Alpa Gateway API

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

Descobre o plano

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

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.

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.

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.

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

Valor	Descrição	Cobrança a cada
`MONTHLY`	Mensal	30 dias
`QUARTERLY`	Trimestral	90 dias
`SEMIANNUAL`	Semestral	180 dias
`ANNUAL`	Anual	365 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:

Evento	Quando disparado
`subscription.created`	Nova inscrição
`subscription.activated`	Primeira cobrança aprovada
`subscription.charge_failed`	Cobrança falhou
`subscription.cancelled`	Assinante cancelou
`subscription.paused`	Assinante 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.

​O que você pode fazer

Criar planos

Checkout público

Retry automático

Métricas MRR/Churn

​Fluxo do assinante

​Criando seu primeiro plano

​Intervalos disponíveis

​Métricas em tempo real

​Webhooks de assinatura

Configurar webhooks

​Boas práticas

Criar plano

Checkout público

O que você pode fazer

Fluxo do assinante

Criando seu primeiro plano

Intervalos disponíveis

Métricas em tempo real

Webhooks de assinatura

Boas práticas