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.