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

# Ciclo de vida e estados

> Como uma assinatura evolui, o que cada estado significa para o acesso do seu cliente, e quando a cobrança se repete.

Antes de integrar, entenda o mapa. Uma assinatura na Autorizou nasce, cobra sozinha a cada ciclo, tenta de novo quando falha, e termina de um jeito previsível. O campo que você mais vai ler é o **`state`**, e o companheiro dele, **`has_access`**.

## Os dois campos que importam

<ResponseField name="state" type="string">
  O momento da assinatura. É o que você usa para decidir o que mostrar ao seu cliente.
</ResponseField>

<ResponseField name="has_access" type="boolean">
  **Libere ou bloqueie o seu serviço por aqui.** É `true` quando o cliente deve ter acesso, `false` quando não. Você não precisa recalcular a regra a partir do `state`; nós já resolvemos.
</ResponseField>

<Info>
  Regra de ouro: **entregue o seu produto quando `has_access` for `true`.** Nunca amarre a entrega a um `state` específico, porque a lista pode crescer.
</Info>

## A tabela de estados

| `state`     | `has_access` | O que significa                                   | O que fazer                                |
| ----------- | ------------ | ------------------------------------------------- | ------------------------------------------ |
| `trial`     | `true`       | Período grátis, ainda sem cobrança                | Liberar o serviço                          |
| `pending`   | `false`      | Aquisição aguardando confirmação (pix/boleto)     | Aguardar o webhook de aprovação            |
| `active`    | `true`       | Cobrando em dia                                   | Liberar o serviço                          |
| `past_due`  | `true`       | Uma cobrança falhou, em janela de retentativa     | Manter acesso; avisar o cliente é opcional |
| `unpaid`    | `false`      | Retentativas esgotadas, ainda recuperável         | Bloquear; pagar reativa                    |
| `canceled`  | `true`       | Parada, mas o período pago ainda vale             | Manter acesso até `next_charge_at`         |
| `ended`     | `false`      | Encerrada (estorno, chargeback ou fim do período) | Bloquear (terminal)                        |
| `completed` | `false`      | Cumpriu todos os ciclos combinados                | Bloquear (terminal)                        |

<Tip>
  `canceled` com `has_access: true` **não é contradição**. O cliente cancelou, mas já pagou o mês corrente. Ele mantém acesso até o fim do período (`next_charge_at`) e pode até reativar nesse meio tempo.
</Tip>

## Fluxo, do nascimento ao fim

```mermaid theme={null}
stateDiagram-v2
  [*] --> trial: com periodo de teste
  [*] --> pending: pix/boleto aguardando
  [*] --> active: cartao aprovado
  trial --> active: pagou
  pending --> active: confirmou
  active --> active: renovou (avanca ciclo)
  active --> past_due: cobranca falhou
  past_due --> active: recuperou
  past_due --> unpaid: carencia esgotou
  unpaid --> active: pagou
  active --> canceled: cancelou
  past_due --> canceled: dunning desistiu
  unpaid --> canceled: dunning desistiu
  canceled --> active: reativou
  canceled --> ended: fim do periodo pago
  active --> completed: ultimo ciclo
  active --> ended: estorno / chargeback
```

## Quando a cobrança se repete

A renovação é automática. Você **não** dispara a cobrança de cada ciclo; a plataforma faz sozinha na data `next_charge_at`. Quando falha, a régua de retentativas depende do método:

| Método            | Retentativas (dias após vencer) | Vira `unpaid` | Cancela |
| ----------------- | ------------------------------- | ------------- | ------- |
| Cartão de crédito | 2, 4, 6, 8, 10, 15, 20, 25      | D+4           | D+27    |
| Boleto / Pix      | D+7                             | D+7           | D+10    |

O `next_charge_amount` de cada ciclo segue a **régua de preços congelada na assinatura** no momento em que ela nasceu. Editar a oferta depois nunca reprecifica quem já assina.

## Eventos (webhooks)

Configure `notification_url` na criação para receber o estado em tempo real. Todo evento traz `state`, `has_access`, `cycle`, `next_charge_at` e um `portal_url` pronto do assinante.

| Evento                                          | Quando                                        |
| ----------------------------------------------- | --------------------------------------------- |
| `subscription.activated`                        | virou `active`                                |
| `subscription.charge_succeeded`                 | um ciclo foi cobrado com sucesso              |
| `subscription.charge_failed`                    | uma cobrança falhou (com `code` e `category`) |
| `subscription.past_due`                         | entrou em atraso                              |
| `subscription.unpaid`                           | carência esgotou                              |
| `subscription.canceled`                         | foi cancelada                                 |
| `subscription.ended` / `subscription.completed` | terminou                                      |
| `subscription.plan_changed`                     | trocou de oferta (upgrade/downgrade)          |

<Warning>
  Trate o webhook como **confirmação**, não como fonte da verdade. Se precisar do estado atual com certeza, consulte [`GET /subscriptions/{id}`](/api-reference/subscriptions/get-subscription).
</Warning>

## O portal do assinante

Toda assinatura tem um portal onde o seu cliente **troca o cartão, cancela e reativa sozinho**. Um `portal_url` pronto acompanha **todo webhook** de assinatura; e você gera um sob demanda em [`POST /subscriptions/{id}/portal-link`](/api-reference/subscriptions/portal-link). Menos suporte para você, mais autonomia para o cliente.