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.