Assinaturas

Visão Geral

O sistema de assinaturas da Garu permite criar produtos com cobrança recorrente. Com ele você pode:

Criar planos com intervalos flexíveis (diário, semanal, mensal, anual)
Oferecer períodos de teste gratuito
Processar pagamentos automaticamente via cartão de crédito ou Pix Automático
Gerenciar retry automático em caso de falha
Permitir que clientes gerenciem suas assinaturas via Portal

Cobrança recorrente automática funciona com cartão de crédito e com Pix Automático. PIX tradicional e Boleto exigem pagamento manual a cada ciclo.

Conceitos Principais

Termo	Descrição
Produto	O item ou serviço que você vende (ex: “Plano Premium”)
Preço de Assinatura	Um plano de preço com intervalo e valor (ex: “Mensal R$ 49,90”)
Assinatura	O acordo de cobrança ativo entre você e um cliente
Período de Teste	Dias gratuitos antes da primeira cobrança
Ciclo de Cobrança	Intervalo recorrente das cobranças

Intervalos de Cobrança

Intervalo	Valor	Descrição
Diário	`daily`	Cobrança a cada dia
Semanal	`weekly`	Cobrança a cada 7 dias
Mensal	`monthly`	Cobrança no mesmo dia todo mês
Anual	`annually`	Cobrança uma vez por ano

Ciclo de Vida da Assinatura

Status	Descrição
`pending`	Assinatura criada, aguardando primeiro pagamento
`active`	Assinatura ativa e cobrando normalmente
`pending_cancellation`	Cancelamento agendado para fim do período
`canceled`	Assinatura encerrada
`failed`	Pagamento falhou após todas as tentativas

Passo a Passo: Criar uma Assinatura

1. Criar o Produto

Primeiro, crie um produto de assinatura. Apenas o name é obrigatório - defina isSubscription: true para indicar que é um produto de assinatura. Veja a API de Criação de Produtos para mais detalhes.

curl -X POST https://garu.com.br/api/v1/products \
  -H "Authorization: Bearer sk_test_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Plano Premium",
    "isSubscription": true
  }'

Para produtos de assinatura, o preço é definido nos preços de assinatura, não no produto. Por isso, não é necessário informar value.

Resposta:

{
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Plano Premium",
  "isSubscription": true,
  "isActive": true
}

2. Criar Preços de Assinatura

Crie um ou mais planos de preço para o produto. Consulte a API de Criação de Preços para todos os campos disponíveis.

# Plano Mensal
curl -X POST https://garu.com.br/api/subscription-prices \
  -H "Authorization: Bearer sk_test_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "prod_abc123xyz",
    "name": "Plano Mensal",
    "amount": 49.90,
    "billingInterval": "monthly",
    "trialDays": 7
  }'

Resposta:

{
  "id": "price_def456uvw",
  "productId": "prod_abc123xyz",
  "name": "Plano Mensal",
  "amount": 49.90,
  "currency": "BRL",
  "billingInterval": "monthly",
  "trialDays": 7,
  "isActive": true
}

3. Obter o Link de Pagamento

Combine o uuid do produto com o id do preço para gerar o link de pagamento:

https://garu.com.br/pay/{product_uuid}?priceId={price_id}

Parâmetro	Origem	Exemplo
`product_uuid`	Campo `uuid` do produto	`c69c63d2-4207-4613-ad69-28e7e902544b`
`price_id`	Campo `id` do preço	`price_gNgQVRrG5goab0Ql`

Link completo:

https://garu.com.br/pay/c69c63d2-4207-4613-ad69-28e7e902544b?priceId=price_gNgQVRrG5goab0Ql

Salve o uuid do produto e o id do preço no seu banco de dados para gerar links de pagamento a qualquer momento.

4. Cliente Realiza o Checkout

Quando o cliente acessa o link:

Preenche informações pessoais (nome, email, CPF/CNPJ)
Insere dados do cartão de crédito
Sistema valida e cria a assinatura
Se houver período de teste, primeira cobrança é agendada
Cliente recebe confirmação

Pix Automático na Assinatura

Quer oferecer recorrência sem depender de cartão? Ligue o campo pixAutomatic no produto e o checkout passa a exibir a aba Pix Automático ao lado do cartão.

curl -X PATCH https://garu.com.br/api/v1/products/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "pixAutomatic": true }'

Com o toggle ligado, o comportamento no checkout muda assim:

O cliente acessa o mesmo link de pagamento (/pay/{uuid}?priceId=...).
Escolhe a aba Pix Automático em vez de cartão.
Autoriza a recorrência uma vez no app do banco (seção “Pix Automático” / “Recorrência Pix”).
A assinatura sai de waitingPayment e vira active — os próximos ciclos são debitados sozinhos.

A partir daí, os webhooks (subscription.activated, transaction.payment.succeeded, subscription.renewed) são os mesmos do cartão. Para diferenciar a origem, cheque paymentMethod === 'pix_automatic' no payload.

Guia completo do Pix Automático

Autorização, ciclos silenciosos, cancelamento pelos dois lados e modelo de falha.

O campo pixAutomatic vem desligado por padrão (false). Ligar é aditivo: o cartão de crédito continua funcionando normalmente como método de assinatura.

Período de Teste (Trial)

O período de teste permite que clientes experimentem antes de pagar.

Como Funciona

Assinatura Criada: Status active imediatamente
Durante o Trial: Cliente tem acesso, sem cobranças
Trial Termina: Primeira cobrança processada automaticamente
Cobrança Continua: Ciclo normal de cobrança inicia

Exemplo de Timeline

Para um trial de 14 dias iniciando em 1º de janeiro:

Data	Evento
1 Jan	Assinatura criada, trial inicia
1-14 Jan	Período de teste (sem cobranças)
15 Jan	Primeira cobrança de R$ 49,90
15 Fev	Segunda cobrança de R$ 49,90
…	Continua mensalmente

Clientes podem cancelar durante o trial sem serem cobrados.

Lógica de Retry de Pagamento

Quando um pagamento falha, o sistema tenta novamente automaticamente.

Estratégia de Retry

Tentativa	Timing	Ação
1	Imediatamente	Primeira tentativa
2	+3 dias	Retry automático
3	+3 dias	Retry automático
4	+3 dias	Tentativa final
Falha	Após 4ª	Assinatura marcada como `failed`

Motivos Comuns de Falha

Motivo	Descrição
`insufficient_funds`	Saldo insuficiente
`card_expired`	Cartão expirado
`card_declined`	Transação recusada pelo banco
`invalid_card`	Número ou CVV inválido
`fraud_suspected`	Detecção de fraude

Cancelamento

Existem duas formas de cancelar uma assinatura. Veja a API de Cancelamento para mais detalhes, ou Pausar e Retomar para opções de pausa temporária.

Cancelamento Imediato

Cliente perde acesso imediatamente:

curl -X POST https://garu.com.br/api/subscriptions/100/cancel \
  -H "Authorization: Bearer sk_test_sua_chave" \
  -d '{"cancelImmediately": true}'

Cancelamento Agendado

Cliente mantém acesso até o fim do período:

curl -X POST https://garu.com.br/api/subscriptions/100/cancel \
  -H "Authorization: Bearer sk_test_sua_chave" \
  -d '{"cancelImmediately": false}'

Resultado:

Status muda para pending_cancellation
Cliente mantém acesso até o período terminar
Nenhuma cobrança adicional
No fim do período, status muda para canceled

Portal do Cliente

O Portal permite que assinantes gerenciem suas assinaturas de forma autônoma. Veja a API do Portal do Cliente para configurações avançadas e todos os endpoints disponíveis.

Criando uma Sessão do Portal

curl -X POST https://garu.com.br/api/portal/sessions \
  -H "Authorization: Bearer sk_test_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": 50,
    "returnUrl": "https://seusite.com/conta"
  }'

Resposta:

{
  "token": "a1b2c3d4e5f6...",
  "expiresAt": "2024-01-15T11:30:00.000Z",
  "portalUrl": "/portal?token=a1b2c3d4e5f6..."
}

URL do Portal

https://garu.com.br/portal?token={session_token}

O que Clientes Podem Fazer

Ação	Descrição
Cancelar assinatura	Encerrar a assinatura
Atualizar pagamento	Trocar cartão de crédito
Atualizar dados	Alterar informações de cobrança
Ver histórico	Consultar pagamentos anteriores
Pausar/Retomar	Pausar temporariamente a cobrança

Configure o Portal em Configurações → Portal do Cliente no Dashboard.

Webhooks de Assinatura

Configure webhooks para receber notificações em tempo real. Consulte a documentação de Webhooks para implementação completa e validação de assinatura.

Eventos Disponíveis

Evento	Descrição
`subscription.created`	Nova assinatura criada
`subscription.activated`	Assinatura ativada
`subscription.payment_success`	Pagamento recorrente confirmado
`subscription.payment_failed`	Pagamento falhou (pode haver retry)
`subscription.canceled`	Assinatura cancelada
`subscription.trial_ending`	Trial termina em 3 dias

Exemplo de Payload

{
  "event": "subscription.payment_success",
  "timestamp": "2024-02-15T10:00:00.000Z",
  "data": {
    "subscription": {
      "id": 100,
      "status": "active",
      "customerId": 50
    },
    "payment": {
      "amount": 49.90,
      "transactionId": "tx_abc123",
      "paidAt": "2024-02-15T10:00:00.000Z"
    }
  }
}

Exemplo Completo

const GARU_API = 'https://garu.com.br/api';

class GaruAssinaturas {
  constructor(apiKey) {
    this.apiKey = apiKey;
  }

  async request(method, endpoint, data) {
    const response = await fetch(`${GARU_API}${endpoint}`, {
      method,
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      },
      body: data ? JSON.stringify(data) : undefined
    });
    return response.json();
  }

  // Criar produto de assinatura (apenas nome é obrigatório)
  async criarProduto(nome) {
    return this.request('POST', '/products', {
      name: nome,
      isSubscription: true
    });
  }

  // Criar preço de assinatura (productId é o UUID do produto)
  async criarPreco(productId, nome, valor, intervalo, trialDias = 0) {
    return this.request('POST', '/subscription-prices', {
      productId, // UUID do produto (ex: 'prod_abc123xyz')
      name: nome,
      amount: valor, // Valor em Reais (ex: 49.90)
      billingInterval: intervalo, // 'daily', 'weekly', 'monthly', 'annually'
      trialDays: trialDias
    });
  }

  // Gerar link de checkout
  getCheckoutUrl(productUuid, priceId) {
    return `https://garu.com.br/pay/${productUuid}?priceId=${priceId}`;
  }

  // Cancelar assinatura
  async cancelar(subscriptionId, imediatamente = false) {
    return this.request('POST', `/subscriptions/${subscriptionId}/cancel`, {
      cancelImmediately: imediatamente
    });
  }

  // Criar sessão do portal
  async criarSessaoPortal(customerId, returnUrl) {
    return this.request('POST', '/portal/sessions', {
      customerId,
      returnUrl
    });
  }
}

// Uso
const garu = new GaruAssinaturas('sk_test_sua_chave');

// Criar produto (apenas nome é obrigatório)
const produto = await garu.criarProduto('SaaS Premium');
// produto.uuid = 'prod_abc123xyz'

// Criar planos de preço (usando o UUID do produto)
const planoMensal = await garu.criarPreco(produto.uuid, 'Mensal', 49.90, 'monthly', 7);
const planoAnual = await garu.criarPreco(produto.uuid, 'Anual', 479.00, 'annually', 14);

// Links de checkout
console.log('Mensal:', garu.getCheckoutUrl(produto.uuid, planoMensal.id));
console.log('Anual:', garu.getCheckoutUrl(produto.uuid, planoAnual.id));

Próximos Passos

Criar Preço

Crie planos de preço para assinaturas

Listar Assinaturas

Consulte todas as assinaturas

Detalhes da Assinatura

Consulte os detalhes de uma assinatura

Cancelar Assinatura

Cancele uma assinatura

Pausar/Retomar

Pause temporariamente as cobranças

Eventos

Histórico de eventos e pagamentos

Portal do Cliente

Configurar e usar o portal de autoatendimento

Webhooks

Receber notificações de eventos

​Visão Geral

​Conceitos Principais

​Intervalos de Cobrança

​Ciclo de Vida da Assinatura

​Passo a Passo: Criar uma Assinatura

​1. Criar o Produto

​2. Criar Preços de Assinatura

​3. Obter o Link de Pagamento

​4. Cliente Realiza o Checkout

​Pix Automático na Assinatura

Guia completo do Pix Automático

​Período de Teste (Trial)

​Como Funciona

​Exemplo de Timeline

​Lógica de Retry de Pagamento

​Estratégia de Retry

​Motivos Comuns de Falha

​Cancelamento

​Cancelamento Imediato

​Cancelamento Agendado

​Portal do Cliente

​Criando uma Sessão do Portal

​URL do Portal

​O que Clientes Podem Fazer

​Webhooks de Assinatura

​Eventos Disponíveis

​Exemplo de Payload

​Exemplo Completo

​Próximos Passos

Criar Preço

Listar Assinaturas

Detalhes da Assinatura

Cancelar Assinatura

Pausar/Retomar

Eventos

Portal do Cliente

Webhooks

Visão Geral

Conceitos Principais

Intervalos de Cobrança

Ciclo de Vida da Assinatura

Passo a Passo: Criar uma Assinatura

1. Criar o Produto

2. Criar Preços de Assinatura

3. Obter o Link de Pagamento

4. Cliente Realiza o Checkout

Pix Automático na Assinatura

Período de Teste (Trial)

Como Funciona

Exemplo de Timeline

Lógica de Retry de Pagamento

Estratégia de Retry

Motivos Comuns de Falha

Cancelamento

Cancelamento Imediato

Cancelamento Agendado

Portal do Cliente

Criando uma Sessão do Portal

URL do Portal

O que Clientes Podem Fazer

Webhooks de Assinatura

Eventos Disponíveis

Exemplo de Payload

Exemplo Completo

Próximos Passos