Consultas em lote
Last updated
Um lote reúne entradas de um único dataset, mantém a ordem original por índices e consolida a cobrança somente depois de todos os itens aceitos terminarem. A entrega pode ser acompanhada pela resposta HTTP ou por eventos de webhook.
Base da API: https://api.verifica-online.com.br. O suporte e a disponibilidade de lote por dataset são publicados em batch no catálogo autenticado.
Criar lote
POST /datasets/{dataset}/batches
Authorization: Bearer <API_KEY>
Content-Type: application/json
Idempotency-Key: lote-cpf-20261003-001
O corpo aceita somente items e, opcionalmente, webhook. Parâmetros na URL não são aceitos nesse POST.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
items |
Array | Sim | De uma a 50 entradas do mesmo dataset, na ordem desejada. Cada entrada válida deve ser uma string no formato publicado para esse dataset. |
webhook |
Objeto | Não | Destino e segredo de assinatura dos eventos. Deve conter somente url e secret. |
webhook.url |
String | Quando houver webhook | URL HTTPS pública na porta 443, com até 2.048 caracteres. |
webhook.secret |
String | Quando houver webhook | De 32 a 128 caracteres ASCII imprimíveis, do espaço ao ~. Não é devolvido nas respostas. |
Exemplo sintético para cpf_emails, com uma entrada válida, uma repetida e uma inválida:
curl --request POST 'https://api.verifica-online.com.br/datasets/cpf_emails/batches' \
--header 'Authorization: Bearer <API_KEY>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: lote-cpf-20261003-001' \
--data '{"items":["52998224725","52998224725","cpf-invalido"]}'
O documento é usado apenas para demonstrar o formato. Nenhuma entrada de exemplo representa uma consulta executada ou garante um resultado.
Validação e duplicidade
O corpo é validado como lote; as entradas são validadas individualmente segundo o dataset. Uma entrada inválida é registrada como invalid_input, e uma repetida depois da normalização é registrada como duplicate_input. Somente a primeira ocorrência válida é aceita para execução.
Em consultas por placa, por exemplo, ABC1D23 e abc-1d23 representam a mesma entrada normalizada e são duplicadas dentro do lote. CPF e CNPJ seguem seus formatos próprios, descritos em requisições e cobrança.
Uma entrada rejeitada preserva sua string original em key; quando o valor recebido não é uma string, key é null. Entradas inválidas e duplicadas não reservam saldo nem geram cobrança.
Um lote com todas as entradas rejeitadas pode terminar como completed, com accepted_count: 0, reserva zero e cobrança zero. Ainda são exigidos acesso válido, preço válido, disponibilidade do processamento e observância dos limites de admissão. A presença de entradas inválidas não dispensa essas verificações.
Limites e prazos
| Limite | Valor |
|---|---|
| Entradas por lote | De uma a 50. |
| Corpo da requisição | 32 KiB, equivalentes a 32.768 bytes. |
| Resposta de resultados por página | Até 20 MiB, equivalentes a 20.971.520 bytes. |
| Espera de processamento no POST sem webhook | Até 30 segundos. |
| Processamento e armazenamento por item | Até 330 segundos, limitado pelo prazo restante do lote. |
| Prazo de processamento do lote | Uma hora a partir da criação. |
| Retenção dos resultados | 48 horas por padrão ou 5 minutos após o fechamento, conforme a configuração da conta na admissão. |
| Lotes simultâneos por conta | Dois em processamento. |
| Novos lotes por conta | Cinco por minuto. |
| Entregas webhook pendentes por conta | Até mil, contando um evento por entrada e um evento final por lote. |
A capacidade compartilhada também pode limitar a admissão. A recuperação não prolonga a retenção. A espera de 30 segundos se refere ao processamento; validação, admissão e leitura da resposta também consomem tempo da requisição HTTP.
Idempotência
Idempotency-Key é obrigatório e contém de oito a 128 caracteres entre letras, dígitos, _, ., :, -. A repetição exige a mesma conta, a mesma chave de API, o mesmo dataset, as mesmas entradas na mesma ordem e a mesma configuração de webhook. Entradas válidas são comparadas na forma normalizada; para entradas inválidas, são comparados o conteúdo e o tipo do valor JSON recebido. Alterar uma entrada de null para 123, por exemplo, retorna idempotency_conflict, mesmo que ambas sejam rejeitadas e apresentem key: null.
Uma operação existente é recuperada sem nova execução, nova reserva ou nova cobrança, com X-Idempotent-Replay: true. Dados diferentes para a mesma chave retornam idempotency_conflict, HTTP 409. Uma chave de API diferente não obtém acesso ao lote original, mesmo pertencendo à mesma conta.
A expiração dos resultados não libera a chave de idempotência. Um replay do lote expirado retorna batch_expired, HTTP 410. Uma nova operação exige outra chave. As regras gerais e a recuperação após perda de conexão estão em requisições e cobrança.
HTTP de criação e acompanhamento
| Requisição | Estado e modo | HTTP |
|---|---|---|
| POST sem webhook | Lote concluído dentro da espera. | 200 |
| POST sem webhook | Lote continua processing. |
202 |
| POST com webhook | Qualquer estado do lote, inclusive replay já completed. |
202 |
| GET do lote | processing. |
202 |
| GET do lote | completed. |
200 |
O POST aceito devolve Location: /batches/{request_id}. Uma resposta cujo lote continua processing inclui Retry-After: 2, em segundos. O HTTP 202 de um POST com webhook não significa necessariamente que o estado ainda é processing; deve-se ler o campo status.
GET /batches/{request_id}
Authorization: Bearer <API_KEY>
curl 'https://api.verifica-online.com.br/batches/722eab69-c85e-4c62-8dad-0442a79da11e' \
--header 'Authorization: Bearer <API_KEY>'
É necessária a mesma chave de API que criou o lote. O GET aceita somente o parâmetro opcional cursor. Recuperação não cria outra operação e não cobra novamente. Uma desconexão durante a espera não cancela o lote já aceito.
Envelope do lote
| Campo | Tipo | Descrição |
|---|---|---|
request_id |
String UUID | Identificador do lote. |
dataset |
String | Chave do dataset de todos os itens. |
schema_version |
String | Versão do schema dos dados retornados pelos itens. |
batch_schema_version |
String | Versão do schema de lote; atualmente 1.0.0. |
status |
String | processing ou completed. |
billing |
Objeto | Preço, reserva, cobrança e contadores globais. |
created_at |
String ISO 8601 | Criação do lote em UTC. |
completed_at |
String ISO 8601 ou null |
Fechamento do lote; null enquanto em processamento. |
expires_at |
String ISO 8601 ou null |
Expiração 48 horas ou 5 minutos após o fechamento; null enquanto em processamento. |
delivery |
Objeto | Modo e estado das entregas webhook. |
pagination |
Objeto | Indicação de continuação dos resultados. |
data |
Objeto ou null |
Quatro listas de resultados após o fechamento; null durante processing. |
completed significa que todos os itens chegaram a um estado terminal. Não significa que todos tiveram sucesso: um lote totalmente falho também é completed.
Cobrança e contadores
Campo de billing |
Tipo | Descrição |
|---|---|---|
status |
String | pending durante processamento; charged ou not_charged no fechamento. |
charged |
Boolean | Indica cobrança consolidada maior que zero. |
amount_cents |
Inteiro não negativo | Total cobrado; zero durante processamento. |
discount_cents |
Inteiro não negativo | Total de descontos aplicados; zero durante processamento. |
balance_cents |
Inteiro | Saldo disponível registrado pela operação, não saldo atual. |
currency |
String | Sempre BRL. |
unit_price_cents |
Inteiro positivo | Preço unitário definido na criação do lote. |
initial_reserved_cents |
Inteiro não negativo | Reserva inicial para todos os itens aceitos. |
reserved_cents |
Inteiro não negativo | Reserva ainda mantida: integral enquanto processing, zero no fechamento. |
released_cents |
Inteiro não negativo | Valor liberado no fechamento por descontos e itens sem cobrança. |
received_count |
Inteiro não negativo | Total de entradas recebidas, incluindo rejeitadas. |
accepted_count |
Inteiro não negativo | Entradas válidas e únicas aceitas para execução. |
completed_count |
Inteiro não negativo | Itens terminais, incluindo inválidos e duplicados. |
succeeded_count |
Inteiro não negativo | Consultas concluídas com dados e sem falhas. |
partial_count |
Inteiro não negativo | Consultas com dados parciais, incluindo as gratuitas. |
no_data_count |
Inteiro não negativo | Consultas concluídas sem dados. |
failed_count |
Inteiro não negativo | Total de itens falhos, incluindo inválidos e duplicados. |
charged_count |
Inteiro não negativo | Zero durante processamento; itens com cobrança positiva no fechamento. |
invalid_count |
Inteiro não negativo | Entradas rejeitadas por formato ou validação. |
duplicate_count |
Inteiro não negativo | Entradas rejeitadas por duplicidade. |
Durante processing, a cobrança e os descontos permanecem pendentes e a reserva inicial é mantida. No fechamento, succeeded e partial seguem as regras de cobrança. Itens no_data e failed ficam sem cobrança e desconto.
received_count = accepted_count + invalid_count + duplicate_count
completed_count = succeeded_count + partial_count + no_data_count + failed_count
initial_reserved_cents = unit_price_cents × accepted_count
No fechamento, aplicam-se também:
completed_count = received_count
charged_count = quantidade de itens com valor cobrado positivo
amount_cents = unit_price_cents × (succeeded_count + partial_count) - discount_cents
initial_reserved_cents = amount_cents + released_cents
reserved_cents = 0
Os contadores são globais do lote e não correspondem apenas aos itens presentes na página atual.
Entregas
Campo de delivery |
Tipo | Descrição |
|---|---|---|
mode |
String | response sem webhook; webhook quando configurado. |
total_count |
Inteiro não negativo | Zero no modo response; no modo webhook, received_count + 1. |
pending_count |
Inteiro não negativo | Eventos ainda não terminais, incluindo entregas em andamento e eventos de itens que ainda não terminaram. |
delivered_count |
Inteiro não negativo | Eventos confirmados por HTTP 2xx. |
failed_count |
Inteiro não negativo | Eventos cuja entrega terminou sem confirmação. |
blocked_count |
Inteiro não negativo | Eventos bloqueados por restrição de acesso. |
final_status |
String ou null |
Estado da entrega de batch.completed: pending, processing, sent, failed, blocked; null antes da criação desse evento ou no modo response. |
No modo response, todos os contadores de entrega são zero e final_status é null. No modo webhook:
total_count = pending_count + delivered_count + failed_count + blocked_count
delivery.failed_count descreve falhas de entrega; billing.failed_count descreve falhas das entradas. Uma entrega falha não reexecuta a consulta, não altera o resultado e não cria outra cobrança.
Paginação
Campo de pagination |
Tipo | Descrição |
|---|---|---|
has_more |
Boolean | Indica que existem mais resultados após a página atual. |
next_cursor |
String ou null |
Cursor opaco de continuação; null quando não há outra página. |
Durante processamento, pagination é {"has_more":false,"next_cursor":null}. Um cursor só é aceito para lote concluído.
Quando has_more é true, a continuação usa exatamente next_cursor, codificado como valor de parâmetro da URL:
GET /batches/{request_id}?cursor={next_cursor}
Authorization: Bearer <API_KEY>
O cursor está vinculado ao lote, à conta e à chave de API. Não deve ser decodificado, modificado ou reutilizado em outro contexto. As páginas avançam pela posição original dos itens; cada uma pode conter quantidades diferentes em results, partial, failed e no_data. Sem cursor, o GET devolve a primeira página.
Listas de resultados
data é null durante processamento. Após o fechamento, contém sempre quatro arrays, inclusive quando algum deles está vazio:
| Lista | Conteúdo |
|---|---|
results |
Dados do schema do dataset, acrescidos de index e request_id. Não há um campo genérico key; o documento ou placa só aparece se fizer parte do schema daquele dataset. |
partial |
Dados disponíveis de itens parciais, com o mesmo schema e campos index e request_id de results. |
failed |
Objetos com index, key, code e message. Não contém request_id. |
no_data |
Objetos com index, key e request_id. |
index é inteiro de base zero e identifica a posição original em items. Cada lista é ordenada por esse índice, e cada entrada aparece em apenas uma lista.
Em failed e no_data, key preserva a string original enviada, antes da normalização, inclusive para uma entrada aceita que falhou ou terminou sem dados. Para entradas não textuais rejeitadas, é null. Em uma repetição idempotente, prevalece a entrada da criação original.
Código de failed |
Mensagem |
|---|---|
invalid_input |
Entrada inválida. |
duplicate_input |
Entrada duplicada neste lote. |
query_failed |
Não foi possível concluir a consulta. |
query_timeout |
A consulta não foi concluída dentro do prazo. |
access_disabled |
O acesso à API foi desabilitado. |
Exemplo sintético de lote concluído para as três entradas do exemplo de criação. Dados, identificadores, datas e valores são ilustrativos e não representam uma resposta real ou um preço contratual:
{
"request_id": "722eab69-c85e-4c62-8dad-0442a79da11e",
"dataset": "cpf_emails",
"schema_version": "1.0.0",
"batch_schema_version": "1.0.0",
"status": "completed",
"billing": {
"status": "charged",
"charged": true,
"amount_cents": 248,
"discount_cents": 0,
"balance_cents": 9752,
"currency": "BRL",
"unit_price_cents": 248,
"initial_reserved_cents": 248,
"reserved_cents": 0,
"released_cents": 0,
"received_count": 3,
"accepted_count": 1,
"completed_count": 3,
"succeeded_count": 1,
"partial_count": 0,
"no_data_count": 0,
"failed_count": 2,
"charged_count": 1,
"invalid_count": 1,
"duplicate_count": 1
},
"created_at": "2026-10-03T12:00:00.000Z",
"completed_at": "2026-10-03T12:00:02.000Z",
"expires_at": "2026-10-05T12:00:02.000Z",
"delivery": {
"mode": "response",
"total_count": 0,
"pending_count": 0,
"delivered_count": 0,
"failed_count": 0,
"blocked_count": 0,
"final_status": null
},
"pagination": {
"has_more": false,
"next_cursor": null
},
"data": {
"results": [
{
"cpf": "52998224725",
"total": 1,
"emails": [
{
"email": "contato@example.com",
"domain": "example.com",
"username": "contato",
"type": "personal",
"priority": 1,
"similarity": null,
"quality": null
}
],
"index": 0,
"request_id": "b13cf882-895d-47da-839f-1f3c378ffafa"
}
],
"failed": [
{
"index": 1,
"key": "52998224725",
"code": "duplicate_input",
"message": "Entrada duplicada neste lote."
},
{
"index": 2,
"key": "cpf-invalido",
"code": "invalid_input",
"message": "Entrada inválida."
}
],
"no_data": [],
"partial": []
}
}
Se uma consulta aceita terminar sem dados, sua entrada aparece em no_data, por exemplo:
{
"index": 0,
"key": "52998224725",
"request_id": "109ece7b-48c5-450a-b017-a3c0c5a2d616"
}
Esse segundo exemplo mostra a estrutura de um item isolado, não um item adicional ao lote anterior.
Webhook
O destino deve ser HTTPS na porta 443, acessível por endereços IP públicos. URLs com credenciais, fragmentos ou endereços privados, locais ou reservados são rejeitadas. O destino é validado na admissão e em cada tentativa de entrega. Redirects não são seguidos.
Exemplo de corpo de criação; o domínio e o segredo são placeholders ilustrativos a substituir por um destino público válido e um segredo de assinatura:
{
"items": ["52998224725", "52998224725", "cpf-invalido"],
"webhook": {
"url": "https://integracao.example.com/webhooks/verifica-online",
"secret": "<WEBHOOK_SECRET_COM_32_A_128_CARACTERES_ASCII>"
}
}
O segredo do webhook é independente da chave Bearer da API. Ele não é incluído nos eventos ou nas respostas de recuperação.
Eventos e corpo
| Evento | Quando é criado | data |
|---|---|---|
batch.item_completed |
Um item termina ou é rejeitado na admissão. | Objeto com results, partial, failed e no_data; somente a lista correspondente contém um item. |
batch.completed |
Todos os itens terminam e a cobrança é consolidada. | null. Os resultados completos são recuperados pelo GET do lote. |
Há um evento para cada entrada recebida, incluindo inválidos e duplicados, e um evento final. O corpo usa os campos abaixo; não inclui delivery nem pagination:
| Campo do evento | Tipo | Descrição |
|---|---|---|
event_id |
String | Identificador estável do evento, preservado nas tentativas de entrega. |
event_type |
String | batch.item_completed ou batch.completed. |
request_id |
String UUID | Identificador do lote. Não é o identificador do item. |
dataset |
String | Dataset do lote. |
schema_version |
String | Versão do schema dos dados retornados pelos itens. |
batch_schema_version |
String | Versão do schema de lote. |
status |
String | Estado do lote no momento de criação do evento. |
billing |
Objeto | Os mesmos campos de cobrança e contadores do lote, registrados na criação do evento. |
created_at |
String ISO 8601 | Criação do lote. |
completed_at |
String ISO 8601 ou null |
Fechamento no snapshot do evento. |
expires_at |
String ISO 8601 ou null |
Expiração no snapshot do evento. |
results_url |
String | Caminho relativo /batches/{request_id}, resolvido na base da API. |
data |
Objeto ou null |
Item correspondente no evento de item; null no evento final. |
O evento de item é registrado antes da liquidação: status é processing, cobrança é pending, amount_cents, discount_cents e charged_count são zero, completed_at e expires_at são null. Isso também vale para o evento do último item. O evento final registra completed, cobrança consolidada e datas finais.
O snapshot não é atualizado na entrega. Um evento de item recebido depois do fechamento continua descrevendo o momento em que foi criado. Os contadores do snapshot são globais, embora data contenha apenas um item.
Exemplo sintético de evento de item para as mesmas entradas, em um lote configurado com webhook:
{
"event_id": "6da2de43cf1b499ab859901df02e31911b5a53b7c1809329aca36d5227f82300",
"event_type": "batch.item_completed",
"request_id": "722eab69-c85e-4c62-8dad-0442a79da11e",
"dataset": "cpf_emails",
"schema_version": "1.0.0",
"batch_schema_version": "1.0.0",
"status": "processing",
"billing": {
"status": "pending",
"charged": false,
"amount_cents": 0,
"discount_cents": 0,
"balance_cents": 9752,
"currency": "BRL",
"unit_price_cents": 248,
"initial_reserved_cents": 248,
"reserved_cents": 248,
"released_cents": 0,
"received_count": 3,
"accepted_count": 1,
"completed_count": 3,
"succeeded_count": 1,
"partial_count": 0,
"no_data_count": 0,
"failed_count": 2,
"charged_count": 0,
"invalid_count": 1,
"duplicate_count": 1
},
"created_at": "2026-10-03T12:00:00.000Z",
"completed_at": null,
"expires_at": null,
"results_url": "/batches/722eab69-c85e-4c62-8dad-0442a79da11e",
"data": {
"results": [
{
"cpf": "52998224725",
"total": 1,
"emails": [
{
"email": "contato@example.com",
"domain": "example.com",
"username": "contato",
"type": "personal",
"priority": 1,
"similarity": null,
"quality": null
}
],
"index": 0,
"request_id": "b13cf882-895d-47da-839f-1f3c378ffafa"
}
],
"failed": [],
"no_data": [],
"partial": []
}
}
No evento final correspondente, event_type é batch.completed, event_id identifica outro evento, status é completed, billing contém os valores consolidados do exemplo de lote concluído, as datas finais são preenchidas e data é null. results_url continua apontando ao mesmo lote.
Assinatura
As entregas são POSTs em application/json, com os seguintes cabeçalhos:
X-Webhook-Id: <EVENT_ID>
X-Webhook-Timestamp: <TIMESTAMP_UNIX_EM_SEGUNDOS>
X-Webhook-Signature: v1=<ASSINATURA_HEXADECIMAL>
X-Webhook-Id corresponde a event_id do corpo. O timestamp é decimal, em segundos desde a época Unix, e representa a tentativa de entrega. A assinatura é hexadecimal de HMAC-SHA256 com o segredo configurado e esta mensagem:
event_id + "." + timestamp + "." + corpo_bruto
O corpo assinado é a sequência exata de bytes UTF-8 recebida. Fazer parse e serializar novamente o JSON pode alterar espaços ou ordem de campos e produzir outra assinatura.
O recebimento deve preservar o corpo bruto antes do parse, validar o formato v1= seguido de 64 caracteres hexadecimais, calcular o HMAC, comparar em tempo constante e verificar a atualidade do timestamp segundo a política da integração. Também deve conferir a correspondência entre o identificador do cabeçalho e event_id, o tipo de evento, o lote esperado, versões, estado, contadores e schema de data.
Uma nova tentativa preserva event_id, mas usa timestamp e assinatura novos. A deduplicação deve usar event_id, não a assinatura ou o timestamp.
Confirmação e novas tentativas
Uma resposta HTTP 2xx confirma a entrega. A API não usa o corpo da resposta. Cada tentativa tem limite de dez segundos. Ausência de confirmação, outros códigos HTTP e falhas de conexão podem gerar novas tentativas.
São realizadas até oito tentativas, dentro de 24 horas após a criação de cada evento e limitadas à validade do lote. Os intervalos crescem aproximadamente de 30 segundos para dois minutos, dez minutos, uma hora, três horas, seis horas e 12 horas, com variação adicional. O prazo máximo ou a expiração do lote pode encerrar a entrega antes de todas as tentativas.
Não há garantia de ordem ou de recebimento exatamente uma vez. O evento final pode chegar antes de um evento de item em nova tentativa. Processe cada evento de forma idempotente e registre-o de forma durável antes de confirmar o recebimento. A chegada de um snapshot antigo não deve substituir um estado final já conhecido.
Restrição de acesso pode bloquear entregas pendentes. Falha ou bloqueio do webhook não cancela a consulta, não muda sua cobrança e não estende a retenção. O estado de entrega pode ser acompanhado em delivery; os resultados continuam recuperáveis com acesso válido durante o prazo.
Recuperação de itens e expiração
Um request_id publicado em results, partial ou no_data também pode ser usado em GET /queries/{request_id} com a mesma chave de API. Um item já concluído pode ter dados antes de o lote fechar, mas sua cobrança continua pendente e sua expiração é null até esse fechamento. O envelope de filho está em resultados.
Os resultados do lote e de seus itens expiram juntos: 48 horas após completed_at por padrão, ou 5 minutos após completed_at se a retenção de 48 horas estava desabilitada na admissão. A opção é alterada em Configurações no painel e não modifica lotes já admitidos. GET do lote expirado retorna batch_expired, HTTP 410; GET do filho expirado retorna query_expired, HTTP 410. Cursores, leituras e eventos não renovam o prazo. Entregas webhook pendentes são encerradas ao expirar o lote.
Corpo inválido, acesso, saldo, limites e indisponibilidade são descritos em erros da API. Uma perda de conexão no POST deve ser tratada preservando a chave de idempotência e a solicitação original.