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

# Versionamento

> Planos são versionados por contrato. Cada contrato mantém sua própria versão do plano, garantindo zero efeitos colaterais.

> Planos evoluem com o tempo — preços mudam, métricas são ajustadas, faixas são redefinidas. O versionamento garante que essas mudanças não alterem retroativamente contratos que já estão ativos.

## Como funciona

Quando um plano é adicionado a um contrato, a Aira cria uma **instância independente** daquele plano, capturando o estado atual (preços, métricas, faixas). A partir desse momento, o contrato possui sua própria cópia do plano:

* **Editar o plano original** não afeta contratos existentes — cada um mantém a versão que foi contratada
* **Personalizar o plano de um contrato** não afeta outros contratos nem o plano original
* **Múltiplos contratos** podem usar versões diferentes do mesmo plano simultaneamente

<Info>
  Esse modelo elimina efeitos colaterais: atualizar a tabela de preços do plano "Starter" para novos clientes não altera o valor cobrado de quem já contratou.
</Info>

No Dashboard, você pode visualizar todas as versões de um plano e quais contratos utilizam cada uma:

<Frame>
  <img src="https://mintcdn.com/aira-e93056c6/D0DI4R_7r28AeG1L/static/plan-versions.png?fit=max&auto=format&n=D0DI4R_7r28AeG1L&q=85&s=10e5737d1c7c5358cb92e09ba09b49b1" alt="Aira — Versões de um plano" width="4066" height="2392" data-path="static/plan-versions.png" />
</Frame>

<br />

## Status do contrato

Quando um plano original é editado, os **contratos** que usam versões anteriores desse plano recebem um status na listagem de contratos:

| Status do contrato | Significado                                                     | Causa                                                       |
| ------------------ | --------------------------------------------------------------- | ----------------------------------------------------------- |
| **Desatualizado**  | O contrato usa versões antigas de um ou mais planos             | Plano original foi editado após a criação do contrato       |
| **Sobrescrito**    | O contrato possui planos personalizados exclusivamente para ele | Equipe alterou preços/métricas para este cliente específico |

<br />

<h2 id="cenarios-praticos">
  Cenários práticos
</h2>

<Tabs>
  <Tab title="Contrato desatualizado">
    **Situação:** a empresa atualiza o plano "Starter" de `R$ 0,01` para `R$ 0,008` por requisição.

    **O que acontece:**

    * Contratos novos criados a partir de agora usam a versão atualizada (`R$ 0,008`)
    * Contratos antigos continuam com `R$ 0,01` — o **contrato** recebe o status **Desatualizado**
    * Nenhuma ação automática é tomada

    **O que você pode fazer:**

    * Manter o contrato como está (o cliente continua pagando `R$ 0,01`)
    * Selecionar os contratos desatualizados na listagem e clicar em **"Atualizar para última versão"** — a atualização pode ser feita em lote para múltiplos contratos de uma vez

    <Tip>
      Contratos desatualizados podem ser filtrados diretamente na listagem de contratos no Dashboard.
    </Tip>
  </Tab>

  <Tab title="Contrato sobrescrito">
    **Situação:** a equipe comercial negociou condições especiais com um cliente e precisa alterar os preços do plano apenas para ele.

    **O que acontece:**

    * A equipe edita o plano diretamente dentro do contrato do cliente
    * Uma nova versão exclusiva é criada para este contrato — o **contrato** recebe o status **Sobrescrito**
    * O plano original e os contratos de outros clientes não são afetados

    **O que você pode fazer:**

    * Manter a versão personalizada
    * Reverter para o plano original, se necessário
  </Tab>
</Tabs>

<br />

<h2 id="ciclo-de-vida-de-uma-versao">
  Ciclo de vida de uma versão
</h2>

<Steps>
  <Step title="Plano publicado (v1)">
    A primeira versão é criada e pode ser vinculada a contratos.
  </Step>

  <Step title="Contrato usa v1">
    Ao criar o contrato, uma instância da v1 é capturada. O contrato agora possui sua cópia independente.
  </Step>

  <Step title="Plano editado (v2)">
    A equipe altera preços ou métricas do plano original. Uma nova versão (v2) é criada.
  </Step>

  <Step title="Contratos antigos permanecem na v1">
    Contratos existentes continuam na v1 com status **Desatualizado**. Novos contratos usam a v2.
  </Step>

  <Step title="Personalização (opcional)">
    Se um plano é editado diretamente dentro de um contrato, ele recebe o status **Sobrescrito** e passa a ter uma versão exclusiva.
  </Step>
</Steps>

<br />

## Deletar planos

Um plano só pode ser deletado se **não estiver associado a nenhum contrato ativo**. Planos com contratos vinculados devem ser desativados ou ter seus contratos encerrados primeiro.

<br />

<h2 id="proximos-passos">
  Próximos passos
</h2>

* [Criar planos](/planos/criar-planos) — configure planos com métricas e precificação
* [Criar contratos](/contratos/criar-contratos) — vincule planos a clientes e entenda como instâncias funcionam