Cobrança do projeto

Estas rotas mostram quanto um projeto consumiu: o uso apurado hora a hora (projetos com cobrança por hora) e os lançamentos de cobrança associados ao projeto. Para entender os modelos de pagamento, veja Pagamentos e cobrança.

Autenticação e permissões

As rotas aceitam uma API Key da organização (x-api-key: znf_... ou Authorization: Bearer znf_...) ou um token de usuário com x-organization-id. Ambas exigem project.billing.read em project:<project-id> (ou project:*). project.metrics.read não dá acesso a valores financeiros. owner tem acesso completo.

Rota	Limite
`GET /v1/project/:id/billing/hourly-usage`	50 por minuto
`GET /v1/project/:id/billing/ledger`	50 por minuto

Os valores monetários são números em centavos de BRL e podem ser fracionários (até 8 casas decimais). Divida por 100 para exibir em reais.

Parâmetros de consulta

Parâmetro	Tipo	Padrão	Descrição
`from`	string ISO 8601	—	Início do período (inclusivo)
`to`	string ISO 8601	—	Fim do período (exclusivo)
`page`	inteiro	`1`	Página, a partir de 1
`limit`	inteiro	`10`	Itens por página, de 1 a 50
`status`	string	—	Somente no ledger: `pending` ou `applied`

Valores fora desses formatos retornam 400. Projeto inexistente na organização retorna 404 com Project not found.

Uso por hora

GET /v1/project/:id/billing/hourly-usage?from=2026-10-01T00:00:00Z&to=2026-10-08T00:00:00Z

{
  "status": "success",
  "message": "get project hourly usage with success",
  "data": {
    "hours": [
      {
        "id": "6702a1b2c3d4e5f6a7b8c9d0",
        "hour_start": "2026-10-07T23:00:00.000Z",
        "hour_end": "2026-10-08T00:00:00.000Z",
        "currency": "brl",
        "compute_amount": 12.5,
        "storage_amount": 0.4,
        "total_amount": 12.9,
        "compute_instance_hours": 1,
        "storage_gb_hours": 10,
        "status": "charged",
        "calculated_at": "2026-10-08T00:05:00.000Z",
        "charged_at": "2026-10-08T00:10:00.000Z"
      }
    ],
    "summary": {
      "currency": "brl",
      "compute_amount": 12.5,
      "storage_amount": 0.4,
      "total_amount": 12.9
    },
    "pagination": { "page": 1, "limit": 10, "total": 1, "total_pages": 1 }
  }
}

Campo	Descrição
`hours[]`	Uma entrada por hora apurada, da mais recente para a mais antiga. O filtro de período usa `hour_start`
`compute_amount` / `storage_amount` / `total_amount`	Valor de capacidade, de armazenamento e total da hora
`compute_instance_hours`	Instâncias-hora consideradas na hora
`storage_gb_hours`	GB-hora de armazenamento considerados na hora
`status`	`pending` (apurado, ainda não cobrado) ou `charged` (cobrado)
`charged_at`	Momento da cobrança, quando já ocorreu
`summary`	Soma de todo o período filtrado, não apenas da página

Projetos com contrato mensal ou anual e Jobs agendados (cobrados por minuto) não têm uso por hora: a rota responde 200 com hours vazio, totais 0 e total: 0. O custo das execuções de um Job está em Jobs agendados.

Lançamentos de cobrança

GET /v1/project/:id/billing/ledger?status=pending

{
  "status": "success",
  "message": "get project billing ledger with success",
  "data": {
    "entries": [
      {
        "id": "6702a1b2c3d4e5f6a7b8c9d1",
        "category": "usage",
        "description": "Uso computado",
        "amount": 12.5,
        "currency": "brl",
        "status": "pending",
        "occurred_at": "2026-10-08T00:05:00.000Z"
      }
    ],
    "summary": {
      "currency": "brl",
      "adjustment_amount": 0,
      "storage_amount": 0,
      "usage_amount": 12.5,
      "total_amount": 12.5
    },
    "summary_by_currency": [
      {
        "currency": "brl",
        "adjustment_amount": 0,
        "storage_amount": 0,
        "usage_amount": 12.5,
        "total_amount": 12.5
      }
    ],
    "pagination": { "page": 1, "limit": 10, "total": 1, "total_pages": 1 }
  }
}

Campo	Descrição
`category`	`usage` (uso de capacidade ou de banco), `storage` (armazenamento) ou `adjustment` (ajuste de saldo)
`description`	Texto descritivo do lançamento
`status`	`pending` (aguardando aplicação) ou `applied` (já aplicado ao saldo)
`occurred_at`	Quando o lançamento foi registrado; o filtro de período usa este campo
`applied_at`	Quando o lançamento foi aplicado, se já foi
`summary`	Totais por categoria de todo o período filtrado. Ausente se houver mais de uma moeda; nesse caso, use `summary_by_currency`

Os lançamentos vêm do mais recente para o mais antigo.

Exemplo

curl "https://api.zenifra.com/v1/project/6650f1a2b3c4d5e6f7a8b9c0/billing/hourly-usage?page=1&limit=24" \
  -H "x-api-key: znf_..."

Próximos passos

Consulte preços vigentes nos catálogos de Criar, listar e remover projetos.
Veja custos de Jobs em Jobs agendados e de previews em Ambientes de preview.
Entenda os modelos de cobrança em Pagamentos e cobrança.