> ## 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.

# Extrato de uso

> A fatura com descritivos do período: cada instância, o número, os dias e os valores

Esta página documenta o **extrato de uso**, a fatura com descritivos de um período. Onde o [Consumo](/pt/enterprise/usage) mostra o total do ciclo em andamento, o extrato abre linha a linha: cada instância que teve período faturável na janela, o número que esteve conectado, quantos dias contaram, o preço unitário e o valor, mais os totais de uso, crédito e cobrança.

## Extrato itemizado

**`GET /api/account/billing/statement?from=<rfc3339>&to=<rfc3339>`**

Devolve o extrato de uma janela. Autentique com o **TokenAccount** da conta, ou com o token global passando `?account=<nome-da-conta>`. Os parâmetros `from` e `to` são obrigatórios, em formato RFC3339.

<ParamField query="from" type="string" required>
  Início da janela, em RFC3339 (ex. `2026-08-01T00:00:00Z`).
</ParamField>

<ParamField query="to" type="string" required>
  Fim da janela, em RFC3339 (ex. `2026-09-01T00:00:00Z`).
</ParamField>

<ParamField query="account" type="string">
  Nome da conta. Obrigatório apenas quando você usa o token global. Com o TokenAccount, a conta já vem do próprio token.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://ryzeapi.cloud/api/account/billing/statement?from=2026-08-01T00:00:00Z&to=2026-09-01T00:00:00Z" \
    -H "token: $Token_Account"
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    from: "2026-08-01T00:00:00Z",
    to: "2026-09-01T00:00:00Z"
  });

  await fetch(`https://ryzeapi.cloud/api/account/billing/statement?${params}`, {
    headers: { "token": process.env.Token_Account }
  });
  ```

  ```python Python theme={null}
  import os, requests

  requests.get(
      "https://ryzeapi.cloud/api/account/billing/statement",
      headers={"token": os.environ["Token_Account"]},
      params={"from": "2026-08-01T00:00:00Z", "to": "2026-09-01T00:00:00Z"}
  )
  ```
</CodeGroup>

```json 200 OK theme={null}
{
  "items": [
    {
      "instanceName": "cliente-acme",
      "numberJid": "5511999998888@s.whatsapp.net",
      "billableFrom": "2026-08-01T00:00:00Z",
      "billableTo": "2026-09-01T00:00:00Z",
      "days": 31,
      "unitPriceCents": 5000,
      "amountCents": 5000
    },
    {
      "instanceName": "cliente-beta",
      "numberJid": "5511988887777@s.whatsapp.net",
      "billableFrom": "2026-08-15T00:00:00Z",
      "billableTo": "2026-09-01T00:00:00Z",
      "days": 17,
      "unitPriceCents": 5000,
      "amountCents": 2741
    }
  ],
  "peakInstances": 2,
  "usageCents": 7741,
  "creditCents": 50000,
  "overageCents": 0,
  "totalChargedCents": 50000,
  "cycleStart": "2026-08-01T00:00:00Z",
  "cycleEnd": "2026-09-01T00:00:00Z"
}
```

## Campos da resposta

<ResponseField name="items" type="array">
  Os descritivos do período, uma linha por instância que teve período faturável na janela. Uma instância deletada no meio do período continua aparecendo, com o nome e o número que ela tinha, pois o registro sobrevive à deleção. Veja [Como a cobrança funciona](/pt/enterprise/how-billing-works).

  <Expandable title="campos de cada item">
    <ResponseField name="instanceName" type="string">
      Nome da instância no período.
    </ResponseField>

    <ResponseField name="numberJid" type="string">
      O número de WhatsApp que esteve conectado à instância no período.
    </ResponseField>

    <ResponseField name="billableFrom" type="string">
      Início do período faturável dentro da janela.
    </ResponseField>

    <ResponseField name="billableTo" type="string">
      Fim do período faturável dentro da janela.
    </ResponseField>

    <ResponseField name="days" type="integer">
      Dias faturáveis do item na janela.
    </ResponseField>

    <ResponseField name="unitPriceCents" type="integer">
      Preço unitário mensal aplicado, em centavos. Definido pela faixa de volume do seu contrato no pico de instâncias do período.
    </ResponseField>

    <ResponseField name="amountCents" type="integer">
      Valor do item, em centavos, proporcional aos dias: `unitPriceCents` vezes `days` dividido pelos dias do período.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="peakInstances" type="integer">
  Pico de instâncias simultâneas em cobrança na janela. É ele que define a faixa de preço unitário.
</ResponseField>

<ResponseField name="usageCents" type="integer">
  A soma dos `amountCents` de todos os itens, em centavos. O uso do período.
</ResponseField>

<ResponseField name="creditCents" type="integer">
  O crédito incluído no seu contrato para o período, em centavos. É o piso da fatura.
</ResponseField>

<ResponseField name="overageCents" type="integer">
  Quanto o uso passou do crédito, em centavos: o maior entre `0` e `usageCents` menos `creditCents`. Fica `0` quando o uso cabe no crédito.
</ResponseField>

<ResponseField name="totalChargedCents" type="integer">
  O total cobrado no período, em centavos: o maior entre `creditCents` e `usageCents`. Ou seja, você nunca paga abaixo do crédito, e paga o uso quando ele ultrapassa o crédito.
</ResponseField>

<ResponseField name="cycleStart" type="string">
  Início da janela consultada.
</ResponseField>

<ResponseField name="cycleEnd" type="string">
  Fim da janela consultada.
</ResponseField>

<Note>
  Precisa de um documento pronto para enviar ao seu cliente? No painel, em **`/settings`**, aba **Faturas e uso**, você baixa o extrato do período formatado em PDF, e também as suas faturas em PDF.
</Note>

## Próximo

<CardGroup cols={2}>
  <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>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.