Ciclo de vida

Todo contrato na Aira passa por um ciclo de vida com quatro estados. Cada transição tem implicações no faturamento e nos ciclos de cobrança.

Status de um contrato

Rascunho (Draft)

O contrato foi criado mas ainda não está ativo. Nenhum ciclo de cobrança é gerado, e eventos não são associados a ele. O que você pode fazer: editar qualquer campo, alterar planos, ajustar o escopo de uso, duplicar ou excluir o contrato.

Ativo (Active)

O contrato está em vigor. Ciclos de cobrança são criados automaticamente e eventos dentro do escopo são agregados para faturamento. O que você pode fazer: cancelar o contrato, editar campos limitados (reajuste, campos personalizados, escopo de uso, alocações, gateway de pagamento), migrar planos para nova versão.

Para ativar um contrato, ele precisa ter pelo menos um plano ativo vinculado.

Cancelado (Canceled)

O contrato foi encerrado antes da data de término prevista. O ciclo de cobrança atual é fechado, e faturas abertas são canceladas automaticamente. O que você pode fazer: consultar histórico de faturas e eventos. O contrato não pode ser reativado.

Completo (Completed)

O contrato atingiu sua data de término natural. O último ciclo é processado e a fatura final é gerada automaticamente. O que você pode fazer: consultar histórico completo. Para renovar, crie um novo contrato ou duplique o existente.

Transições permitidas

Rascunho → Ativo ou Cancelado
Ativo → Cancelado ou Completo
Cancelado e Completo são estados finais (sem retorno)

A transição de Rascunho para Ativo é irreversível. Certifique-se de que todas as configurações estejam corretas antes de ativar o contrato.

Histórico de status

Todas as mudanças de status são registradas com timestamp e identificação do usuário que realizou a ação. O histórico completo pode ser consultado na tela de detalhes do contrato, garantindo rastreabilidade para auditoria.

Gerenciar via API

O conjunto de campos que um contrato aceita depende do status, por isso a atualização tem um endpoint para cada situação. As requisições são autenticadas por chave de API (header X-API-KEY).

Método	Endpoint	Ação	Permissão
`PUT`	`/v1/contracts/{id}/draft`	Atualizar um contrato em rascunho	`contracts:write`
`PUT`	`/v1/contracts/{id}/active`	Atualizar um contrato ativo	`contracts:write`

Chamar o endpoint de rascunho em um contrato ativo, ou o inverso, resulta em 400. Contratos cancelados e completos são estados finais e não aceitam atualização.

Campos aceitos em cada status

Campo	Rascunho	Ativo
`endDate`	Sim	Sim
`rateAdjustmentIndex`	Sim	Sim
`customFields`	Sim	Sim
`taxRegimeId`	Sim	Sim
`includeNewSubsidiariesOnUsageScope`	Sim	Sim
`autoIssue`	Sim	Sim
`usageScopes`	Sim	Sim
`allocations`	Sim	Sim
`billingSettings`	Sim	Sim
`paymentGatewaySettings`	Sim	Sim
`startDate`	Sim	Não
`retroactiveDate`	Sim	Não
`invoiceAllocationStrategy`	Sim	Não
`billingSchedule`	Sim	Não
`legalEntityId`	Sim	Não

Comportamento dos campos omitidos

A requisição substitui a configuração do contrato em vez de aplicar um ajuste parcial, portanto envie o conjunto completo de campos a cada chamada. Campos ausentes do corpo se comportam assim:

usageScopes e allocations são obrigatórios e exigem ao menos um item
taxRegimeId e paymentGatewaySettings são limpos no contrato
billingSettings e autoIssue preservam o valor atual
Os vínculos de sincronização com ERP não fazem parte do corpo público e são sempre preservados

Exemplo: ajustar a franquia mínima de um contrato ativo

CONTRACT_ID="a1b2c3d4-0000-0000-0000-000000000000"

curl -X PUT "https://api.useaira.com/v1/contracts/${CONTRACT_ID}/active" \
  -H "X-API-KEY: sua_chave_api" \
  -H "Content-Type: application/json" \
  -d '{
    "endDate": null,
    "rateAdjustmentIndex": "ipca",
    "customFields": {},
    "includeNewSubsidiariesOnUsageScope": false,
    "usageScopes": [{ "customerId": "a1b2c3d4-0000-0000-0000-000000000000" }],
    "allocations": [{
      "paymentAccountId": "b2c3d4e5-0000-0000-0000-000000000000",
      "allocationPercentage": "100.000000"
    }],
    "billingSettings": {
      "invoiceMinimumAmount": 300000,
      "productId": "c3d4e5f6-0000-0000-0000-000000000000"
    },
    "paymentGatewaySettings": null
  }'

A resposta devolve o contrato completo, no mesmo formato do endpoint de consulta.

Definir uma data de término em um contrato ativo exige que ele já tenha ao menos uma fatura não cancelada, e a data precisa ser posterior à da última fatura emitida.

Próximos passos

Criar contratos — configure um novo contrato
Configuração de cobrança — defina ciclos e períodos
Faturas — veja como faturas são geradas a partir de contratos

​Status de um contrato

​Rascunho (Draft)

​Ativo (Active)

​Cancelado (Canceled)

​Completo (Completed)

​Transições permitidas

​Histórico de status

​Gerenciar via API

​Campos aceitos em cada status

​Comportamento dos campos omitidos

​Exemplo: ajustar a franquia mínima de um contrato ativo

​Próximos passos

Status de um contrato

Rascunho (Draft)

Ativo (Active)

Cancelado (Canceled)

Completo (Completed)

Transições permitidas

Histórico de status

Gerenciar via API

Campos aceitos em cada status

Comportamento dos campos omitidos

Exemplo: ajustar a franquia mínima de um contrato ativo

Próximos passos