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

# Consumo

> Como o uso é medido e como consultar o resumo de cobrança da conta

Esta página explica **como o seu consumo é medido** e os endpoints para acompanhar o ciclo. A cobrança Enterprise é baseada em uso, então vale entender o que conta e como o total do ciclo é formado.

## O que é medido

A unidade de medida é o **dia de instância ativa**. Para cada instância em cobrança, a API conta os dias comprometidos no ciclo, e o total do ciclo é a soma desses dias de todas as suas instâncias.

* Uma instância ativa o ciclo inteiro conta o ciclo cheio.
* Uma instância que entra em cobrança no meio do ciclo compromete os dias dali até a renovação.
* Deletar uma instância não reduz os dias já comprometidos. Veja [Como a cobrança funciona](/pt/enterprise/how-billing-works).
* Uma instância ainda em teste não entra na conta enquanto estiver nesse estado.

## Resumo de cobrança da conta

**`GET /api/account/billing/summary`**

Devolve o resumo do ciclo vigente da conta. Autentique com o **TokenAccount** da conta, ou com o token global passando `?account=<nome-da-conta>`.

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://ryzeapi.cloud/api/account/billing/summary" \
    -H "token: $Token_Account"
  ```

  ```javascript JavaScript theme={null}
  await fetch("https://ryzeapi.cloud/api/account/billing/summary", {
    headers: { "token": process.env.Token_Account }
  });
  ```
</CodeGroup>

```json 200 OK theme={null}
{
  "enterprise": true,
  "baseCents": 50000,
  "committedCents": 42000,
  "projectedChargeCents": 50000,
  "billableInstanceDays": 210,
  "billableCount": 8,
  "cycleStart": "2026-08-01T00:00:00Z",
  "cycleEnd": "2026-09-01T00:00:00Z",
  "nextChargeAt": "2026-09-01T00:00:00Z"
}
```

<ResponseField name="enterprise" type="boolean">
  `true` quando a conta é Enterprise. Se vier `false`, os demais campos não aparecem.
</ResponseField>

<ResponseField name="baseCents" type="integer">
  O crédito mensal (base) do seu contrato, em centavos. É o piso da fatura.
</ResponseField>

<ResponseField name="committedCents" type="integer">
  O valor de uso já comprometido no ciclo, em centavos, proporcional aos dias de instância.
</ResponseField>

<ResponseField name="projectedChargeCents" type="integer">
  A projeção da cobrança do ciclo, em centavos: o maior entre `baseCents` e `committedCents`.
</ResponseField>

<ResponseField name="billableInstanceDays" type="integer">
  A soma de dias de instância em cobrança no ciclo.
</ResponseField>

<ResponseField name="billableCount" type="integer">
  O pico de instâncias simultâneas em cobrança no ciclo.
</ResponseField>

<ResponseField name="cycleStart" type="string">
  Início do ciclo vigente.
</ResponseField>

<ResponseField name="cycleEnd" type="string">
  Fim do ciclo vigente.
</ResponseField>

<ResponseField name="nextChargeAt" type="string">
  Quando a próxima cobrança acontece (o fim do ciclo).
</ResponseField>

<Note>
  Antes da primeira renovação, a janela do ciclo pode ainda não estar preenchida, e o resumo mostra a `base` como piso projetado.
</Note>

## Cobrança por instância na listagem

**`GET /api/instance/list`** já traz, para cada instância, um bloco `billing` com o estado de cobrança. Ele aparece apenas em chamadas com token de conta ou global, nunca com token de instância.

```json theme={null}
{
  "billing": {
    "billingMode": "trial",
    "trialEndsAt": "2026-08-25T12:00:00Z",
    "billableSince": null,
    "trialDaysLeft": 5,
    "willBeCharged": false
  }
}
```

<ResponseField name="billingMode" type="string">
  `trial` ou `billable`.
</ResponseField>

<ResponseField name="trialEndsAt" type="string | null">
  Quando o teste termina. `null` quando a instância já está em cobrança.
</ResponseField>

<ResponseField name="billableSince" type="string | null">
  Desde quando a instância é cobrada. `null` enquanto em teste.
</ResponseField>

<ResponseField name="trialDaysLeft" type="integer">
  Dias que faltam do teste, arredondado para cima. `0` fora do teste.
</ResponseField>

<ResponseField name="willBeCharged" type="boolean">
  `true` quando a instância já está em cobrança.
</ResponseField>

## Acompanhando em tempo real

Para reagir a cada virada de estado, use os [webhooks Enterprise](/pt/enterprise/webhooks). Eles avisam quando um teste começa, quando está prestes a acabar e quando uma instância vira cobrança, o que permite você espelhar esse estado no seu próprio painel.

## Próximo

<CardGroup cols={2}>
  <Card title="Extrato de uso" icon="receipt" href="/pt/enterprise/statement">
    A fatura com descritivos do período, instância a instância.
  </Card>

  <Card title="Histórico de conexões" icon="link" href="/pt/enterprise/connections">
    A linha do tempo de quando cada número esteve conectado.
  </Card>

  <Card title="Como a cobrança funciona" icon="calculator" href="/pt/enterprise/how-billing-works">
    Crédito, teste e o modelo comprometido em detalhe.
  </Card>

  <Card title="Webhooks Enterprise" icon="webhook" href="/pt/enterprise/webhooks">
    Acompanhe as viradas de estado em tempo real.
  </Card>
</CardGroup>