> ## 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.

# Introdução

> Automatizando o processo de assinaturas

A **Malga** oferece um **Motor de Assinaturas** que automatiza todo o ciclo de vida de cobranças recorrentes — desde o agendamento e execução até as retentativas em caso de falha — com monitoramento centralizado via Dashboard e notificações via Webhooks.

## Benefícios

* **Automatização completa**
* **Monitoramento centralizado via Dashboard**
* **Webhooks para notificações de eventos**
* **Provedor-agnóstico + uso do Fluxo Inteligente**

## Ciclo de vida da assinatura

Assinaturas podem ser definidas com frequência semanal, mensal, trimestral, anual, bienal ou trienal. O dia de vencimento segue regras específicas:

```mermaid theme={null}
graph TD
  A[Criação da assinatura] --> B[Primeira cobrança]
  B --> C{Falha?}
  C -- Não --> D[Assinatura ativa]
  C -- Sim --> E[Retentativas automáticas]
  E --> F{Sucesso?}
  F -- Sim --> D
  F -- Não --> G[Status unpaid ou cancelamento]
  G --> H[Novas faturas ou encerramento]
```

### Frequências e regras

* **weekly**: sempre mesmo dia da semana de `startAt`
* **monthly**: mesmo dia do mês (ou próximo dia válido)
* **quarterly**: a cada 3 meses, idem ao mensal
* **yearly**: mesmo dia/ano (ou adaptação para anos bissextos)
* **biennial**: a cada 2 anos, mesma data do `startAt` (ou adaptação equivalente ao anual)
* **triennial**: a cada 3 anos, mesma data do `startAt` (ou adaptação equivalente ao anual)

### Estados das assinaturas

| Estado     | Descrição                                       |
| ---------- | ----------------------------------------------- |
| `created`  | Assinatura criada, aguardando primeira cobrança |
| `trialing` | Em período de trial                             |
| `active`   | Assinatura ativa com cobrança recorrente        |
| `paused`   | Temporariamente suspensa                        |
| `canceled` | Encerrada definitivamente                       |
| `unpaid`   | Inadimplente após falhas                        |
| `expired`  | Exauriu as faturas permitidas                   |

## Retentativas & estratégia

Fluxo padrão de retentativas (5 tentativas)

<Steps>
  <Step title="D+0">Tentativa inicial no dia da fatura</Step>
  <Step title="D+1">Primeira retentativa (1 dia depois)</Step>
  <Step title="D+4">Segunda retentativa (4 dias depois)</Step>
  <Step title="D+9">Terceira retentativa (9 dias depois)</Step>
  <Step title="D+16">Última retentativa (16 dias depois)</Step>
</Steps>

Você também pode personalizar a estratégia de retentativas através do campo `retryPolicy` nas [configurações](/documentations/more/recurrence/engine/client-settings).

### Erros irreversíveis

O campo `retryable` da transação determina se a assinatura deve seguir as retentativas completas ou falhar imediatamente. Isso se deve porque alguns erros são passíveis de multa caso insistirmos em cobrar.

Confira na [tabela erros](/documentations/type-tables/declined-code) quais são irreversíveis.

### Consequências da falha completa

Se todas as retentativas falharem:

* A fatura recebe status `failed`
  * **Comportamento padrão**: assinatura vai para `unpaid`
  * Se `cancelAfterAllRetries` estiver ativo: `canceled`
* Status `unpaid`: próximas faturas ainda serão processadas
* Status `canceled`: não haverá mais cobranças automáticas

## Integração via API

Você pode integrar o motor de recorrência via [API](/api-reference/subscriptions/criacao-de-uma-nova-assinatura).

<Card title="Comece a integração" href="/documentations/more/recurrence/engine/getting-started" cta="Iniciar" horizontal arrow>
  Siga o passo a passo para implementar o motor de recorrência na sua aplicação.
</Card>