Sign In

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 processing retorna HTTP 202, sem dados.
  • Um item succeeded ou partial já pode retornar HTTP 200 e dados enquanto o lote continua em processamento.
  • Antes do fechamento do lote, billing.status permanece pending, charged é false, amount_cents e discount_cents são zero e expires_at é null, mesmo para um item terminal.
  • Depois do fechamento, itens succeeded e partial recebem a cobrança efetiva, com os descontos aplicáveis. Itens no_data e failed ficam sem cobrança.
  • Todos os itens recebem o mesmo limite de expiração: 48 horas ou 5 minutos após completed_at do 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.