Assinaturas

Gerencie assinaturas de clientes.

Criar Assinatura

Inicia uma nova assinatura no estado PAUSED e retorna uma URL de checkout para o cliente concluir o primeiro pagamento.

Endpoint: POST /subscription/create

Corpo da Solicitação

Campo	Tipo	Descrição	Obrigatório
planId	string	ID do plano de assinatura (UUID)	Sim
customerEmail	string	Endereço de e-mail do cliente	Sim
customerName	string	Nome do cliente	Não
metadata	object	Metadados adicionais para a assinatura	Não

Exemplo de Solicitação

{
  "planId": "550e8400-e29b-41d4-a716-446655440000",
  "customerEmail": "john@example.com",
  "customerName": "John Doe"
}

Resposta de Sucesso

{
  "success": true,
  "data": {
    "subscriptionId": "uuid-v4-subscription-id",
    "checkoutUrl": "https://paysgator.com/checkout/sub_...",
    "status": "PAUSED"
  }
}

Obter Assinatura

Recupera detalhes de uma assinatura específica.

Endpoint: GET /subscription/{id}

Parâmetros

Parâmetro	Tipo	Descrição	Obrigatório
id	string	O UUID da assinatura	Sim

Resposta de Sucesso

{
  "success": true,
  "data": {
    "id": "uuid-v4-subscription-id",
    "planId": "uuid-v4-plan-id",
    "customerEmail": "john@example.com",
    "status": "ACTIVE",
    "currentPeriodStart": "2023-10-27T10:00:00Z",
    "currentPeriodEnd": "2023-11-27T10:00:00Z",
    "createdAt": "2023-10-27T10:00:00Z"
  }
}

Listar Assinaturas

Lista todas as assinaturas da sua empresa. Você pode filtrar por e-mail do cliente, status ou ID do plano.

Endpoint: GET /subscriptions

Parâmetros de Consulta

Parâmetro	Tipo	Descrição	Obrigatório
customerEmail	string	Filtrar por e-mail do cliente	Não
status	string	Filtrar por status (ACTIVE, CANCELED, PAST_DUE, PAUSED)	Não
planId	string	Filtrar por ID do plano (UUID)	Não

Resposta de Sucesso

{
  "success": true,
  "data": [
    {
      "id": "uuid-v4-subscription-id",
      "planId": "uuid-v4-plan-id",
      "customerEmail": "john@example.com",
      "status": "ACTIVE",
      "currentPeriodStart": "2023-10-27T10:00:00Z",
      "currentPeriodEnd": "2023-11-27T10:00:00Z",
      "createdAt": "2023-10-27T10:00:00Z"
    }
  ]
}

Atualizar Assinatura

Atualize o status de uma assinatura existente. Utilize este endpoint para cancelar, pausar ou retomar uma assinatura.

Endpoint: PATCH /subscriptions/{id}

Parâmetros

Parâmetro	Tipo	Descrição	Obrigatório
id	string	O UUID da assinatura	Sim

Corpo da Solicitação

Campo	Tipo	Descrição	Obrigatório
action	string	Ação a realizar: cancel, pause, ou resume	Sim

Exemplo de Solicitação

{
  "action": "cancel"
}

Resposta de Sucesso

{
  "id": "uuid-v4-subscription-id",
  "status": "CANCELED",
  "customerEmail": "cliente@exemplo.com",
  "currentPeriodEnd": "2023-11-27T10:00:00Z"
}

Respostas de Erro

• 400 Bad Request: Ação inválida.
• 401 Unauthorized: Chave de API ausente ou inválida.
• 403 Forbidden: Acesso não autorizado a esta assinatura.
• 404 Not Found: Assinatura não encontrada.