API Reference: Planos e Assinaturas
Base URL: /api/planos. Todos requerem autenticacao. Suporte a checkout transparente e ciclo anual.
Endpoints
| Metodo | Endpoint | Permissao | Descricao |
|---|---|---|---|
| GET | /api/planos | Autenticado | Listar planos disponiveis |
| GET | /api/planos/minha-assinatura | Autenticado | Ver plano atual e data de validade |
| POST | /api/planos/assinar | Autenticado | Assinar plano (CC, R$ ou mix) |
| PATCH | /api/planos/membros/:id/plano | Admin | Alterar plano manualmente |
Assinar Plano — Body
{
"planoId": "uuid",
"valorCC": 4990,
"metodo": "PIX",
"ciclo": "mensal"
}Planos Disponiveis
Cada nucleo configura seus proprios planos com precos e beneficios independentes. A tabela abaixo e apenas um exemplo.
| Plano | R$/mes | R$/ano | Moeda do nucleo | Beneficios |
|---|---|---|---|---|
| Free | R$0 | -- | 0 | Acesso base |
| Apoiador | R$19,90 | R$199,00 | 1.990 | Beneficios externos |
| Militante | R$49,90 | R$499,00 | 4.990 | + Ingresso congresso |
| Onca | R$89,90 | R$899,00 | 8.990 | + Festival + Kit exclusivo |
Regras
- Pagamento 100% moeda do nucleo: debita e ativa imediatamente por 30 dias (mensal) ou 365 dias (anual)
- Pagamento com R$: gera cobranca Asaas, ativa apos confirmacao
- Split: moeda do nucleo debitada + Asaas pelo restante
- Se plano vencer e nao renovar: revertido para Free (cron diario)
- Admin pode alterar plano manualmente a qualquer momento
Ciclo Anual
Assinaturas podem ser feitas com ciclo mensal ou anual:
- O campo
ciclono body aceita"mensal"ou"anual" - Ciclo anual aplica desconto (equivalente a ~2 meses gratis): R$199, R$499 ou R$899 por ano
- A validade e definida como 365 dias a partir da confirmacao do pagamento
- Renovacao anual gera uma nova cobranca Asaas com o valor anual
Checkout Transparente para Assinaturas
Assinaturas com cartao de credito utilizam o mesmo checkout transparente descrito em API > Pagamentos:
- Dados do cartao (
creditCard) e do titular (creditCardHolderInfo) sao enviados inline - Mapeamento:
CARTAO_CREDITO(enum interno) e convertido paraCREDIT_CARD(Asaas billing type) - Debito de moeda: Moedas do nucleo so sao debitadas apos a criacao da assinatura no Asaas ser confirmada com sucesso
Error Handling com Rollback
O fluxo de assinatura implementa rollback em caso de falha para manter consistencia:
- Cria registro de assinatura local no banco (status: PENDENTE)
- Cria assinatura/cobranca no Asaas via API
- Se falhar na etapa 2: o registro local e deletado (rollback)
- Se sucesso: atualiza registro local com dados do Asaas e debita moeda do nucleo (se aplicavel)
Isso garante que nao existam registros orfaos de assinaturas que falharam no gateway.