Assinaturas

Gerenciamento de assinaturas (Subscriptions) para cobrança recorrente.

Endpoints

Método	Endpoint	Descrição	Permissão
POST	`/billing/api/v1/subscriptions`	Criar assinatura	`BILLING_SUBSCRIPTIONS_CREATE`
GET	`/billing/api/v1/subscriptions`	Listar assinaturas	`BILLING_SUBSCRIPTIONS_READ`
GET	`/billing/api/v1/subscriptions/:id`	Obter assinatura por ID	`BILLING_SUBSCRIPTIONS_READ`
PATCH	`/billing/api/v1/subscriptions/:id`	Atualizar assinatura	`BILLING_SUBSCRIPTIONS_UPDATE`
POST	`/billing/api/v1/subscriptions/:id/cancel`	Cancelar assinatura	`BILLING_SUBSCRIPTIONS_CANCEL`
POST	`/billing/api/v1/subscriptions/:id/pause`	Pausar assinatura	`BILLING_SUBSCRIPTIONS_UPDATE`
POST	`/billing/api/v1/subscriptions/:id/resume`	Retomar assinatura	`BILLING_SUBSCRIPTIONS_UPDATE`

Atributos

Campo	Tipo	Descrição
`billingAccountId`	string (UUID)	ID da conta de faturamento
`planId`	string (UUID)	ID do plano de assinatura
`planName`	string	Nome do plano (somente leitura)
`status`	enum	Status da assinatura
`quantity`	number	Quantidade de licenças/unidades
`currentPeriodStart`	datetime	Início do período atual
`currentPeriodEnd`	datetime	Fim do período atual
`trialStart`	datetime	Início do período de teste
`trialEnd`	datetime	Fim do período de teste
`canceledAt`	datetime	Data do cancelamento
`cancelAtPeriodEnd`	boolean	Se cancela no fim do período
`pausedAt`	datetime	Data da pausa
`unitPrice`	number	Preço por unidade
`currency`	string	Moeda
`createdAt`	datetime	Data de criação
`updatedAt`	datetime	Data da última atualização

Status da Assinatura

Status	Descrição
`TRIAL`	Em período de teste gratuito
`ACTIVE`	Assinatura ativa e cobrando normalmente
`PAUSED`	Assinatura pausada temporariamente
`CANCELED`	Assinatura cancelada
`EXPIRED`	Assinatura expirada (não renovada)

Criar Assinatura

POST /api/v1/subscriptions

Cria uma nova assinatura para uma conta de faturamento.

Atributos

Campo	Tipo	Obrigatório	Descrição
`billingAccountId`	string	Sim	ID da conta de faturamento
`planId`	string	Sim	ID do plano de assinatura
`quantity`	number	Não	Quantidade (padrão: 1)
`startDate`	datetime	Não	Data de início (padrão: agora)
`skipTrial`	boolean	Não	Pular período de teste

cURL
JavaScript

curl -X POST 'https://billing.stg.catalisa.app/billing/api/v1/subscriptions' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "type": "subscriptions",
      "attributes": {
        "billingAccountId": "550e8400-e29b-41d4-a716-446655440010",
        "planId": "550e8400-e29b-41d4-a716-446655440020",
        "quantity": 5
      }
    }
  }'

const response = await fetch('https://billing.stg.catalisa.app/billing/api/v1/subscriptions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    data: {
      type: 'subscriptions',
      attributes: {
        billingAccountId: '550e8400-e29b-41d4-a716-446655440010',
        planId: '550e8400-e29b-41d4-a716-446655440020',
        quantity: 5,
      },
    },
  }),
});

const { data } = await response.json();
console.log(`Assinatura criada: ${data.id}`);
console.log(`Status: ${data.attributes.status}`);
console.log(`Período de teste até: ${data.attributes.trialEnd}`);

Response (201 Created)

{
  "data": {
    "type": "subscriptions",
    "id": "550e8400-e29b-41d4-a716-446655440040",
    "links": {
      "self": "/api/v1/subscriptions/550e8400-e29b-41d4-a716-446655440040"
    },
    "attributes": {
      "billingAccountId": "550e8400-e29b-41d4-a716-446655440010",
      "planId": "550e8400-e29b-41d4-a716-446655440020",
      "planName": "Plano Pro",
      "status": "TRIAL",
      "quantity": 5,
      "currentPeriodStart": "2024-01-15T10:30:00Z",
      "currentPeriodEnd": "2024-02-15T10:30:00Z",
      "trialStart": "2024-01-15T10:30:00Z",
      "trialEnd": "2024-01-29T10:30:00Z",
      "cancelAtPeriodEnd": false,
      "unitPrice": 299.90,
      "currency": "BRL",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  },
  "links": {
    "self": "/api/v1/subscriptions/550e8400-e29b-41d4-a716-446655440040"
  }
}

Listar Assinaturas

GET /api/v1/subscriptions

Lista todas as assinaturas 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[billingAccountId]`	UUID	Filtrar por conta
`filter[planId]`	UUID	Filtrar por plano
`filter[status]`	enum	Filtrar por status

cURL
JavaScript

curl 'https://billing.stg.catalisa.app/billing/api/v1/subscriptions?filter[status]=ACTIVE&filter[billingAccountId]=550e8400-e29b-41d4-a716-446655440010' \
  -H 'Authorization: Bearer SEU_TOKEN'

const params = new URLSearchParams({
  'filter[status]': 'ACTIVE',
  'filter[billingAccountId]': '550e8400-e29b-41d4-a716-446655440010',
});

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

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

Response (200 OK)

{
  "data": [
    {
      "type": "subscriptions",
      "id": "550e8400-e29b-41d4-a716-446655440040",
      "links": {
        "self": "/api/v1/subscriptions/550e8400-e29b-41d4-a716-446655440040"
      },
      "attributes": {
        "billingAccountId": "550e8400-e29b-41d4-a716-446655440010",
        "planId": "550e8400-e29b-41d4-a716-446655440020",
        "planName": "Plano Pro",
        "status": "ACTIVE",
        "quantity": 5,
        "currentPeriodStart": "2024-02-15T10:30:00Z",
        "currentPeriodEnd": "2024-03-15T10:30:00Z",
        "cancelAtPeriodEnd": false,
        "unitPrice": 299.90,
        "currency": "BRL",
        "createdAt": "2024-01-15T10:30:00Z",
        "updatedAt": "2024-02-15T10:30:00Z"
      }
    }
  ],
  "meta": {
    "totalItems": 3,
    "totalPages": 1,
    "currentPage": 1,
    "itemsPerPage": 20
  },
  "links": {
    "self": "/api/v1/subscriptions?page[number]=1&page[size]=20"
  }
}

Obter Assinatura por ID

GET /api/v1/subscriptions/:id

Obtém os detalhes de uma assinatura específica.

cURL
JavaScript

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

const subscriptionId = '550e8400-e29b-41d4-a716-446655440040';

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

const { data } = await response.json();
console.log(`Plano: ${data.attributes.planName}`);
console.log(`Status: ${data.attributes.status}`);
console.log(`Próxima cobrança: ${data.attributes.currentPeriodEnd}`);

Response (200 OK)

{
  "data": {
    "type": "subscriptions",
    "id": "550e8400-e29b-41d4-a716-446655440040",
    "links": {
      "self": "/api/v1/subscriptions/550e8400-e29b-41d4-a716-446655440040"
    },
    "attributes": {
      "billingAccountId": "550e8400-e29b-41d4-a716-446655440010",
      "planId": "550e8400-e29b-41d4-a716-446655440020",
      "planName": "Plano Pro",
      "status": "ACTIVE",
      "quantity": 5,
      "currentPeriodStart": "2024-02-15T10:30:00Z",
      "currentPeriodEnd": "2024-03-15T10:30:00Z",
      "cancelAtPeriodEnd": false,
      "unitPrice": 299.90,
      "currency": "BRL",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-02-15T10:30:00Z"
    }
  },
  "links": {
    "self": "/api/v1/subscriptions/550e8400-e29b-41d4-a716-446655440040"
  }
}

Atualizar Assinatura

PATCH /api/v1/subscriptions/:id

Atualiza a quantidade de licenças/unidades de uma assinatura.

Atributos Atualizáveis

Campo	Tipo	Descrição
`quantity`	number	Nova quantidade

cURL
JavaScript

curl -X PATCH 'https://billing.stg.catalisa.app/billing/api/v1/subscriptions/550e8400-e29b-41d4-a716-446655440040' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "type": "subscriptions",
      "id": "550e8400-e29b-41d4-a716-446655440040",
      "attributes": {
        "quantity": 10
      }
    }
  }'

const subscriptionId = '550e8400-e29b-41d4-a716-446655440040';

const response = await fetch(`https://billing.stg.catalisa.app/billing/api/v1/subscriptions/${subscriptionId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    data: {
      type: 'subscriptions',
      id: subscriptionId,
      attributes: {
        quantity: 10,
      },
    },
  }),
});

const { data } = await response.json();
console.log(`Nova quantidade: ${data.attributes.quantity}`);

Response (200 OK)

{
  "data": {
    "type": "subscriptions",
    "id": "550e8400-e29b-41d4-a716-446655440040",
    "attributes": {
      "billingAccountId": "550e8400-e29b-41d4-a716-446655440010",
      "planId": "550e8400-e29b-41d4-a716-446655440020",
      "planName": "Plano Pro",
      "status": "ACTIVE",
      "quantity": 10,
      "currentPeriodStart": "2024-02-15T10:30:00Z",
      "currentPeriodEnd": "2024-03-15T10:30:00Z",
      "unitPrice": 299.90,
      "currency": "BRL",
      "updatedAt": "2024-02-20T14:00:00Z"
    }
  }
}

Cancelar Assinatura

POST /api/v1/subscriptions/:id/cancel

Cancela uma assinatura. Pode cancelar imediatamente ou ao fim do período.

Query Parameters

Parâmetro	Tipo	Descrição
`cancelAtPeriodEnd`	boolean	Se `true`, cancela ao fim do período atual

cURL
JavaScript

# Cancelar ao fim do período
curl -X POST 'https://billing.stg.catalisa.app/billing/api/v1/subscriptions/550e8400-e29b-41d4-a716-446655440040/cancel?cancelAtPeriodEnd=true' \
  -H 'Authorization: Bearer SEU_TOKEN'

# Cancelar imediatamente
curl -X POST 'https://billing.stg.catalisa.app/billing/api/v1/subscriptions/550e8400-e29b-41d4-a716-446655440040/cancel' \
  -H 'Authorization: Bearer SEU_TOKEN'

const subscriptionId = '550e8400-e29b-41d4-a716-446655440040';

// Cancelar ao fim do período (mantém acesso até a data de renovação)
const response = await fetch(`https://billing.stg.catalisa.app/billing/api/v1/subscriptions/${subscriptionId}/cancel?cancelAtPeriodEnd=true`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const { data } = await response.json();
console.log(`Status: ${data.attributes.status}`);
console.log(`Cancela em: ${data.attributes.currentPeriodEnd}`);

Response (200 OK)

{
  "data": {
    "type": "subscriptions",
    "id": "550e8400-e29b-41d4-a716-446655440040",
    "attributes": {
      "billingAccountId": "550e8400-e29b-41d4-a716-446655440010",
      "planId": "550e8400-e29b-41d4-a716-446655440020",
      "planName": "Plano Pro",
      "status": "ACTIVE",
      "quantity": 5,
      "currentPeriodStart": "2024-02-15T10:30:00Z",
      "currentPeriodEnd": "2024-03-15T10:30:00Z",
      "canceledAt": "2024-02-20T15:00:00Z",
      "cancelAtPeriodEnd": true,
      "unitPrice": 299.90,
      "currency": "BRL",
      "updatedAt": "2024-02-20T15:00:00Z"
    }
  }
}

Pausar Assinatura

POST /api/v1/subscriptions/:id/pause

Pausa uma assinatura temporariamente. Não gera cobranças enquanto pausada.

cURL
JavaScript

curl -X POST 'https://billing.stg.catalisa.app/billing/api/v1/subscriptions/550e8400-e29b-41d4-a716-446655440040/pause' \
  -H 'Authorization: Bearer SEU_TOKEN'

const subscriptionId = '550e8400-e29b-41d4-a716-446655440040';

const response = await fetch(`https://billing.stg.catalisa.app/billing/api/v1/subscriptions/${subscriptionId}/pause`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const { data } = await response.json();
console.log(`Status: ${data.attributes.status}`); // PAUSED
console.log(`Pausada em: ${data.attributes.pausedAt}`);

Response (200 OK)

{
  "data": {
    "type": "subscriptions",
    "id": "550e8400-e29b-41d4-a716-446655440040",
    "attributes": {
      "billingAccountId": "550e8400-e29b-41d4-a716-446655440010",
      "planId": "550e8400-e29b-41d4-a716-446655440020",
      "planName": "Plano Pro",
      "status": "PAUSED",
      "quantity": 5,
      "currentPeriodStart": "2024-02-15T10:30:00Z",
      "currentPeriodEnd": "2024-03-15T10:30:00Z",
      "pausedAt": "2024-02-20T16:00:00Z",
      "unitPrice": 299.90,
      "currency": "BRL",
      "updatedAt": "2024-02-20T16:00:00Z"
    }
  }
}

Retomar Assinatura

POST /api/v1/subscriptions/:id/resume

Retoma uma assinatura que estava pausada.

cURL
JavaScript

curl -X POST 'https://billing.stg.catalisa.app/billing/api/v1/subscriptions/550e8400-e29b-41d4-a716-446655440040/resume' \
  -H 'Authorization: Bearer SEU_TOKEN'

const subscriptionId = '550e8400-e29b-41d4-a716-446655440040';

const response = await fetch(`https://billing.stg.catalisa.app/billing/api/v1/subscriptions/${subscriptionId}/resume`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const { data } = await response.json();
console.log(`Status: ${data.attributes.status}`); // ACTIVE

Response (200 OK)

{
  "data": {
    "type": "subscriptions",
    "id": "550e8400-e29b-41d4-a716-446655440040",
    "attributes": {
      "billingAccountId": "550e8400-e29b-41d4-a716-446655440010",
      "planId": "550e8400-e29b-41d4-a716-446655440020",
      "planName": "Plano Pro",
      "status": "ACTIVE",
      "quantity": 5,
      "currentPeriodStart": "2024-02-20T16:30:00Z",
      "currentPeriodEnd": "2024-03-20T16:30:00Z",
      "pausedAt": null,
      "unitPrice": 299.90,
      "currency": "BRL",
      "updatedAt": "2024-02-20T16:30:00Z"
    }
  }
}

Ciclo de Vida da Assinatura

Estados da Assinatura

TRIAL (Período de Teste)

Período de teste gratuito (opcional)
Duração definida em trialDays do plano
Não gera cobranças
Transições:
- → ACTIVE: Fim do período de teste (automático)

ACTIVE (Ativa)

Assinatura ativa e gerando cobranças recorrentes
Gera faturas automaticamente ao fim de cada período
Transições:
- → PAUSED: Chamada de pause() (pausar temporariamente)
- → CANCELED: Chamada de cancel() (cancelar definitivamente)

PAUSED (Pausada)

Assinatura pausada temporariamente
Não gera cobranças enquanto pausada
Pode retomar a qualquer momento
Transições:
- → ACTIVE: Chamada de resume() (retomar assinatura)

CANCELED (Cancelada)

Assinatura cancelada definitivamente
Estado final
Não permite mais transições
Pode ser cancelada imediatamente ou ao fim do período atual

EXPIRED (Expirada)

Assinatura expirou por falta de renovação
Estado final
Não permite mais transições

Erros Comuns

Código	Erro	Descrição
400	`VALIDATION`	Dados inválidos
404	`NOT_FOUND`	Assinatura, conta ou plano não encontrado
409	`CONFLICT`	Conta já possui assinatura do mesmo plano
409	`CONFLICT`	Assinatura não está ativa (para pausar/cancelar)
409	`CONFLICT`	Assinatura não está pausada (para retomar)
409	`CONFLICT`	Assinatura já foi cancelada

Endpoints​

Atributos​

Status da Assinatura​

Criar Assinatura​

Atributos​

Response (201 Created)​

Listar Assinaturas​

Query Parameters​

Response (200 OK)​

Obter Assinatura por ID​

Response (200 OK)​

Atualizar Assinatura​

Atributos Atualizáveis​

Response (200 OK)​

Cancelar Assinatura​

Query Parameters​

Response (200 OK)​

Pausar Assinatura​

Response (200 OK)​

Retomar Assinatura​

Response (200 OK)​

Ciclo de Vida da Assinatura​

Estados da Assinatura​

Erros Comuns​

Endpoints

Atributos

Status da Assinatura

Criar Assinatura

Atributos

Response (201 Created)

Listar Assinaturas

Query Parameters

Response (200 OK)

Obter Assinatura por ID

Response (200 OK)

Atualizar Assinatura

Atributos Atualizáveis

Response (200 OK)

Cancelar Assinatura

Query Parameters

Response (200 OK)

Pausar Assinatura

Response (200 OK)

Retomar Assinatura

Response (200 OK)

Ciclo de Vida da Assinatura

Estados da Assinatura

Erros Comuns