Criar plano
POST /api/v1/subscriptions/plans — requer X-Client-ID + X-API-Key.
{
"name": "Pro Mensal",
"description": "Acesso completo à plataforma",
"amount": 2990,
"currency": "BRL",
"interval": "monthly",
"interval_count": 1,
"trial_period_days": 7,
"billing_day": 5,
"min_card_months": 3
}
| Campo | Tipo | Obrigatório | Descrição |
|---|
name | string (max 255) | sim | Nome do plano |
description | string (max 1000) | não | Descrição exibida ao cliente |
amount | inteiro (centavos) | sim | Valor do ciclo em centavos (ex: 2990 = R$ 29,90) |
currency | string (3 chars) | não | Moeda — padrão BRL |
interval | weekly|monthly|yearly | sim | Frequência de cobrança |
interval_count | inteiro (1–365) | não | Multiplicador do intervalo — padrão 1 (ex: 2 + monthly = a cada 2 meses) |
trial_period_days | inteiro (0–365) | não | Dias de trial gratuito antes da primeira cobrança |
billing_day | inteiro (1–28) | não | Dia fixo de cobrança no mês/ano. Para weekly é ignorado. Se omitido, usa o dia da criação da assinatura |
min_card_months | inteiro (1–120) | não | Validade mínima do cartão em meses a partir de hoje. Impede criação de assinaturas com cartões prestes a vencer |
billing_day é sempre limitado a 28 para garantir compatibilidade com todos os meses. Dias 29, 30 e 31 não são aceitos.
201:
{
"id": "018f1a2b-3c4d-7e5f-a6b7-c8d9e0f1a2b3",
"name": "Pro Mensal",
"description": "Acesso completo à plataforma",
"amount": 2990,
"currency": "BRL",
"interval": "monthly",
"interval_count": 1,
"trial_period_days": 7,
"billing_day": 5,
"min_card_months": 3,
"is_active": true,
"created_at": "2026-06-25T12:00:00+00:00",
"updated_at": "2026-06-25T12:00:00+00:00"
}
Atualizar plano
PUT /api/v1/subscriptions/plans/{uuid} — requer X-Client-ID + X-API-Key.
{
"name": "Pro Mensal Plus",
"description": "Novo benefício incluído",
"billing_day": 10,
"trial_period_days": 14,
"min_card_months": 6,
"is_active": true
}
Não é possível alterar amount, currency, interval ou interval_count após a criação. Para mudar o valor ou a frequência, crie um novo plano e migre as assinaturas via troca de plano.
Listar planos
GET /api/v1/subscriptions/plans — requer X-Client-ID + X-API-Key.
Retorna a lista de planos da empresa. Planos inativos (is_active: false) são incluídos.
Deletar plano
DELETE /api/v1/subscriptions/plans/{uuid} — requer X-Client-ID + X-API-Key.
Soft-delete. Não é possível deletar um plano com assinaturas ativas.