Sign In

Catálogo de datasets

Last updated

GET /datasets retorna as modalidades de consulta, os schemas públicos, o preço efetivo da conta autenticada e a habilitação atual de consultas individuais e lotes.

Requisição

GET /datasets
Authorization: Bearer <API_KEY>
curl 'https://api.verifica-online.com.br/datasets' \
  --header 'Authorization: Bearer <API_KEY>'

O endpoint não exige corpo e não gera cobrança de consulta. A resposta bem-sucedida utiliza HTTP 200 e contém um objeto com a lista datasets.

Campos de cada dataset

Campo Tipo Descrição
key string Identificador usado no caminho da consulta, como cpf_dados_basicos.
id string Mesmo identificador de key.
name string Nome de apresentação.
description string Descrição da modalidade.
schema_version string Versão do schema dos dados retornados pela consulta; atualmente 1.0.0.
input_field string Campo de entrada: cpf, cnpj ou plate.
input_schema object Schema do corpo da consulta individual.
request_example object Exemplo estrutural da entrada, com valor de preenchimento.
response_schema object Schema do campo data do resultado individual.
example object Exemplo estrutural de data, derivado do schema.
public_method string Método da consulta individual: POST.
public_path string Caminho /datasets/{key}/queries.
enabled boolean Habilitação atual para novas consultas individuais, considerando as regras do catálogo.
price_cents integer Preço exibido, em centavos; em uma modalidade habilitada, é o preço efetivo da conta.
currency string Moeda: BRL.
batch object Contrato e habilitação atual do lote.

Em uma modalidade desabilitada, a presença de price_cents não assegura que uma consulta possa ser admitida por aquele valor. A integração deve exigir enabled: true e um preço válido antes de planejar uma nova consulta.

O preço pode ser específico da conta. Valores de exemplos da documentação não constituem tabela de preços. Cada operação aceita utiliza o preço registrado na sua admissão; leituras posteriores do catálogo não alteram esse valor.

Interpretação dos schemas e exemplos

input_schema descreve o corpo completo do POST individual. response_schema descreve somente data; os campos request_id, status, billing e datas pertencem ao envelope de resultados.

Os objetos dos schemas utilizam required para identificar campos e additionalProperties: false para limitar as propriedades do contrato. Campos declarados com união de tipos podem aceitar null. Arrays possuem limites próprios; a documentação de cada modalidade detalha seus itens, unidades e formatos.

Os padrões de CPF e CNPJ não substituem a validação dos dígitos verificadores. O schema de placa descreve a entrada antes da normalização; a placa resultante também precisa corresponder a um formato brasileiro válido.

request_example utiliza marcadores estruturais que podem falhar na validação de uma consulta real. example pode conter textos vazios, valores nulos e listas vazias. Esses exemplos não asseguram existência de dados e não definem critérios de sucesso ou ausência de dados. Exemplos ilustrativos completos estão nas referências de cada consulta.

Contrato de lote

Campo de batch Tipo Descrição
enabled boolean Admissão de novos lotes disponível naquele dataset e momento.
schema_version string Versão do schema de lote; atualmente 1.0.0.
max_items integer Máximo de 50 itens por lote.
max_input_bytes integer Máximo de 32.768 bytes no corpo da requisição.
max_response_bytes integer Limite de 20.971.520 bytes para composição de uma página de resposta.
wait_seconds integer Espera de até 30 segundos pela conclusão no POST sem webhook.
deadline_seconds integer Prazo de processamento de 3.600 segundos.
retention_seconds integer Prazo para novos lotes da conta: 172.800 segundos por padrão ou 300 segundos com retenção curta, contados da conclusão.
public_method string Método: POST.
public_path string Caminho /datasets/{key}/batches.
input_schema object Schema do corpo com items e webhook opcional.
response_schema object Schema de data, com results, partial, failed e no_data, ou null durante o processamento.

batch.schema_version corresponde ao campo batch_schema_version nas respostas e nos eventos de lote. O campo schema_version dessas respostas identifica o schema dos dados dos itens.

A preferência de retenção é alterada em Configurações no painel e vale somente para novas operações. Em um lote já admitido, use seu expires_at definitivo; mudar a preferência ou reler o catálogo não altera esse prazo.

O objeto batch é apresentado mesmo em modalidades sem suporte a lote. batch.enabled: false também pode indicar indisponibilidade temporária em uma modalidade compatível; o suporte estrutural está listado na Introdução.

No lote, o identificador de entrada é definido pelo dataset. Por exemplo, cpf_enderecos recebe items como lista de CPFs, sem objetos intermediários ou repetição da chave cpf.

Disponibilidade

enabled informa a habilitação da modalidade no catálogo. Novas consultas continuam sujeitas à autenticação, ao saldo, aos limites e à disponibilidade no momento da operação.

batch.enabled incorpora condições adicionais para admissão de lotes. A modalidade veicular_completa fica desabilitada para novas operações entre 23h, inclusive, e 3h, exclusive, no fuso America/Sao_Paulo.

O endpoint de saúde apresenta a disponibilidade geral sem preços específicos da conta. Sua leitura não substitui o catálogo autenticado.

Erros

Falhas de autenticação e autorização seguem Autenticação. Falhas temporárias seguem o formato descrito em Erros. Uma leitura malsucedida não deve ser interpretada como catálogo vazio ou alteração de preços.