# Subscrições

Automatize pagamentos recorrentes com gestão flexível de subscrições.

## Visão Geral

Subscrições são pagamentos recorrentes de um montante fixo, cobrados automaticamente em intervalos regulares. São perfeitas para serviços de adesão, produtos SaaS e qualquer modelo de negócio que necessite de receita recorrente previsível.

## Funcionalidades Principais

- **Cobrança Automática**: Pagamentos processados automaticamente conforme agendado
- **Frequências Flexíveis**: De diariamente a cada 3 anos
- **Lógica de Repetição**: Tentativas configuráveis para pagamentos falhados
- **Métodos Alternativos**: Método de pagamento secundário se o principal falhar
- **Finito ou Ilimitado**: Defina data de fim/limite de capturas ou funcione indefinidamente
- **Gestão Fácil**: Ative, pause, atualize ou cancele a qualquer momento


## Métodos de Pagamento Suportados

- Cartão de Crédito/Débito
- Débito Direto


## Opções de Frequência

| Frequência | Descrição |
|  --- | --- |
| `1D` | Diariamente |
| `1W` | Semanalmente |
| `2W` | Bi-semanal (cada 2 semanas) |
| `1M` | Mensalmente |
| `2M` | Bi-mensal (cada 2 meses) |
| `3M` | Trimestralmente (cada 3 meses) |
| `4M` | A cada 4 meses |
| `6M` | Semestralmente (cada 6 meses) |
| `1Y` | Anualmente |
| `2Y` | A cada 2 anos |
| `3Y` | A cada 3 anos |


## Ciclo de Vida da Subscrição

![Subscription lifecycle](https://mermaid.ink/svg/pako:eNq1Vt1q2zAUfpWDLkYC6U9auiSGFkrLoBftwlJ2MQJFkY9jUVvyZHluVvImYw-3J9lRLDtOm6broL6S5fOdn-98OvIjEzpEFrAcvxeoBF5KPjc8nSqghxdWqyKdoaneM26sFDLjysI1GhG7Bc_X6_MsS6TgVmr1HDGejM_HV85-zBcpOvPx1RazhNtIm9QZTkSMYZFsi3-DttTmvu3Ob0197DqrvbOzKnQAFwa5RZgUs1wYmbk8oTP-PLmFg7y1160cVCgH9ykF8JUnMnQuPgBtlNyEILSK5NwjvOEGxgeVSlrJE5jJJJFqDmIhEoRObrkt8tMMVUi7PrLSBNA_0MDazSUKGaKH2UWGAQie2cLgndIlaAMGFZZ8lmDNAE9s26bafJKnJy2Ac2sxzRoAdOqEVxG7a7BH7G0U-QXzIrGVESY5tpPZEnUNrFsMkTS59eVlVHmWcLXGbmPkRoNMUwylo7dOmzoqHOGNBInYNh9XEfDGuCT18KpuDKHjeaQAaFoFO1itsUkhBOb5-uOLhV1zUmdVzinkO2GEq8VKhFDCUOIs1vrelS0jf6JIKy2N3tU1eNetfFf81wl_4jIhs83IidYZtcyaBXQq_RbG9aomIz-YcXGvo6i7iXtJO5Urn9FzyKuKaTJ3vXobsxHVh-F7EFt5fsKA04KjdCVFVI60cAdH_5VA5P3frYSM_9iDW-oAZYdGueOQ-fanaGMdvqklLpuVpA6iSjvd9yoQSmljmhQuaneHEpqX1ln2EhaFMe7egk49MyAy1V226L4yevxgVvhgn07lzXH8EuVjox1PkPsZFj4_Art4_vP7F-Q8bY5wzTcQm6HLpima9djcyJAF1hTYYymalLtX9uhMpszGmOKUBbQsY2lpOVVLAtFN-U3rtMYZXcxjFkScBkSPFZm7yfyF35hQNDQXulCWBScnKxcseGQPLDga9veP-sfHg_5w9HHYP6SPCxYcD_dH9AxGo8PhaDAYnCx77Ocq5uH-cEA2NJ-tNtfVb0Y1bNjyL5I9xzY)

## Início Rápido

### Criar uma Subscrição


```bash
POST /subscription

{
  "frequency": "1M",
  "value": 29.99,
  "currency": "EUR",
  "method": "cc",
  "start_time": "2024-02-01 00:00",
  "max_captures": 12,
  "customer": {
    "name": "John Doe",
    "email": "john@example.com"
  },
  "capture": {
    "descriptive": "Monthly SaaS Subscription"
  },
  "retries": 3,
  "failover": true
}
```

Resposta:


```json
{
  "id": "sub-123",
  "status": "active",
  "frequency": "1M",
  "value": 29.99,
  "start_time": "2024-02-01 00:00"
}
```

## Tipos de Subscrição

### Subscrições Finitas

Terminam após uma data específica ou número de capturas:


```json
{
  "frequency": "1M",
  "value": 9.99,
  "start_time": "2024-01-01",
  "max_captures": 12  // 12 months
}
```

Ou:


```json
{
  "frequency": "1M",
  "value": 9.99,
  "start_time": "2024-01-01",
  "expiration_time": "2024-12-31 23:59"  // Specific end date
}
```

### Subscrições Ilimitadas

Continuam até serem canceladas manualmente:


```json
{
  "frequency": "1M",
  "value": 9.99,
  "start_time": "2024-01-01",
  "unlimited_payments": true  // No end date
}
```

## Tipos de Ciclo

Cada subscrição cria ciclos de pagamento:

- **CAPTURE_NOW**: Pagamento imediato quando a subscrição é criada
- **RENEWABLE**: Ciclos recorrentes regulares baseados na frequência
- **ONE_TIME_CHARGE**: Pagamento único isolado


## Gerir Subscrições

### Obter Detalhes da Subscrição


```bash
GET /subscription/{id}
```

### Atualizar uma Subscrição


```bash
PATCH /subscription/{id}

{
  "value": 39.99,  // Update amount
  "frequency": "1Y"  // Change frequency
}
```

### Pausar uma Subscrição


```bash
PATCH /subscription/{id}

{
  "status": "inactive"
}
```

**Efeito**: Todos os ciclos pendentes são eliminados, sem pagamentos adicionais.

### Reativar uma Subscrição


```bash
PATCH /subscription/{id}

{
  "status": "active"
}
```

**Efeito**: Novos ciclos criados com base na configuração atual.

### Cancelar uma Subscrição


```bash
DELETE /subscription/{id}
```

## Lógica de Repetição

Configure tentativas automáticas para pagamentos falhados:


```json
{
  "retries": 3,  // Retry up to 3 times
  "retry_interval": "24H"  // Wait 24 hours between retries
}
```

**Como funciona**:

1. Tentativa de cobrança inicial
2. Se falhar, repete após intervalo
3. Continua até sucesso ou máximo de tentativas atingido
4. Aciona fallback se configurado


## Métodos de Pagamento Alternativos (Failover)

Ative o failover para fornecer opções de pagamento alternativas:


```json
{
  "method": "cc",  // Método principal
  "failover": true
}
```

**Como funciona**:

1. Tenta pagamento com método principal
2. Se falhar após todas as tentativas, um checkout de failover é criado
3. O checkout inclui todos os métodos de pagamento ativos na sua conta
4. Se o pagamento for bem-sucedido através do checkout, a subscrição continua
5. Se nenhum pagamento for efetuado, o ciclo é marcado como falhado


## Casos de Uso

### Subscrição SaaS

Licença de software mensal:


```json
{
  "frequency": "1M",
  "value": 49.99,
  "method": "cc",
  "start_time": "2024-01-01",
  "unlimited_payments": true,
  "retries": 3
}
```

### Adesão Anual

Taxa de adesão anual:


```json
{
  "frequency": "1Y",
  "value": 199.99,
  "method": "cc",
  "start_time": "2024-01-01",
  "unlimited_payments": true
}
```

### Plano de Instalação

Plano de pagamento de 12 meses:


```json
{
  "frequency": "1M",
  "value": 83.33,
  "method": "dd",
  "start_time": "2024-01-01",
  "max_captures": 12  // Total: €999.96
}
```

### Serviço Trimestral

Faturação trimestral:


```json
{
  "frequency": "3M",
  "value": 299.99,
  "method": "cc",
  "start_time": "2024-01-01",
  "unlimited_payments": true
}
```

## Webhooks

Receba notificações para eventos de subscrição:

- **subscription_created**: Enviado quando o utilizador insere os seus dados de cartão e a subscrição é criada
- **subscription_capture**: Enviado após todas as tentativas serem feitas para uma tentativa de pagamento (seja bem-sucedida ou falhada)


## Melhores Práticas

1. **Comunicação Clara**: Informe os clientes sobre os termos da subscrição antecipadamente
2. **Períodos de Carência**: Considere períodos de carência antes de cancelar por pagamentos falhados
3. **Cancelamento Fácil**: Torne simples para os clientes cancelarem
4. **Atualizar Métodos de Pagamento**: Permita que os clientes atualizem detalhes de pagamento
5. **Preços Transparentes**: Exiba claramente custo total e frequência de faturação
6. **Períodos de Teste**: Considere testes gratuitos antes da primeira cobrança
7. **Cobranças Prorratizadas**: Gerencie mudanças de plano no meio do ciclo com elegância


## Cenários Comuns

### Cenário 1: SaaS Mensal

Cliente subscreve software mensal, cobrado automaticamente no 1º de cada mês, continua até cancelado.

### Cenário 2: Adesão Anual

Cliente paga taxa de adesão anual, recebe lembrete 30 dias antes da renovação, pode cancelar ou atualizar método de pagamento.

### Cenário 3: Instalação de 12 Meses

Cliente compra produto de €1000, paga €83,33/mês durante 12 meses, subscrição termina automaticamente após pagamento final.

### Cenário 4: Serviço Trimestral

Serviço faturado a cada 3 meses, cliente recebe fatura 7 dias antes da cobrança, pagamento auto-processado.

## Próximos Passos

- [Referência da API de Subscrição](/openapi#tag/Subscription-Payment) - Documentação completa da API
- [Guia de Webhooks](/docs/guides/webhooks) - Gerencie eventos de subscrição
- [Checkout](/docs/products/checkout) - Aceite subscrições via Checkout
- [Guia de Tipos de Pagamento](/docs/guides/payment-types) - Saiba mais sobre pagamentos de subscrição