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

# Assinaturas

> Como funciona a cobrança recorrente na Ephra: o modelo de 3 camadas, o que você inicia e o que a plataforma gerencia por você.

Na Ephra, a **recorrência é gerenciada pela plataforma**. Você só **inicia** a assinatura com a 1ª cobrança no cartão — a partir daí a Ephra re-cobra o cartão automaticamente a cada ciclo. Você não armazena cartão nem agenda cobranças.

## O modelo de 3 camadas

<CardGroup cols={3}>
  <Card title="Produto" icon="box">
    Um produto marcado como assinatura no dashboard: tipo **digital** + cobrança **recorrente**.
  </Card>

  <Card title="Oferta / Plano" icon="tags">
    Define a **frequência** (mensal, anual…) e o **preço**. Gera um `offerSlug`.
  </Card>

  <Card title="Assinatura" icon="rotate">
    O `ProductSubscription`, criado **quando a 1ª cobrança é aprovada**.
  </Card>
</CardGroup>

## Pré-requisitos

<Steps>
  <Step title="Configure o produto de assinatura">
    No dashboard, crie um produto **digital + recorrente** com um plano (frequência + preço). Guarde o `productId` e o `offerSlug`.
  </Step>

  <Step title="Autentique-se">
    Troque sua API key por um token Bearer de curta duração. Veja [Autenticação](/guias/autenticacao).
  </Step>

  <Step title="Tokenize o cartão">
    Gere um `cardToken` (`ct_...`) em [Tokenizar cartão](/api-reference/cartao-token). Ele é de uso pontual e curta duração — tokenize imediatamente antes de iniciar a assinatura.
  </Step>
</Steps>

## O ciclo de vida

<Steps>
  <Step title="Você inicia a assinatura">
    Chame [`POST /v1/subscriptions`](/api-reference/assinaturas-criar) com `productId`, `offerSlug`, o `cardToken` e o `customer`. **Não envie `amountInCents`** — o valor vem do plano.
  </Step>

  <Step title="A 1ª cobrança define o resultado">
    Se aprovada, a assinatura nasce `active` e a resposta traz `data.subscription`. Se recusada, a assinatura **não** é criada — trate o retry ou peça um novo cartão (veja `data.transaction.refuseReason`).
  </Step>

  <Step title="A Ephra assume a recorrência">
    Um job diário re-cobra o cartão a cada ciclo. Em caso de falha há **retentativas automáticas (dunning)**; após **5 falhas** consecutivas a assinatura é cancelada e o acesso é revogado.
  </Step>
</Steps>

<Warning>
  Uma assinatura só existe se a 1ª cobrança for aprovada. Sempre confirme que `data.subscription` veio na resposta antes de liberar o acesso.
</Warning>

## Status da assinatura

| `status`    | Label     | Significado                                       |
| ----------- | --------- | ------------------------------------------------- |
| `active`    | Ativo     | Em dia, cobrando normalmente.                     |
| `overdue`   | Em atraso | Última cobrança falhou; em retentativa (dunning). |
| `cancelled` | Cancelado | Cancelada pelo produtor ou após 5 falhas.         |
| `completed` | Concluído | Atingiu o nº máximo de cobranças do plano.        |
| `failed`    | Falhou    | Reservado.                                        |

## Frequências do plano

`weekly` (Semanal), `monthly` (Mensal), `bimonthly` (Bimestral), `quarterly` (Trimestral), `semiannual` (Semestral), `annual` (Anual).

## Acompanhamento por webhook

Cada cobrança recorrente gera uma **nova transação**, que dispara os webhooks de transação que você já assina (`transaction_paid`, `transaction_refunded`). Use-os para acompanhar cada ciclo — não é preciso ficar consultando a API.

<Note>
  O cancelamento automático após 5 falhas dispara o evento [`product_canceled`](/webhooks/eventos/assinaturas) com `cancelReason: max_retries`.
</Note>

<Tip>
  Um cliente tem **uma** assinatura ativa por produto. Iniciar uma nova para o mesmo produto + cliente **substitui/reinicia** a existente.
</Tip>

## Rotas de assinatura

<CardGroup cols={2}>
  <Card title="Iniciar assinatura" icon="plus" href="/api-reference/assinaturas-criar">
    Faz a 1ª cobrança e cria a assinatura.
  </Card>

  <Card title="Listar assinaturas" icon="list" href="/api-reference/assinaturas-listar">
    Lista paginada com métricas (MRR, churn, LTV).
  </Card>

  <Card title="Consultar assinatura" icon="magnifying-glass" href="/api-reference/assinaturas-consultar">
    Detalhe, cliente e histórico de cobranças.
  </Card>

  <Card title="Cancelar assinatura" icon="ban" href="/api-reference/assinaturas-cancelar">
    Encerra a assinatura e revoga o acesso.
  </Card>
</CardGroup>