Planos de Assinatura

Gerenciamento de planos de assinatura (Subscription Plans) para configuração de cobrança recorrente.

Endpoints

Método	Endpoint	Descrição	Permissão
POST	`/billing/api/v1/subscription-plans`	Criar plano	`BILLING_PLANS_CREATE`
GET	`/billing/api/v1/subscription-plans`	Listar planos	`BILLING_PLANS_READ`
GET	`/billing/api/v1/subscription-plans/:id`	Obter plano por ID	`BILLING_PLANS_READ`
PATCH	`/billing/api/v1/subscription-plans/:id`	Atualizar plano	`BILLING_PLANS_UPDATE`
DELETE	`/billing/api/v1/subscription-plans/:id`	Excluir plano	`BILLING_PLANS_DELETE`
POST	`/billing/api/v1/subscription-plans/:id/items`	Adicionar item ao plano	`BILLING_PLANS_UPDATE`
DELETE	`/billing/api/v1/subscription-plans/:planId/items/:itemId`	Remover item do plano	`BILLING_PLANS_UPDATE`

Atributos do Plano

Campo	Tipo	Descrição
`name`	string	Nome do plano
`description`	string	Descrição do plano
`billingInterval`	enum	Intervalo de cobrança
`billingCycleType`	enum	Tipo do ciclo de cobrança
`basePrice`	number	Preço base do plano
`currency`	string	Moeda
`trialDays`	number	Dias de período de teste
`isActive`	boolean	Se o plano está ativo
`items`	array	Itens incluídos no plano
`createdAt`	datetime	Data de criação
`updatedAt`	datetime	Data da última atualização

Intervalos de Cobrança (billingInterval)

Valor	Descrição
`DAILY`	Cobrança diária
`WEEKLY`	Cobrança semanal
`MONTHLY`	Cobrança mensal
`QUARTERLY`	Cobrança trimestral
`YEARLY`	Cobrança anual

Tipos de Ciclo de Cobrança (billingCycleType)

Valor	Descrição
`CALENDAR_ALIGNED`	Alinhado ao calendário (ex: dia 1 de cada mês)
`ANNIVERSARY`	Baseado na data de início da assinatura

Estrutura do Item do Plano

Campo	Tipo	Descrição
`productId`	string (UUID)	ID do produto de cobrança
`productName`	string	Nome do produto (somente leitura)
`quantity`	number	Quantidade incluída
`priceOverride`	number	Preço customizado (opcional)
`includedUnits`	number	Unidades incluídas no plano

Criar Plano de Assinatura

POST /api/v1/subscription-plans

Cria um novo plano de assinatura.

Atributos

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome do plano
`description`	string	Não	Descrição
`billingInterval`	enum	Sim	Intervalo de cobrança
`billingCycleType`	enum	Sim	Tipo do ciclo
`basePrice`	number	Sim	Preço base
`currency`	string	Não	Moeda (padrão: config da org)
`trialDays`	number	Não	Dias de teste (padrão: 0)
`isActive`	boolean	Não	Se está ativo (padrão: true)

cURL
JavaScript

curl -X POST 'https://billing.stg.catalisa.app/billing/api/v1/subscription-plans' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "type": "subscription-plans",
      "attributes": {
        "name": "Plano Pro",
        "description": "Acesso completo a todos os recursos da plataforma",
        "billingInterval": "MONTHLY",
        "billingCycleType": "ANNIVERSARY",
        "basePrice": 299.90,
        "currency": "BRL",
        "trialDays": 14
      }
    }
  }'

const response = await fetch('https://billing.stg.catalisa.app/billing/api/v1/subscription-plans', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    data: {
      type: 'subscription-plans',
      attributes: {
        name: 'Plano Pro',
        description: 'Acesso completo a todos os recursos da plataforma',
        billingInterval: 'MONTHLY',
        billingCycleType: 'ANNIVERSARY',
        basePrice: 299.90,
        currency: 'BRL',
        trialDays: 14,
      },
    },
  }),
});

const { data } = await response.json();
console.log(`Plano criado: ${data.id}`);

Response (201 Created)

{
  "data": {
    "type": "subscription-plans",
    "id": "550e8400-e29b-41d4-a716-446655440020",
    "links": {
      "self": "/api/v1/subscription-plans/550e8400-e29b-41d4-a716-446655440020"
    },
    "attributes": {
      "name": "Plano Pro",
      "description": "Acesso completo a todos os recursos da plataforma",
      "billingInterval": "MONTHLY",
      "billingCycleType": "ANNIVERSARY",
      "basePrice": 299.90,
      "currency": "BRL",
      "trialDays": 14,
      "isActive": true,
      "items": [],
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  },
  "links": {
    "self": "/api/v1/subscription-plans/550e8400-e29b-41d4-a716-446655440020"
  }
}

Listar Planos de Assinatura

GET /api/v1/subscription-plans

Lista todos os planos de assinatura com suporte a paginação e filtros.

Query Parameters

Parâmetro	Tipo	Descrição
`page[number]`	integer	Número da página
`page[size]`	integer	Itens por página
`filter[isActive]`	boolean	Filtrar por status ativo
`filter[billingInterval]`	enum	Filtrar por intervalo

cURL
JavaScript

curl 'https://billing.stg.catalisa.app/billing/api/v1/subscription-plans?filter[isActive]=true&filter[billingInterval]=MONTHLY' \
  -H 'Authorization: Bearer SEU_TOKEN'

const params = new URLSearchParams({
  'filter[isActive]': 'true',
  'filter[billingInterval]': 'MONTHLY',
});

const response = await fetch(`https://billing.stg.catalisa.app/billing/api/v1/subscription-plans?${params}`, {
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const { data, meta } = await response.json();
console.log(`Total de planos: ${meta.totalItems}`);

Response (200 OK)

{
  "data": [
    {
      "type": "subscription-plans",
      "id": "550e8400-e29b-41d4-a716-446655440020",
      "links": {
        "self": "/api/v1/subscription-plans/550e8400-e29b-41d4-a716-446655440020"
      },
      "attributes": {
        "name": "Plano Pro",
        "description": "Acesso completo a todos os recursos da plataforma",
        "billingInterval": "MONTHLY",
        "billingCycleType": "ANNIVERSARY",
        "basePrice": 299.90,
        "currency": "BRL",
        "trialDays": 14,
        "isActive": true,
        "createdAt": "2024-01-15T10:30:00Z",
        "updatedAt": "2024-01-15T10:30:00Z"
      }
    },
    {
      "type": "subscription-plans",
      "id": "550e8400-e29b-41d4-a716-446655440021",
      "links": {
        "self": "/api/v1/subscription-plans/550e8400-e29b-41d4-a716-446655440021"
      },
      "attributes": {
        "name": "Plano Básico",
        "description": "Recursos essenciais para começar",
        "billingInterval": "MONTHLY",
        "billingCycleType": "ANNIVERSARY",
        "basePrice": 99.90,
        "currency": "BRL",
        "trialDays": 7,
        "isActive": true,
        "createdAt": "2024-01-10T10:00:00Z",
        "updatedAt": "2024-01-10T10:00:00Z"
      }
    }
  ],
  "meta": {
    "totalItems": 5,
    "totalPages": 1,
    "currentPage": 1,
    "itemsPerPage": 20
  },
  "links": {
    "self": "/api/v1/subscription-plans?page[number]=1&page[size]=20"
  }
}

Obter Plano por ID

GET /api/v1/subscription-plans/:id

Obtém os detalhes de um plano de assinatura específico.

cURL
JavaScript

curl 'https://billing.stg.catalisa.app/billing/api/v1/subscription-plans/550e8400-e29b-41d4-a716-446655440020' \
  -H 'Authorization: Bearer SEU_TOKEN'

const planId = '550e8400-e29b-41d4-a716-446655440020';

const response = await fetch(`https://billing.stg.catalisa.app/billing/api/v1/subscription-plans/${planId}`, {
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const { data } = await response.json();
console.log(`Plano: ${data.attributes.name} - R$ ${data.attributes.basePrice}`);

Response (200 OK)

{
  "data": {
    "type": "subscription-plans",
    "id": "550e8400-e29b-41d4-a716-446655440020",
    "links": {
      "self": "/api/v1/subscription-plans/550e8400-e29b-41d4-a716-446655440020"
    },
    "attributes": {
      "name": "Plano Pro",
      "description": "Acesso completo a todos os recursos da plataforma",
      "billingInterval": "MONTHLY",
      "billingCycleType": "ANNIVERSARY",
      "basePrice": 299.90,
      "currency": "BRL",
      "trialDays": 14,
      "isActive": true,
      "items": [
        {
          "productId": "550e8400-e29b-41d4-a716-446655440030",
          "productName": "API Calls",
          "quantity": 1,
          "includedUnits": 10000
        },
        {
          "productId": "550e8400-e29b-41d4-a716-446655440031",
          "productName": "Storage",
          "quantity": 1,
          "includedUnits": 100
        }
      ],
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  },
  "links": {
    "self": "/api/v1/subscription-plans/550e8400-e29b-41d4-a716-446655440020"
  }
}

Atualizar Plano

PATCH /api/v1/subscription-plans/:id

Atualiza os dados de um plano de assinatura.

Atributos Atualizáveis

Campo	Tipo	Descrição
`name`	string	Nome do plano
`description`	string	Descrição
`billingInterval`	enum	Intervalo de cobrança
`billingCycleType`	enum	Tipo do ciclo
`basePrice`	number	Preço base
`trialDays`	number	Dias de teste
`isActive`	boolean	Se está ativo

cURL
JavaScript

curl -X PATCH 'https://billing.stg.catalisa.app/billing/api/v1/subscription-plans/550e8400-e29b-41d4-a716-446655440020' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "type": "subscription-plans",
      "id": "550e8400-e29b-41d4-a716-446655440020",
      "attributes": {
        "basePrice": 349.90,
        "trialDays": 30
      }
    }
  }'

const planId = '550e8400-e29b-41d4-a716-446655440020';

const response = await fetch(`https://billing.stg.catalisa.app/billing/api/v1/subscription-plans/${planId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    data: {
      type: 'subscription-plans',
      id: planId,
      attributes: {
        basePrice: 349.90,
        trialDays: 30,
      },
    },
  }),
});

const { data } = await response.json();
console.log(`Novo preço: R$ ${data.attributes.basePrice}`);

Response (200 OK)

{
  "data": {
    "type": "subscription-plans",
    "id": "550e8400-e29b-41d4-a716-446655440020",
    "links": {
      "self": "/api/v1/subscription-plans/550e8400-e29b-41d4-a716-446655440020"
    },
    "attributes": {
      "name": "Plano Pro",
      "description": "Acesso completo a todos os recursos da plataforma",
      "billingInterval": "MONTHLY",
      "billingCycleType": "ANNIVERSARY",
      "basePrice": 349.90,
      "currency": "BRL",
      "trialDays": 30,
      "isActive": true,
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T11:00:00Z"
    }
  },
  "links": {
    "self": "/api/v1/subscription-plans/550e8400-e29b-41d4-a716-446655440020"
  }
}

Excluir Plano

DELETE /api/v1/subscription-plans/:id

Remove um plano de assinatura. O plano não pode ter assinaturas ativas.

cURL
JavaScript

curl -X DELETE 'https://billing.stg.catalisa.app/billing/api/v1/subscription-plans/550e8400-e29b-41d4-a716-446655440020' \
  -H 'Authorization: Bearer SEU_TOKEN'

const planId = '550e8400-e29b-41d4-a716-446655440020';

const response = await fetch(`https://billing.stg.catalisa.app/billing/api/v1/subscription-plans/${planId}`, {
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

if (response.status === 204) {
  console.log('Plano excluído com sucesso');
}

Response (204 No Content)

Sem corpo de resposta.

Adicionar Item ao Plano

POST /api/v1/subscription-plans/:id/items

Adiciona um produto ao plano de assinatura.

Atributos

Campo	Tipo	Obrigatório	Descrição
`productId`	string	Sim	ID do produto de cobrança
`quantity`	number	Não	Quantidade (padrão: 1)
`priceOverride`	number	Não	Preço customizado
`includedUnits`	number	Não	Unidades incluídas

cURL
JavaScript

curl -X POST 'https://billing.stg.catalisa.app/billing/api/v1/subscription-plans/550e8400-e29b-41d4-a716-446655440020/items' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "type": "subscription-plan-items",
      "attributes": {
        "productId": "550e8400-e29b-41d4-a716-446655440030",
        "quantity": 1,
        "includedUnits": 10000
      }
    }
  }'

const planId = '550e8400-e29b-41d4-a716-446655440020';

const response = await fetch(`https://billing.stg.catalisa.app/billing/api/v1/subscription-plans/${planId}/items`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    data: {
      type: 'subscription-plan-items',
      attributes: {
        productId: '550e8400-e29b-41d4-a716-446655440030',
        quantity: 1,
        includedUnits: 10000,
      },
    },
  }),
});

const { data } = await response.json();
console.log(`Item adicionado ao plano. Total de itens: ${data.attributes.items.length}`);

Response (200 OK)

Retorna o plano atualizado com o novo item.

{
  "data": {
    "type": "subscription-plans",
    "id": "550e8400-e29b-41d4-a716-446655440020",
    "attributes": {
      "name": "Plano Pro",
      "billingInterval": "MONTHLY",
      "basePrice": 299.90,
      "currency": "BRL",
      "isActive": true,
      "items": [
        {
          "productId": "550e8400-e29b-41d4-a716-446655440030",
          "productName": "API Calls",
          "quantity": 1,
          "includedUnits": 10000
        }
      ],
      "updatedAt": "2024-01-15T11:30:00Z"
    }
  }
}

Remover Item do Plano

DELETE /api/v1/subscription-plans/:planId/items/:itemId

Remove um produto do plano de assinatura.

cURL
JavaScript

curl -X DELETE 'https://billing.stg.catalisa.app/billing/api/v1/subscription-plans/550e8400-e29b-41d4-a716-446655440020/items/550e8400-e29b-41d4-a716-446655440030' \
  -H 'Authorization: Bearer SEU_TOKEN'

const planId = '550e8400-e29b-41d4-a716-446655440020';
const itemId = '550e8400-e29b-41d4-a716-446655440030';

const response = await fetch(`https://billing.stg.catalisa.app/billing/api/v1/subscription-plans/${planId}/items/${itemId}`, {
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

if (response.status === 204) {
  console.log('Item removido do plano');
}

Response (204 No Content)

Sem corpo de resposta.

Erros Comuns

Código	Erro	Descrição
400	`VALIDATION`	Dados inválidos (intervalo, preço negativo, etc.)
404	`NOT_FOUND`	Plano não encontrado
404	`NOT_FOUND`	Produto não encontrado (ao adicionar item)
409	`CONFLICT`	Plano possui assinaturas ativas (exclusão)
409	`CONFLICT`	Produto já existe no plano

Endpoints​

Atributos do Plano​

Intervalos de Cobrança (billingInterval)​

Tipos de Ciclo de Cobrança (billingCycleType)​

Estrutura do Item do Plano​

Criar Plano de Assinatura​

Atributos​

Response (201 Created)​

Listar Planos de Assinatura​

Query Parameters​

Response (200 OK)​

Obter Plano por ID​

Response (200 OK)​

Atualizar Plano​

Atributos Atualizáveis​

Response (200 OK)​

Excluir Plano​

Response (204 No Content)​

Adicionar Item ao Plano​

Atributos​

Response (200 OK)​

Remover Item do Plano​

Response (204 No Content)​

Erros Comuns​

Endpoints

Atributos do Plano

Intervalos de Cobrança (billingInterval)

Tipos de Ciclo de Cobrança (billingCycleType)

Estrutura do Item do Plano

Criar Plano de Assinatura

Atributos

Response (201 Created)

Listar Planos de Assinatura

Query Parameters

Response (200 OK)

Obter Plano por ID

Response (200 OK)

Atualizar Plano

Atributos Atualizáveis

Response (200 OK)

Excluir Plano

Response (204 No Content)

Adicionar Item ao Plano

Atributos

Response (200 OK)

Remover Item do Plano

Response (204 No Content)

Erros Comuns