Planos

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.

Resposta 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.

Introdução

Conceitos principais

Orquestração

Pagamentos

Assinaturas

Recursos

Criar plano

Atualizar plano

Listar planos

Deletar plano

​Criar plano

​Atualizar plano

​Listar planos

​Deletar plano

Criar plano

Atualizar plano

Listar planos

Deletar plano