> ## Documentation Index
> Fetch the complete documentation index at: https://docs.malga.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Gerenciando suas assinaturas

> Gerencie suas assinaturas recorrentes com o motor de recorrência

O motor de recorrência da Malga oferece uma API para você gerenciar suas assinaturas recorrentes de forma programática.

## Ciclo de Vida das Assinaturas

O motor de recorrência gerencia automaticamente o ciclo de vida das suas assinaturas, desde a criação até a expiração. Entender como funciona esse fluxo é essencial para implementar corretamente as ações de gerenciamento.

### Estados das Assinaturas

* **created**: Assinatura criada, aguardando primeira cobrança
* **trialing**: Assinatura em período de trial gratuito
* **active**: Assinatura ativa com cobranças sendo processadas
* **paused**: Assinatura pausada temporariamente
* **canceled**: Assinatura cancelada manualmente
* **unpaid**: Assinatura inadimplente (após falha de todas as retentativas, exceto se `cancelAfterAllRetries` estiver habilitado)
* **expired**: Assinatura expirada (atingiu o limite de faturas configurado)

### Sistema de Trials

O motor de recorrência suporta períodos de trial gratuito para assinaturas. Durante o trial, a assinatura fica no status `trialing` e não gera faturas de cobrança.

#### Características dos Trials

* **Período gratuito**: Cliente pode usar o serviço sem ser cobrado
* **Status especial**: Assinatura fica com status `trialing` durante o período
* **Sem cobrança**: Não são geradas faturas de cobrança durante o trial
* **Transição automática**: Ao expirar, transiciona automaticamente para `created`

#### Estados com Trial

```mermaid theme={null}
flowchart TD
    A[trialing] -->|Trial expira| B[created]
    B -->|Primeira cobrança| C[active]
    A -->|Apenas pode ser cancelada| D[canceled]
    B -->|Pode ser pausada ou cancelada| E[canceled]
    C -->|Pode ser pausada ou cancelada| F[canceled]
```

#### Regras para Trials

* ✅ **Permitido**: Cancelar a assinatura durante o trial
* ❌ **Não permitido**: Pausar a assinatura durante o trial
* ❌ **Não permitido**: Editar o campo `trialEnd` após criação
* ⚠️ **Automático**: Transição para `created` quando o trial expira

### Fluxo de Processamento de Cobranças

```mermaid theme={null}
flowchart TD
    A[Recorrência iniciou o processo de cobrança] --> B{Status da recorrência é:<br/>created, active ou unpaid?}
    B -->|NÃO| Z[FIM]
    B -->|SIM| C[Processar cobrança]
    C --> D{Cobrança foi autorizada?}
    D -->|SIM| E{Última fatura da recorrência?}
    E -->|SIM| F[Status da recorrência: expired]
    E -->|NÃO| G[Status da recorrência: active]
    D -->|NÃO| H{É a última tentativa?}
    H -->|NÃO| C
    H -->|SIM| I{cancelAfterAllRetries<br/>habilitado?}
    I -->|SIM| J[Status da recorrência: canceled]
    I -->|NÃO| K[Status da recorrência: unpaid]
```

### Regras de Retentativas

O motor de recorrência segue regras específicas para retentativas baseadas no tipo de assinatura:

#### Estratégia Unificada para Todos os Intervalos (5 tentativas)

**Para weekly, monthly, quarterly, yearly, biennial e triennial:**

* **D+0**: Tentativa inicial (no vencimento da fatura)
* **D+1**: 1ª retentativa
* **D+4**: 2ª retentativa
* **D+9**: 3ª retentativa
* **D+16**: 4ª retentativa (última tentativa)

Se todas as retentativas falharem, a fatura fica **failed**, e a assinatura ficará **unpaid**. A assinatura permanecerá neste estado e continuará tentando cobrar nas próximas faturas até que seja cancelada manualmente.

### Status das Faturas

Cada fatura de uma assinatura possui um status que indica seu estado atual no processo de cobrança:

* **scheduled**: Fatura agendada para processamento futuro
* **pending**: Fatura aguardando processamento de cobrança
* **authorized**: Fatura processada com sucesso (estado final - não pode ser alterado)
* **failed**: Fatura que falhou após todas as retentativas (estado final - não pode ser alterado)
* **retrying**: Fatura em processo de retentativa após falha
* **canceled**: Fatura "não faturada", marcada quando a assinatura é pausada ou cancelada (estado final - não será processada)

**Estados finais**: Faturas com status `authorized`, `failed` ou `canceled` são estados finais e não podem ser alteradas ou processadas novamente pelo scheduler de cobranças. Faturas `authorized` e `failed` preservam o histórico de auditoria de cobranças já processadas ou falhas finais, enquanto `canceled` preserva o histórico de faturas que não foram faturadas devido a pausa ou cancelamento da assinatura.

### Status do PaymentHistory(Cobrança)

Cada cobrança registrada no `paymentHistory` de uma fatura possui um status que indica o resultado da tentativa individual:

* **pending**: Status inicial quando uma cobrança é criada
* **authorized**: Cobrança bem-sucedida, atualizada quando o pagamento é autorizado com sucesso
* **failed**: Cobrança que falhou, atualizada quando o pagamento não foi autorizado

<Info>
  **Importante**: O `PaymentHistory` representa tentativas individuais de pagamento e possui apenas 3 status possíveis (`pending`, `authorized`, `failed`).
</Info>

### Ações Disponíveis por Estado

| Estado       | Pausar | Retomar | Cancelar |
| ------------ | ------ | ------- | -------- |
| **created**  | ❌      | ❌       | ✅        |
| **trialing** | ❌      | ❌       | ✅        |
| **active**   | ✅      | ❌       | ✅        |
| **paused**   | ❌      | ✅       | ✅        |
| **canceled** | ❌      | ❌       | ❌        |
| **unpaid**   | ❌      | ❌       | ✅        |
| **expired**  | ❌      | ❌       | ❌        |

### Transições de Estado

```mermaid theme={null}
stateDiagram-v2
    [*] --> created
    [*] --> trialing : com trial
    
    trialing --> created : trial expirado
    trialing --> canceled : cancelamento manual
    
    created --> active : primeira cobrança aprovada
    created --> canceled : cancelamento manual
    created --> FailureDecision : falha após retentativas
    
    active --> paused : pausar
    active --> expired : última fatura completada
    active --> canceled : cancelamento manual
    active --> FailureDecision : falha após retentativas
    
    paused --> active : retomar
    paused --> canceled : cancelamento manual
    
    FailureDecision --> unpaid : cancelAfterAllRetries = false
    FailureDecision --> canceled : cancelAfterAllRetries = true
    
    unpaid --> active : cobrança aprovada
    unpaid --> canceled : cancelamento manual
    
    expired --> [*]
    canceled --> [*]
    
    state FailureDecision {
        [*] --> [*] : Decisão baseada em configuração
    }
```

### Lógica de Falha após Retentativas

O estado `FailureDecision` representa o ponto de decisão quando todas as tentativas de cobrança falharam:

* **`cancelAfterAllRetries = false`** (padrão): A assinatura vai para status `unpaid` e continuará tentando cobrar nas próximas faturas
* **`cancelAfterAllRetries = true`**: A assinatura é automaticamente cancelada e não processará mais cobranças

Esta configuração é definida no [Client Settings](/documentations/more/recurrence/engine/client-settings) e se aplica a todas as assinaturas do cliente.

## Operações de Gerenciamento

<CardGroup cols={2}>
  <Card title="Atualizar uma assinatura" icon="pen" href="/api-reference/subscriptions/atualizar-assinatura/">
    Atualize uma assinatura recorrente com os métodos de pagamento disponíveis na Malga.

    Ao alterar `cycles`, o novo valor **não pode** ser menor do que a quantidade de faturas já cobradas.
  </Card>

  <Card title="Pausar uma assinatura" icon="pause" href="/api-reference/subscriptions/pausar-assinatura/">
    Pause uma assinatura recorrente.
  </Card>
</CardGroup>

<CardGroup cols={2}>
  <Card title="Políticas de Retentativa" icon="gear" href="/documentations/more/recurrence/engine/custom-retry-policies/">
    Configure regras de retentativa personalizadas para suas assinaturas.
  </Card>

  <Card title="Configurar Webhooks" icon="webhook" href="/documentations/more/recurrence/engine/webhooks/">
    Configure notificações em tempo real sobre mudanças de status.
  </Card>
</CardGroup>

<CardGroup cols={2}>
  <Card title="Retomar Assinatura" icon="play" href="/api-reference/subscriptions/reativar-assinatura/">
    Retomar uma assinatura recorrente.
  </Card>

  <Card title="Cancelar Assinatura" icon="xmark" href="/api-reference/subscriptions/cancelar-assinatura/">
    Cancelar uma assinatura recorrente.
  </Card>
</CardGroup>

<CardGroup cols={1}>
  <Card title="Cancelamento Agendado" icon="clock" href="/documentations/more/recurrence/engine/scheduled-cancellation">
    Agende o cancelamento da assinatura para o final do período atual, garantindo que o cliente tenha acesso completo até o fim do período já pago.
  </Card>
</CardGroup>

<Info>
  **Pausar** e **cancelar** não interrompem uma fatura **já iniciada**, somente faturas **futuras** são afetadas.

  Ao pausar ou cancelar uma assinatura, faturas pendentes (scheduled, pending, retrying) são marcadas como `canceled` (não faturado) para preservar o histórico de auditoria. Faturas já finalizadas (authorized, failed) não são alteradas.
</Info>