Resultados
Last updated
O resultado de uma consulta tem um envelope comum com identificação, estado, cobrança, datas e dados. O objeto data segue o schema do dataset publicado no catálogo. Resultados de lotes têm envelope e listas próprios.
Origem e atualização dos dados
Todos os datasets utilizam informações de fornecedores terceiros, que podem estar incompletas, desatualizadas ou incorretas. A data da consulta não comprova a atualização dos dados na origem. Confirme as informações relevantes antes de decisões com impacto jurídico, financeiro ou patrimonial, conforme os Termos de Uso.
Envelope de consulta
| Campo | Tipo | Descrição |
|---|---|---|
request_id |
String UUID | Identificador da operação. É preservado na recuperação e nas repetições idempotentes. |
dataset |
String | Chave da consulta, como cpf_score_quod. |
schema_version |
String | Versão do schema dos dados retornados pela consulta; atualmente 1.0.0. |
status |
String | processing, succeeded, partial, no_data ou failed. |
billing |
Objeto | Estado e valores de cobrança. |
created_at |
String de data ISO 8601 | Data e hora de criação, com fuso explícito. |
expires_at |
String de data ISO 8601 ou null |
Limite de recuperação. É null para item de lote ainda não fechado ou consulta individual com retenção curta ainda em processamento. |
batch_request_id |
String UUID, opcional | Identificador do lote, presente somente em consultas que pertencem a um lote. |
data |
Objeto ou null |
Dados normalizados em succeeded e partial; null nos demais estados. |
As datas do envelope são devolvidas em UTC, com sufixo Z.
Campo de billing |
Tipo | Descrição |
|---|---|---|
status |
String | pending, charged ou not_charged. |
charged |
Boolean | Indica se houve cobrança de valor positivo. |
amount_cents |
Inteiro não negativo | Valor cobrado, em centavos de real. É zero enquanto pendente ou sem cobrança. |
discount_cents |
Inteiro não negativo | Desconto aplicado em centavos; zero enquanto pendente, em no_data ou failed. |
balance_cents |
Inteiro | Saldo disponível registrado pela operação; não é uma leitura do saldo atual. |
currency |
String | Sempre BRL. |
Os campos monetários não usam números decimais, símbolos de moeda ou separadores de milhar. A lógica de reserva está em requisições e cobrança.
Convenções dos dados normalizados
Campos textuais de saída são retornados sem caracteres de controle. Os formatos e limites seguem a referência de cada campo. Os limites de comprimento informados nesta documentação são medidos em unidades UTF-16, que não correspondem necessariamente à quantidade de caracteres visíveis.
Textos obrigatórios podem ser strings vazias quando a informação não está disponível e isso é permitido pelo contrato. Textos opcionais usam null nos campos assim declarados. Valores booleanos podem ser true, false ou null conforme o schema; null não deve ser interpretado como false.
Datas cadastrais, horários, porcentagens e valores monetários seguem os formatos e as unidades de cada campo. Arrays possuem limites e regras próprias. Os contratos de cada dataset detalham essas diferenças.
Estados
status |
data |
Significado |
|---|---|---|
processing |
null |
Operação ainda não terminal. A cobrança está pendente. |
succeeded |
Objeto | Consulta concluída com resultado útil segundo o contrato do dataset. |
partial |
Objeto | Consulta completa com dados úteis disponíveis e falha em parte da execução. |
no_data |
null |
Consulta concluída validamente sem dados úteis para a entrada. Não é cobrada. |
failed |
null |
Consulta falhou. Não é cobrada. |
no_data não é um erro HTTP. Também não se deve inferir ausência de dados apenas porque um resultado contém zero, listas vazias ou campos nulos: esses valores podem fazer parte de um objeto válido succeeded.
Para consulta individual terminal, billing.status é charged quando amount_cents é positivo; caso contrário, é not_charged e charged é false. Um resultado partial pode ser gratuito. Consulte os descontos. Itens de lotes têm a distinção adicional de liquidação pendente descrita adiante.
Exemplo com dados
O exemplo é sintético e demonstra o envelope de cpf_score_quod. Identificadores, datas, valores e score não representam uma resposta real nem um preço contratual.
{
"request_id": "27479345-d720-491d-84f8-621066c33829",
"dataset": "cpf_score_quod",
"schema_version": "1.0.0",
"status": "succeeded",
"billing": {
"status": "charged",
"charged": true,
"amount_cents": 248,
"discount_cents": 0,
"balance_cents": 9752,
"currency": "BRL"
},
"created_at": "2026-10-03T12:00:00.000Z",
"expires_at": "2026-10-05T12:00:00.000Z",
"data": {
"score": 650
}
}
O dataset define os campos de data. O contrato de cpf_score_quod, por exemplo, devolve score; outros datasets devolvem objetos, listas e campos diferentes. O envelope não acrescenta automaticamente o documento consultado a data.
Exemplo sem dados
Exemplo sintético de conclusão sem cobrança:
{
"request_id": "845498a6-99f9-4b34-8296-831e9c1518f4",
"dataset": "cpf_score_quod",
"schema_version": "1.0.0",
"status": "no_data",
"billing": {
"status": "not_charged",
"charged": false,
"amount_cents": 0,
"discount_cents": 0,
"balance_cents": 10000,
"currency": "BRL"
},
"created_at": "2026-10-03T12:00:00.000Z",
"expires_at": "2026-10-05T12:00:00.000Z",
"data": null
}
Uma operação em processing mantém data: null, billing.status: "pending", charged: false e amount_cents: 0. Seu balance_cents já reflete a reserva. Uma operação failed recuperada utiliza o mesmo envelope, com status: "failed", billing.status: "not_charged" e data: null.
Estado da operação e HTTP
| Resposta | HTTP | Corpo |
|---|---|---|
| Consulta individual concluída com dados | 200 | Envelope com status: "succeeded". |
| Consulta concluída com dados parciais | 200 | Envelope com status: "partial". |
| Consulta concluída sem dados | 200 | Envelope com status: "no_data". |
| Recuperação ou replay de consulta falha | 200 | Envelope com status: "failed". |
| Consulta ainda em processamento | 202 | Envelope com status: "processing". |
| Falha da requisição ou da primeira execução | 4xx ou 5xx | Envelope error, conforme erros. |
O HTTP indica o resultado da requisição. O campo status indica o estado da operação consultada. Por isso, HTTP 200 pode trazer uma operação failed, e uma falha na primeira execução pode gerar erro HTTP antes de a mesma operação ser recuperada como failed.
O envelope de consulta falha recuperada não contém error.code nem um motivo detalhado da execução. Em lote, os itens falhos têm códigos próprios na lista failed.
Recuperação
GET /queries/{request_id}
Authorization: Bearer <API_KEY>
curl 'https://api.verifica-online.com.br/queries/27479345-d720-491d-84f8-621066c33829' \
--header 'Authorization: Bearer <API_KEY>'
É necessária a mesma chave de API que criou a operação. Uma chave diferente, mesmo pertencendo à mesma conta, recebe HTTP 404. A recuperação não cria nova operação, não reexecuta a consulta e não cobra novamente.
Por padrão, consultas individuais ficam disponíveis por 48 horas a partir de created_at. A conta pode desabilitar essa opção em Configurações; nesse caso, novas consultas ficam disponíveis por 5 minutos após a conclusão. A preferência é registrada na admissão e não altera consultas existentes. Em processamento com retenção curta, expires_at é null; após a conclusão, ele informa o limite definitivo de acesso.
A partir de expires_at, a recuperação retorna query_expired, HTTP 410. Leituras e reconciliações não renovam o prazo. A mesma chave de idempotência não inicia outra operação após a expiração. O conteúdo é excluído pela manutenção assíncrona, preservando metadados de consumo e cobrança.
Quando os dados de uma consulta bem-sucedida estão temporariamente indisponíveis para leitura, a resposta é result_unavailable, HTTP 503. Outras falhas temporárias de recuperação podem retornar service_unavailable. Esses erros não indicam expiração nem autorizam considerar a consulta inexistente. O mesmo identificador pode ser recuperado novamente enquanto estiver dentro do prazo.
Consultas pertencentes a um lote
Um item aceito para execução em lote possui seu próprio request_id. Esse identificador aparece nos itens succeeded, partial e no_data, inclusive nos eventos correspondentes. O envelope obtido por GET /queries/{request_id} acrescenta batch_request_id.
O estado do item e a liquidação do lote são independentes:
- Um item
processingretorna HTTP 202, sem dados. - Um item
succeededoupartialjá pode retornar HTTP 200 e dados enquanto o lote continua em processamento. - Antes do fechamento do lote,
billing.statuspermanecepending,chargedéfalse,amount_centsediscount_centssão zero eexpires_aténull, mesmo para um item terminal. - Depois do fechamento, itens
succeededepartialrecebem a cobrança efetiva, com os descontos aplicáveis. Itensno_dataefailedficam sem cobrança. - Todos os itens recebem o mesmo limite de expiração: 48 horas ou 5 minutos após
completed_atdo lote, conforme a preferência registrada na admissão.
Exemplo sintético de um item cpf_emails concluído antes da liquidação do lote:
{
"request_id": "b13cf882-895d-47da-839f-1f3c378ffafa",
"dataset": "cpf_emails",
"schema_version": "1.0.0",
"status": "succeeded",
"billing": {
"status": "pending",
"charged": false,
"amount_cents": 0,
"discount_cents": 0,
"balance_cents": 9752,
"currency": "BRL"
},
"created_at": "2026-10-03T12:00:00.000Z",
"expires_at": null,
"batch_request_id": "722eab69-c85e-4c62-8dad-0442a79da11e",
"data": {
"cpf": "52998224725",
"total": 1,
"emails": [
{
"email": "contato@example.com",
"domain": "example.com",
"username": "contato",
"type": "personal",
"priority": 1,
"similarity": null,
"quality": null
}
]
}
}
O GET do lote em processing continua devolvendo data: null; o comportamento de recuperação de um filho não publica listas parciais no envelope do lote. Paginação, contadores globais e entregas estão documentados em lotes.
Identificação e armazenamento pelo integrador
O request_id de operação permite recuperar o resultado; X-Request-Id e error.request_id permitem rastrear uma requisição HTTP. São identificadores com finalidades diferentes.
As respostas usam Cache-Control: no-store. A recuperação não renova o prazo e a API não oferece retenção permanente dos dados consultados. Qualquer armazenamento pelo integrador deve respeitar os termos de uso e a política de privacidade.