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
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.
Status do contrato
Quando um plano original é editado, os contratos que usam versões anteriores desse plano recebem um status na listagem de contratos:Cenários práticos
- Contrato desatualizado
- Contrato sobrescrito
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
- 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
Ciclo de vida de uma versão
1
Plano publicado (v1)
A primeira versão é criada e pode ser vinculada a contratos.
2
Contrato usa v1
Ao criar o contrato, uma instância da v1 é capturada. O contrato agora possui sua cópia independente.
3
Plano editado (v2)
A equipe altera preços ou métricas do plano original. Uma nova versão (v2) é criada.
4
Contratos antigos permanecem na v1
Contratos existentes continuam na v1 com status Desatualizado. Novos contratos usam a v2.
5
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.
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.Gerenciar instâncias via API
Cada plano vinculado a um contrato é uma instância de plano — é ela que a API pública expõe. As requisições são autenticadas por chave de API (headerX-API-KEY).
Criar uma instância
Corpo doPOST /v1/plan-instances/:
Um contrato tem no máximo uma instância ativa de cada plano.
A resposta de instância
Os três endpoints devolvem o mesmo objeto:
Dentro de
activePlanInstanceVersion: id, planInstanceId, planVersionId, versionNumber (sequencial a partir de 1), isActive (apenas uma versão é ativa por vez), planInstanceVersionReason (mesmos valores acima), metadata (detalhes de criação da versão; anulável) e planCharges.
Cobranças por categoria
Cada cobrança emplanCharges segue o formato da sua categoria — category é o discriminador. Os campos comuns às três categorias são id, position (ordem de exibição), itemId (item de catálogo faturado), productId, name (nome exibido nas faturas) e isCustomNameEnabled (quando false, o nome segue o nome do recurso ou do item de catálogo).
Os campos
resourceId, currencyUnit e tiers pertencem apenas às cobranças usage_based — as respostas de cobranças fixed e minimum_commitment contêm somente os campos comuns, pricingModel e pricing. Em usage_based, resourceId é sempre preenchido; currencyUnit traz a unidade de moeda dos créditos que a cobrança consome (null quando a cobrança não consome créditos); e tiers lista as faixas (vazia nos modelos sem escada).
Cobrança fixed na resposta:
usage_based com escada de faixas:
Sobrescrever cobranças
O corpo doPUT /v1/plan-instances/{id} é { "planCharges": [ ... ] }. A lista substitui integralmente as cobranças da instância e cria uma nova versão — é o fluxo de personalização por contrato descrito acima. Na escrita, cada categoria aceita:
Em
fixed e minimum_commitment, identifique a cobrança pelo item de catálogo (itemId) — essas categorias não levam resourceId, currencyUnitCode nem tiers. Em usage_based, identifique pelo recurso (resourceId) — o item de catálogo é derivado dele, então a categoria não leva itemId.
pricing seguem os exemplos acima.
Próximos passos
- Criar planos — configure planos com métricas e precificação
- Modelos de precificação — os modelos de preço e faixas, no Dashboard e na API
- Criar contratos — vincule planos a clientes e entenda como instâncias funcionam