> ## Documentation Index
> Fetch the complete documentation index at: https://docs.garu.com.br/llms.txt
> Use this file to discover all available pages before exploring further.
# Assinaturas
> Guia completo para criar e gerenciar produtos com cobrança recorrente
## 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](/guias/pix-automatico)
* 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](/guias/pix-automatico)**. 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](/api-reference/produtos/criar) para mais detalhes.
```bash theme={null}
curl -X POST https://garu.com.br/api/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:**
```json theme={null}
{
"id": 123,
"uuid": "prod_abc123xyz",
"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](/api-reference/assinaturas/precos/criar) para todos os campos disponíveis.
```bash theme={null}
# 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:**
```json theme={null}
{
"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:
1. Preenche informações pessoais (nome, email, CPF/CNPJ)
2. Insere dados do cartão de crédito
3. Sistema valida e cria a assinatura
4. Se houver período de teste, primeira cobrança é agendada
5. 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.
```bash theme={null}
curl -X PATCH https://garu.com.br/api/products/123 \
-H "Authorization: Bearer sk_live_xxx" \
-H "Content-Type: application/json" \
-d '{ "pixAutomatic": true }'
```
Com o toggle ligado, o comportamento no checkout muda assim:
1. O cliente acessa o mesmo link de pagamento (`/pay/{uuid}?priceId=...`).
2. Escolhe a aba **Pix Automático** em vez de cartão.
3. Autoriza a recorrência **uma vez** no app do banco (seção "Pix Automático" / "Recorrência Pix").
4. 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.
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
1. **Assinatura Criada**: Status `active` imediatamente
2. **Durante o Trial**: Cliente tem acesso, sem cobranças
3. **Trial Termina**: Primeira cobrança processada automaticamente
4. **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](/api-reference/assinaturas/cancelar) para mais detalhes, ou [Pausar](/api-reference/assinaturas/pausar) e [Retomar](/api-reference/assinaturas/retomar) para opções de pausa temporária.
### Cancelamento Imediato
Cliente perde acesso imediatamente:
```bash theme={null}
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:
```bash theme={null}
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](/api-reference/assinaturas/portal) para configurações avançadas e todos os endpoints disponíveis.
### Criando uma Sessão do Portal
```bash theme={null}
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:**
```json theme={null}
{
"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](/api-reference/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
```json theme={null}
{
"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
```javascript theme={null}
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
Crie planos de preço para assinaturas
Consulte todas as assinaturas
Consulte os detalhes de uma assinatura
Cancele uma assinatura
Pause temporariamente as cobranças
Histórico de eventos e pagamentos
Configurar e usar o portal de autoatendimento
Receber notificações de eventos