Consumo do Ciclo Atual

Enquanto o Histórico de Consumo lista requisição por requisição, o GET /billing/consumption devolve o número consolidado do ciclo vigente: quanto a company já consumiu, qual é o teto efetivo e quanto ainda resta.

🤖 Endpoint: GET https://requests.production.judit.io/billing/consumption. A resposta é síncrona (HTTP 200) e traz consumption, max_consumption, remaining e as datas de abertura e fechamento do ciclo.

Quando usar

Dashboards internos

Exiba o consumo do ciclo e o saldo restante no seu próprio painel, sem depender do painel da Judit.

Alertas de uso

Dispare um aviso para o time quando o consumo cruzar 70%, 80% ou 90% do teto contratado.

Pré-flight de lotes

Antes de disparar um volume grande de consultas, confira se remaining comporta a operação.

Fechamento por ciclo

Use cycle_started_at e cycle_ended_at para alinhar seus relatórios à janela real de faturamento.

Passo 1: Fazer a Consulta (GET)

GET https://requests.production.judit.io/billing/consumption

Autenticação

Header obrigatório api-key, preenchido com uma chave administrativa da company. A rota não recebe parâmetros — a company é identificada a partir da própria api-key, e o company_id vem de volta na resposta.

Chaves de integração comuns não têm permissão para ler dados de faturamento. Use a API Key administrativa da conta — a mesma utilizada pelo responsável de billing.

Disponibilidade por plano

Disponível para contas nos planos HOMOLOG, PAID e JUDIT.

Exemplos de Requisição

curl --location 'https://requests.production.judit.io/billing/consumption' \
  --header 'api-key: '"$JUDIT_API_KEY"

const response = await fetch('https://requests.production.judit.io/billing/consumption', {
  method: 'GET',
  headers: { 'api-key': process.env.JUDIT_API_KEY }
});

const data = await response.json();
console.log(data);

import os
import requests

response = requests.get(
    "https://requests.production.judit.io/billing/consumption",
    headers={"api-key": os.environ["JUDIT_API_KEY"]},
)

print(response.json())

Passo 2: Ler a Resposta

{
  "company_id": "3f6c1d2e-8a4b-4c90-9f1e-27b5ad08c631",
  "consumption": 1200,
  "max_consumption": 12500,
  "remaining": 11300,
  "cycle_started_at": "2026-09-01T03:00:00.000Z",
  "cycle_ended_at": "2026-10-01T02:59:59.999Z"
}

Campos da Resposta

Campo	Tipo	Significado
`company_id`	`uuid`	Company identificada pela `api-key`, à qual o consumo pertence.
`consumption`	`number`	Total já consumido dentro do ciclo vigente.
`max_consumption`	`number`	Teto efetivo do ciclo — já inclui os créditos extras de pós-pago, não é apenas o valor do plano base.
`remaining`	`number`	Saldo ainda disponível no ciclo (`max_consumption - consumption`).
`cycle_started_at`	`date-time`	Abertura do ciclo de faturamento atual (ISO 8601, UTC).
`cycle_ended_at`	`date-time`	Fechamento do ciclo atual (ISO 8601, UTC).

max_consumption é o teto efetivo, e não o teto contratual. Se a company tiver créditos adicionais de pós-pago liberados, eles já estão somados nesse número — por isso o valor pode mudar ao longo do ciclo mesmo sem alteração de plano.

Exemplos de Uso

Alerta ao cruzar um limiar

const { consumption, max_consumption, remaining } = await getConsumption();
const usage = consumption / max_consumption;

if (usage >= 0.8) {
  notificarTime(`Consumo em ${(usage * 100).toFixed(1)}% do teto — restam ${remaining}.`);
}

Pré-flight antes de um lote

Antes de enfileirar um volume grande de requisições, verifique se remaining comporta a operação planejada. Isso evita interromper um processamento no meio por estouro de teto.

const { remaining } = await getConsumption();

if (remaining < documentos.length) {
  throw new Error(`Saldo insuficiente no ciclo: restam ${remaining} para ${documentos.length} consultas.`);
}

Primeiros Passos

Conceitos Fundamentais

Modelo de Dados (Schemas)

Consultas Assíncronas

Consultas Síncronas

Monitoramento

Dados Cadastrais

Consultas Penais

Transferência de Arquivos

Cofre de Credenciais

Webhook

Recursos

Quando usar

Dashboards internos

Alertas de uso

Pré-flight de lotes

Fechamento por ciclo

Passo 1: Fazer a Consulta (GET)

Autenticação

Disponibilidade por plano

Exemplos de Requisição

Passo 2: Ler a Resposta

Campos da Resposta

Exemplos de Uso

Alerta ao cruzar um limiar

Pré-flight antes de um lote

Próximos Passos

Histórico de Consumo

Créditos Disponíveis

​Quando usar

Dashboards internos

Alertas de uso

Pré-flight de lotes

Fechamento por ciclo

​Passo 1: Fazer a Consulta (GET)

​Autenticação

​Disponibilidade por plano

​Exemplos de Requisição

​Passo 2: Ler a Resposta

​Campos da Resposta

​Exemplos de Uso

​Alerta ao cruzar um limiar

​Pré-flight antes de um lote

​Próximos Passos

Histórico de Consumo

Créditos Disponíveis

Quando usar

Passo 1: Fazer a Consulta (GET)

Autenticação

Disponibilidade por plano

Exemplos de Requisição

Passo 2: Ler a Resposta

Campos da Resposta

Exemplos de Uso

Alerta ao cruzar um limiar

Pré-flight antes de um lote

Próximos Passos