Sign In

Recuperação de consultas

Last updated

GET /queries/{request_id} recupera o estado e, quando disponível, o resultado de uma consulta já criada. O endpoint não executa uma nova pesquisa nem gera uma nova cobrança.

Requisição

GET /queries/{request_id}
Authorization: Bearer <API_KEY>
curl 'https://api.verifica-online.com.br/queries/5b3b05a2-98ac-49eb-a757-33472b8bcb84' \
  --header 'Authorization: Bearer <API_KEY>'

request_id é o identificador da consulta retornado no envelope. Não corresponde ao cabeçalho X-Request-Id, ao identificador de um lote nem à chave de idempotência.

Autorização

A chamada exige a mesma conta e a mesma chave de API utilizadas na criação, com a chave ainda ativa e a conta apta ao uso. Outra chave da mesma conta recebe 404 query_not_found.

Uma chave revogada recebe 401 invalid_api_key. A emissão de uma nova chave não transfere a autorização de recuperação de operações anteriores. O histórico do portal utiliza a sessão da conta e a validade de acesso aos resultados.

Estados e códigos HTTP

HTTP status data Significado
202 processing null Consulta ainda em processamento.
200 succeeded object Resultado normalizado disponível.
200 partial object Resultado parcial disponível.
200 no_data null Consulta concluída sem dados, sem cobrança.
200 failed null Consulta concluída com falha, sem cobrança da consulta.

Exemplo ilustrativo de uma consulta individual em processamento:

{
  "request_id": "5b3b05a2-98ac-49eb-a757-33472b8bcb84",
  "dataset": "cpf_dados_basicos",
  "schema_version": "1.0.0",
  "status": "processing",
  "billing": {
    "status": "pending",
    "charged": false,
    "amount_cents": 0,
    "discount_cents": 0,
    "balance_cents": 4950,
    "currency": "BRL"
  },
  "created_at": "2026-10-03T12:00:00.000Z",
  "expires_at": "2026-10-05T12:00:00.000Z",
  "data": null
}

Os campos, a cobrança e os formatos de ausência estão detalhados em Resultados. O saldo do envelope é um registro associado à operação, não uma leitura do saldo atual da conta. A resposta recuperada com status: "failed" não contém um objeto error com a causa original.

Consultas pertencentes a lotes

Cada item aceito de um lote possui um identificador próprio de consulta. O endpoint pode recuperá-lo usando a chave que criou o lote. A resposta inclui batch_request_id.

Um item pode terminar como succeeded ou partial e disponibilizar data enquanto o lote ainda está em processamento. Nessa fase, billing.status permanece pending, amount_cents e discount_cents são zero e expires_at é null. A cobrança e a validade de acesso são consolidadas na conclusão do lote.

Itens rejeitados na validação de entrada ou por duplicidade não possuem uma consulta recuperável por esse endpoint. O acompanhamento do conjunto de itens ocorre em GET /batches/{request_id}.

Expiração e indisponibilidade

HTTP Código Situação
404 query_not_found Identificador inexistente, inválido ou não autorizado para a chave.
410 query_expired Prazo de acesso encerrado.
503 result_unavailable Resultado bem-sucedido temporariamente indisponível para leitura.

Consultas individuais permitem acesso por 48 horas após a criação por padrão. Com a retenção de 48 horas desabilitada em Configurações, novas consultas permitem acesso por 5 minutos após a conclusão e publicam expires_at: null enquanto processam. Itens de lote seguem o prazo de 48 horas ou 5 minutos após a conclusão do lote, conforme a preferência registrada na admissão. O fim do prazo impede a recuperação mesmo que o histórico da operação permaneça registrado.

Em result_unavailable, uma nova tentativa de leitura não executa a pesquisa e não cobra novamente. Uma nova chamada de criação, com outra chave de idempotência, constitui outra operação e pode gerar cobrança. Os procedimentos de recuperação estão em Requisições e cobrança e Erros.