Sign In

Métricas da conta

Last updated

GET /account/metrics retorna estatísticas das consultas da conta autenticada em um intervalo. A leitura não gera cobrança de consulta e não inclui dados pessoais dos resultados.

Requisição

curl 'https://api.verifica-online.com.br/account/metrics?period=30d' \
  --header 'Authorization: Bearer <API_KEY>'

As métricas reúnem o consumo de todas as chaves da conta. Para consultá-las, use uma chave ativa. A conta deve atender aos requisitos de acesso.

Intervalos

Parâmetro Valores ou formato Regra
period today, 7d, 30d, month, custom Opcional; o padrão é 30d.
from ISO 8601 com segundos e fuso explícito Obrigatório apenas em custom; início inclusivo.
to ISO 8601 com segundos e fuso explícito Obrigatório apenas em custom; fim inclusivo.
Período Início Fim
today Meia-noite do dia atual em America/Sao_Paulo. Momento da leitura.
7d Exatamente 7 dias de 24 horas antes da leitura. Momento da leitura.
30d Exatamente 30 dias de 24 horas antes da leitura. Momento da leitura.
month Meia-noite do primeiro dia do mês atual em America/Sao_Paulo. Momento da leitura.
custom Valor informado em from. Valor informado em to.

Em custom, a data deve ser válida, o início não pode ser posterior ao fim e o intervalo não pode exceder 366 dias. O formato exige YYYY-MM-DDTHH:mm:ss, admite de uma a três casas decimais nos segundos e exige Z ou deslocamento como -03:00. Datas sem horário ou sem fuso não são aceitas.

Exemplo de intervalo personalizado:

curl --get 'https://api.verifica-online.com.br/account/metrics' \
  --header 'Authorization: Bearer <API_KEY>' \
  --data-urlencode 'period=custom' \
  --data-urlencode 'from=2026-10-01T00:00:00-03:00' \
  --data-urlencode 'to=2026-10-02T23:59:59.999-03:00'

O intervalo retornado é convertido para ISO 8601 UTC. Os limites são aplicados à data de criação da consulta, não à data da conclusão ou do débito.

Resposta

Exemplo de um intervalo sem consultas:

{
  "metrics": {
    "period": "custom",
    "from": "2026-10-01T03:00:00.000Z",
    "to": "2026-10-03T02:59:59.999Z",
    "summary": {
      "total": 0,
      "succeeded": 0,
      "partial": 0,
      "no_data": 0,
      "failed": 0,
      "processing": 0,
      "charged_cents": 0,
      "discount_cents": 0,
      "average_duration_ms": 0,
      "p95_duration_ms": 0
    },
    "by_dataset": [],
    "by_day": []
  }
}
Campo de metrics Tipo Descrição
period string Período utilizado.
from string Início inclusivo em UTC.
to string Fim inclusivo em UTC.
summary object Totais e durações do intervalo.
by_dataset array de objects Totais agrupados por dataset com consultas no intervalo.
by_day array de objects Totais agrupados pelo dia de criação em UTC.

Resumo

Campo de summary Tipo Descrição
total integer Quantidade de registros de consulta selecionados.
succeeded integer Quantidade no estado succeeded.
partial integer Quantidade no estado partial, incluindo parciais gratuitos.
no_data integer Quantidade no estado no_data.
failed integer Quantidade no estado failed.
processing integer Quantidade no estado processing.
charged_cents integer Soma dos valores já cobrados dessas consultas, em centavos de BRL.
discount_cents integer Soma dos descontos consolidados, em centavos de BRL.
average_duration_ms integer Média das durações das consultas concluídas, arredondada em milissegundos.
p95_duration_ms integer Percentil 95 das durações das consultas concluídas, em milissegundos.

total é a soma de succeeded, partial, no_data, failed e processing. As durações incluem os quatro estados concluídos e excluem processing. O percentil utiliza as durações ordenadas e a posição ceil(0,95 × quantidade). Sem consultas concluídas, ambas as durações são zero.

A duração registrada não deve ser interpretada como o tempo completo percebido pela aplicação cliente, que pode incluir transmissão, fila e espera por lote.

Agrupamento por dataset

Campo de by_dataset[] Tipo Descrição
dataset string Identificador da modalidade.
total integer Quantidade de consultas na modalidade.
succeeded integer Quantidade bem-sucedida.
partial integer Quantidade com resultado parcial.
no_data integer Quantidade sem dados.
failed integer Quantidade com falha.
processing integer Quantidade em processamento.
charged_cents integer Soma cobrada na modalidade, em centavos de BRL.
discount_cents integer Soma dos descontos consolidados, em centavos de BRL.

A lista segue a ordem do catálogo e contém apenas datasets com registros no intervalo.

Agrupamento diário

Campo de by_day[] Tipo Descrição
date string Dia de criação no formato YYYY-MM-DD, em UTC.
total integer Quantidade de consultas criadas nesse dia e selecionadas pelo intervalo.
charged_cents integer Soma dos valores já cobrados dessas consultas.

Os dias aparecem em ordem cronológica e apenas quando existem registros. O agrupamento usa UTC mesmo nos períodos cujo início é calculado em America/Sao_Paulo; perto da meia-noite, a data de um agrupamento pode diferir da data local.

Consultas, lotes e cobrança

Cada consulta individual criada conta como um registro. Cada item aceito de um lote também conta como uma consulta. O lote não acrescenta um registro extra ao total. Itens rejeitados por entrada inválida ou duplicidade não são incluídos.

Repetições idempotentes, recuperações por GET e leituras de métricas não criam registros de consulta.

Os estados e valores representam os registros no momento da leitura. Um item de lote pode aparecer como succeeded ou partial com cobrança e desconto zero enquanto o lote ainda não foi consolidado. Após a conclusão, esses valores passam a compor as métricas do intervalo em que o item foi criado.

O endpoint apresenta estatísticas de consumo, não um extrato financeiro de recargas, reservas ou estornos. Ele também não representa uma fotografia dos estados existentes exatamente no último instante do intervalo solicitado. O saldo associado a uma operação está descrito em Resultados.

Erros

HTTP Código Situação
422 invalid_metrics_period Valor de period não reconhecido.
422 invalid_metrics_range Limites de custom ausentes, inválidos, invertidos ou superiores a 366 dias.

Erros de acesso e indisponibilidade seguem o contrato de Erros.