Extrato de uso

Esta página documenta o extrato de uso, a fatura com descritivos de um período. Onde o Consumo 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.

string

obrigatório

Início da janela, em RFC3339 (ex. 2026-08-01T00:00:00Z).

string

obrigatório

Fim da janela, em RFC3339 (ex. 2026-09-01T00:00:00Z).

string

Nome da conta. Obrigatório apenas quando você usa o token global. Com o TokenAccount, a conta já vem do próprio token.

curl "https://ryzeapi.cloud/api/account/billing/statement?from=2026-08-01T00:00:00Z&to=2026-09-01T00:00:00Z" \
  -H "token: $Token_Account"

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 }
});

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"}
)

200 OK

{
  "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

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.

Mostrar campos de cada item

string

Nome da instância no período.

string

O número de WhatsApp que esteve conectado à instância no período.

string

Início do período faturável dentro da janela.

string

Fim do período faturável dentro da janela.

integer

Dias faturáveis do item na janela.

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.

integer

Valor do item, em centavos, proporcional aos dias: unitPriceCents vezes days dividido pelos dias do período.

integer

Pico de instâncias simultâneas em cobrança na janela. É ele que define a faixa de preço unitário.

integer

A soma dos amountCents de todos os itens, em centavos. O uso do período.

integer

O crédito incluído no seu contrato para o período, em centavos. É o piso da fatura.

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.

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.

string

Início da janela consultada.

string

Fim da janela consultada.

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.

Histórico de conexões

A linha do tempo de quando cada número esteve conectado.

Como a cobrança funciona

Crédito, teste e o modelo comprometido em detalhe.

Primeiros passos

Cobrança

Auditoria

Referência

Extrato itemizado

Campos da resposta

Próximo

Histórico de conexões

Como a cobrança funciona

​Extrato itemizado

​Campos da resposta

​Próximo

Histórico de conexões

Como a cobrança funciona

Extrato itemizado

Campos da resposta

Próximo