Endpoints de Assinaturas

Visão Geral

A API de Assinaturas permite gerenciar planos de assinatura, acessar recursos premium e processar pagamentos via Stripe com aplicação automática de limites.

Novo na v1.3.0

Sistema completo de assinaturas com múltiplos níveis, limites automáticos de recursos, flags de funcionalidades e integração Stripe para processamento seguro de pagamentos.

Todos os endpoints requerem autenticação.

Authorization: Bearer <token>

---

Níveis de Assinatura

Plano	Máx. Fazendas	Máx. Viveiros/Fazenda	Máx. Lotes/Viveiro	Preço Mensal
GRATUITO	1	3	1	Grátis
BÁSICO	3	10	2	R$ 149/mês
PROFISSIONAL	10	50	5	R$ 499/mês
EMPRESARIAL	Ilimitado	Ilimitado	Ilimitado	Personalizado

Status da Assinatura

Status	Descrição
ACTIVE	Assinatura ativa e todos os recursos disponíveis
PAST_DUE	Pagamento falhou, período de carência ativo
CANCELED	Assinatura foi cancelada
TRIALING	Em período de teste

Flags de Funcionalidades

Recursos premium controlados por nível de assinatura:

Funcionalidade	GRATUITO	BÁSICO	PROFISSIONAL	EMPRESARIAL
advanced_analytics	❌	❌	✅	✅
api_access	❌	✅	✅	✅
export_data	❌	✅	✅	✅
priority_support	❌	❌	✅	✅
custom_reports	❌	❌	✅	✅
ai_predictions	❌	❌	✅	✅
white_label	❌	❌	❌	✅

---

GET /subscriptions/me

Obter detalhes da assinatura do usuário autenticado.

Requisição

GET /api/v1/subscriptions/me
Authorization: Bearer <token>

Resposta 200 OK

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "123e4567-e89b-12d3-a456-426614174000",
  "plan": "PROFESSIONAL",
  "status": "ACTIVE",
  "stripe_customer_id": "cus_123456789",
  "stripe_subscription_id": "sub_123456789",
  "current_period_start": "2026-01-19T00:00:00Z",
  "current_period_end": "2026-02-19T00:00:00Z",
  "max_farms": 10,
  "max_ponds_per_farm": 50,
  "max_batches_per_pond": 5,
  "current_farms": 5,
  "features": {
    "advanced_analytics": true,
    "api_access": true,
    "export_data": true,
    "priority_support": true,
    "custom_reports": true,
    "ai_predictions": true
  },
  "currency": "BRL",
  "created_at": "2026-01-19T00:00:00Z",
  "updated_at": "2026-01-19T00:00:00Z"
}

---

GET /subscriptions/me/limits

Obter limites de recursos e uso atual para o usuário autenticado.

Requisição

GET /api/v1/subscriptions/me/limits
Authorization: Bearer <token>

Resposta 200 OK

{
  "plan": "PROFESSIONAL",
  "limits": {
    "max_farms": 10,
    "max_ponds_per_farm": 50,
    "max_batches_per_pond": 5
  },
  "usage": {
    "farms": {
      "current": 5,
      "max": 10,
      "percentage": 50.0
    },
    "ponds": {
      "current": 25,
      "max": 250,
      "percentage": 10.0
    },
    "active_batches": {
      "current": 12,
      "max": 125,
      "percentage": 9.6
    }
  },
  "warnings": [],
  "can_create": {
    "farm": true,
    "pond": true,
    "batch": true
  }
}

Avisos de Uso

Quando próximo dos limites (>80%), avisos são retornados:

{
  "warnings": [
    {
      "resource": "farms",
      "message": "Você está usando 80% do seu limite de fazendas",
      "current": 8,
      "max": 10
    }
  ]
}

---

GET /subscriptions/plans

Obter planos de assinatura disponíveis.

Requisição

GET /api/v1/subscriptions/plans

Resposta 200 OK

{
  "plans": [
    {
      "id": "FREE",
      "name": "Gratuito",
      "description": "Comece com recursos básicos",
      "price": {
        "usd": 0,
        "brl": 0
      },
      "billing_period": null,
      "limits": {
        "max_farms": 1,
        "max_ponds_per_farm": 3,
        "max_batches_per_pond": 1
      },
      "features": {
        "advanced_analytics": false,
        "api_access": false,
        "export_data": false,
        "priority_support": false,
        "custom_reports": false,
        "ai_predictions": false,
        "white_label": false
      }
    },
    {
      "id": "BASIC",
      "name": "Básico",
      "description": "Recursos essenciais para pequenas operações",
      "price": {
        "usd": 29,
        "brl": 149
      },
      "billing_period": "monthly",
      "limits": {
        "max_farms": 3,
        "max_ponds_per_farm": 10,
        "max_batches_per_pond": 2
      },
      "features": {
        "advanced_analytics": false,
        "api_access": true,
        "export_data": true,
        "priority_support": false,
        "custom_reports": false,
        "ai_predictions": false,
        "white_label": false
      }
    },
    {
      "id": "PROFESSIONAL",
      "name": "Profissional",
      "description": "Recursos completos para operações profissionais",
      "price": {
        "usd": 99,
        "brl": 499
      },
      "billing_period": "monthly",
      "limits": {
        "max_farms": 10,
        "max_ponds_per_farm": 50,
        "max_batches_per_pond": 5
      },
      "features": {
        "advanced_analytics": true,
        "api_access": true,
        "export_data": true,
        "priority_support": true,
        "custom_reports": true,
        "ai_predictions": true,
        "white_label": false
      },
      "popular": true
    },
    {
      "id": "ENTERPRISE",
      "name": "Empresarial",
      "description": "Soluções personalizadas para grandes operações",
      "price": null,
      "billing_period": null,
      "limits": {
        "max_farms": -1,
        "max_ponds_per_farm": -1,
        "max_batches_per_pond": -1
      },
      "features": {
        "advanced_analytics": true,
        "api_access": true,
        "export_data": true,
        "priority_support": true,
        "custom_reports": true,
        "ai_predictions": true,
        "white_label": true
      },
      "contact_sales": true
    }
  ]
}

Nota

Limites com valor -1 indicam recursos ilimitados.

---

GET /subscriptions/{user_id}/limits

Obter limites de recursos e uso para um usuário específico (somente admin).

Parâmetros de Path

Parâmetro	Tipo	Descrição
user_id	UUID	ID do usuário

Requisição

GET /api/v1/subscriptions/{user_id}/limits
Authorization: Bearer <token>

Resposta 200 OK

Mesma estrutura de GET /subscriptions/me/limits.

Possíveis Erros

Status	Detalhe
403	Não autorizado (somente admin)
404	Usuário não encontrado

---

POST /stripe/cancel-subscription

Cancelar a assinatura atual.

Requisição

POST /api/v1/stripe/cancel-subscription
Authorization: Bearer <token>
Content-Type: application/json

{
  "cancel_at_period_end": true,
  "reason": "Mudando para plano anual"
}

Parâmetros do Body

Campo	Tipo	Obrigatório	Descrição
cancel_at_period_end	boolean	❌	Se true, cancela ao final do período de cobrança (padrão: true)
reason	string	❌	Motivo do cancelamento

Resposta 200 OK

{
  "subscription_id": "sub_123456789",
  "status": "ACTIVE",
  "cancel_at_period_end": true,
  "current_period_end": "2026-03-19T00:00:00Z",
  "message": "Assinatura será cancelada ao final do período de cobrança atual"
}

Cuidado

Se cancel_at_period_end for false, a assinatura é cancelada imediatamente e o usuário perde acesso aos recursos premium.

---

POST /stripe/create-billing-portal

Criar uma sessão do portal de cobrança Stripe para gerenciar métodos de pagamento e visualizar faturas.

Requisição

POST /api/v1/stripe/create-billing-portal
Authorization: Bearer <token>
Content-Type: application/json

{
  "return_url": "https://app.aeraplus.com/account/billing"
}

Parâmetros do Body

Campo	Tipo	Obrigatório	Descrição
return_url	string (URL)	✅	URL de retorno após sessão do portal

Resposta 200 OK

{
  "url": "https://billing.stripe.com/p/session/test_123456789"
}

Recursos do Portal

O portal de cobrança permite aos usuários:

• Visualizar e baixar faturas
• Atualizar métodos de pagamento
• Visualizar histórico de assinatura
• Gerenciar endereço de cobrança

---

PUT /subscriptions/{user_id}

Atualizar plano e limites de assinatura de um usuário (somente admin).

Parâmetros de Caminho

Parâmetro	Tipo	Descrição
user_id	UUID	ID do usuário a atualizar

Requisição

PUT /api/v1/subscriptions/{user_id}
Authorization: Bearer <token>
Content-Type: application/json

{
  "plan": "PROFESSIONAL",
  "status": "ACTIVE",
  "max_farms": 10,
  "max_ponds_per_farm": 50,
  "max_batches_per_pond": 5,
  "features": {
    "advanced_analytics": true,
    "api_access": true,
    "export_data": true,
    "priority_support": true,
    "custom_reports": true,
    "ai_predictions": true
  },
  "currency": "BRL"
}

Parâmetros do Body

Campo	Tipo	Obrigatório	Descrição
plan	enum	❌	Plano de assinatura (FREE, BASIC, PROFESSIONAL, ENTERPRISE)
status	enum	❌	Status da assinatura
max_farms	integer	❌	Número máximo de fazendas
max_ponds_per_farm	integer	❌	Máximo de viveiros por fazenda
max_batches_per_pond	integer	❌	Máximo de lotes por viveiro
features	object	❌	Objeto com flags de funcionalidades
currency	string	❌	Código da moeda (USD, BRL)

Resposta 200 OK

Retorna o objeto de assinatura atualizado.

---

POST /stripe/create-checkout-session

Criar uma sessão de checkout Stripe para pagamento de assinatura.

Requisição

POST /api/v1/stripe/create-checkout-session
Authorization: Bearer <token>
Content-Type: application/json

{
  "plan": "PROFESSIONAL",
  "success_url": "https://app.aeraplus.com/subscription/success",
  "cancel_url": "https://app.aeraplus.com/subscription/cancel"
}

Parâmetros do Body

Campo	Tipo	Obrigatório	Descrição
plan	enum	✅	Plano de assinatura desejado
success_url	string (URL)	✅	URL de redirecionamento em caso de sucesso
cancel_url	string (URL)	✅	URL de redirecionamento em caso de cancelamento

Resposta 200 OK

{
  "session_id": "cs_test_123456789",
  "url": "https://checkout.stripe.com/pay/cs_test_123456789"
}

Dica

Redirecione o usuário para a url retornada para completar o processo de pagamento.

---

POST /stripe/create-portal-session

Criar uma sessão do portal do cliente Stripe para gerenciar assinatura e métodos de pagamento.

Requisição

POST /api/v1/stripe/create-portal-session
Authorization: Bearer <token>
Content-Type: application/json

{
  "return_url": "https://app.aeraplus.com/account/subscription"
}

Resposta 200 OK

{
  "url": "https://billing.stripe.com/p/session/test_123456789"
}

---

Limites de Taxa

Os limites de taxa variam por plano de assinatura:

Plano	Requisições/Hora	Conexões Simultâneas
GRATUITO	100	5
BÁSICO	500	20
PROFISSIONAL	2,000	50
EMPRESARIAL	Ilimitado	Ilimitado

---

Códigos de Erro

Código	Descrição
SUBSCRIPTION_LIMIT_REACHED	Limite de recursos excedido para o plano atual
FEATURE_NOT_AVAILABLE	Recurso não disponível no plano atual
SUBSCRIPTION_REQUIRED	Assinatura ativa necessária
PAYMENT_REQUIRED	Método de pagamento necessário
SUBSCRIPTION_CANCELED	Assinatura foi cancelada

---

Exemplos de Uso

Verificar Limites de Assinatura

const response = await fetch('https://api.aeraplus.com/v1/subscriptions/me', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

const subscription = await response.json();

// Verificar se pode criar nova fazenda
if (subscription.current_farms >= subscription.max_farms) {
  console.log('Limite de fazendas atingido. Por favor, atualize seu plano.');
} else {
  // Criar fazenda
}

Fazer Upgrade de Assinatura

const response = await fetch('https://api.aeraplus.com/v1/stripe/create-checkout-session', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    plan: 'PROFESSIONAL',
    success_url: 'https://app.aeraplus.com/subscription/success',
    cancel_url: 'https://app.aeraplus.com/subscription/cancel'
  })
});

const { url } = await response.json();
window.location.href = url; // Redirecionar para checkout Stripe