Sign In

Requisições e cobrança

Last updated

As consultas são realizadas por requisições HTTPS à base https://api.verifica-online.com.br. Cada operação pertence à conta e à chave de API que a criou. Preços e valores de cobrança são expressos em centavos de real, com moeda BRL.

Consulta individual

POST /datasets/{dataset}/queries
Authorization: Bearer <API_KEY>
Content-Type: application/json
Idempotency-Key: consulta-cpf-20261003-001

{dataset} é a chave publicada no catálogo de consultas, como cpf_dados_basicos. O corpo deve conter somente o campo de entrada desse dataset. Parâmetros na URL não são aceitos nesse POST.

curl --request POST 'https://api.verifica-online.com.br/datasets/cpf_dados_basicos/queries' \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: consulta-cpf-20261003-001' \
  --data '{"cpf":"52998224725"}'

O documento é um exemplo sintético de entrada. O exemplo não representa uma consulta executada nem garante a existência de dados para esse documento.

Entrada Formato
cpf String com 11 dígitos, sem pontuação e com dígitos verificadores válidos. Exemplo: 52998224725.
cnpj String com 14 caracteres: 12 letras maiúsculas ou dígitos e dois dígitos verificadores válidos, sem pontuação. Exemplo numérico: 11222333000181.
plate String com placa brasileira antiga ou Mercosul. Espaços e hífens são removidos e letras são convertidas para maiúsculas. Exemplo: ABC1D23.

CPF e CNPJ não são convertidos de número para string. Pontuação, espaços e letras minúsculas em CNPJ não são normalizados. A forma exata de entrada e os campos de resposta estão no contrato de cada dataset.

O corpo da requisição tem limite de 32 KiB, equivalentes a 32.768 bytes. Entradas inválidas são rejeitadas antes da execução da consulta. Para múltiplas entradas do mesmo dataset, aplica-se o contrato de lotes.

A espera pelos dados tem limite de 300 segundos. Validação, armazenamento e finalização também consomem tempo da requisição. Para consultas individuais, configure o timeout do cliente para pelo menos 360 segundos.

Cabeçalhos

Cabeçalho Uso
Authorization Obrigatório nos endpoints autenticados, no formato Bearer <API_KEY>.
Content-Type Obrigatório nos POSTs de consulta e lote, com application/json.
Idempotency-Key Opcional em consulta individual e obrigatório em lote.
X-Request-Id Identificador opcional de rastreamento HTTP em formato UUID. A API devolve um identificador em toda resposta.
X-Idempotent-Replay Devolvido com valor true quando uma operação existente é recuperada por idempotência.

O X-Request-Id identifica a requisição HTTP. O campo request_id de um resultado identifica a operação persistida. Uma repetição idempotente mantém o identificador da operação, mas pode ter outro identificador HTTP. Em respostas de erro, error.request_id corresponde ao rastreamento HTTP.

Idempotência

Uma chave de idempotência contém de oito a 128 caracteres e aceita letras de A a Z, letras de a a z, dígitos, _, ., :, -. Exemplo: consulta-cpf-20261003-001.

Na consulta individual, a ausência de Idempotency-Key faz cada POST criar uma nova operação. Para permitir recuperação segura após perda de conexão, a chave deve ser definida e preservada antes do primeiro envio.

Uma repetição de operação existente exige a mesma conta, a mesma chave de API, o mesmo dataset e a mesma entrada normalizada. Nos lotes, a ordem dos itens, o conteúdo e o tipo dos valores JSON das entradas inválidas e a configuração de webhook também integram a solicitação. A mesma chave com dados diferentes retorna idempotency_conflict, HTTP 409. Uma operação associada a outra chave de API não é exposta: o retorno é query_not_found ou batch_not_found, HTTP 404.

Consulta individual e lote possuem contextos de idempotência distintos. Dentro de cada contexto, o identificador não deve ser reutilizado para outro dataset ou outra operação da mesma conta.

Situação da operação existente Comportamento da repetição
Consulta ainda em processamento Retorna a mesma operação com HTTP 202, sem nova execução nem nova reserva.
Consulta concluída, com ou sem dados Retorna o resultado existente com HTTP 200, sem nova cobrança.
Consulta que falhou Retorna HTTP 200 com status: "failed", data: null e sem cobrança. O erro HTTP da primeira execução não é reproduzido.
Lote existente Retorna o mesmo lote conforme o modo de entrega e o estado descritos em lotes.
Resultado expirado Retorna HTTP 410. A expiração não libera a chave de idempotência para criar outra operação.

Uma falha HTTP anterior à criação da operação, como entrada inválida, não representa um resultado persistido. Já uma perda de conexão, um timeout ou uma resposta de indisponibilidade não comprovam que nenhuma operação foi criada. A repetição com a mesma chave e a mesma solicitação permite distinguir esses casos sem iniciar outra operação deliberadamente.

Depois de uma operação terminal, uma nova tentativa de consulta exige outra chave de idempotência e constitui nova operação. Não existe reexecução automática da consulta ao recuperar um resultado falho ou expirado.

Preços e saldo

GET /datasets, autenticado, informa price_cents por dataset e currency: "BRL". O preço pode ser específico da conta. Os valores do catálogo representam os preços vigentes no momento da leitura; a operação mantém o preço definido em sua criação.

Exemplos de unidade: 24 centavos correspondem a R$ 0,24; 2500 centavos correspondem a R$ 25,00. Esses valores são ilustrativos e não substituem o preço do catálogo autenticado.

O saldo corresponde a créditos para consultas, sem opção de saque, retirada ou conversão em dinheiro. As condições de reembolso, as hipóteses de restituição legalmente asseguradas ou decorrentes da oferta contratada e o canal de atendimento estão nos Termos de Uso.

O saldo disponível já considera valores reservados. Uma reserva reduz o saldo disponível imediatamente, mesmo quando a cobrança ainda está pendente. O campo billing.balance_cents é o saldo disponível registrado na criação ou na conclusão da operação, conforme seu estado. A recuperação desse campo não consulta o saldo atual da conta.

Reserva e liquidação

Resultado Consulta individual Lote
Operação aceita Reserva o preço de uma consulta. Reserva o preço unitário multiplicado pela quantidade de entradas válidas e únicas aceitas.
succeeded Consolida a cobrança do valor reservado. Conta como sucesso, mas a cobrança permanece pendente até o fechamento integral do lote.
partial Cobra o valor líquido e libera o restante da reserva. Cobrança e desconto são consolidados no fechamento do lote.
no_data Libera integralmente a reserva, sem cobrança. Não é cobrado; a parte correspondente da reserva é liberada no fechamento.
failed Libera integralmente a reserva, sem cobrança. Não é cobrado; a parte correspondente da reserva é liberada no fechamento.
Entrada inválida ou duplicada em lote Não se aplica. Não é aceita para execução e não reserva saldo.

A liberação de uma reserva recompõe o saldo disponível para consultas; não corresponde a reembolso do pagamento nem a saque em dinheiro.

Em lote, a reserva integral é mantida durante processing. Ao passar para completed, são cobrados os itens succeeded e partial, considerando descontos e gratuidade. A relação final é:

initial_reserved_cents = amount_cents + released_cents
amount_cents = unit_price_cents × (succeeded_count + partial_count) - discount_cents
charged_count = quantidade de itens com valor cobrado positivo
reserved_cents = 0

Uma consulta sem dados e uma consulta falha têm efeitos de cobrança iguais, mas significados diferentes. no_data representa conclusão válida sem resultado útil para aquela entrada; failed representa falha de execução. Um resultado válido com números zero, listas vazias ou campos nulos pode continuar sendo succeeded, conforme o contrato do dataset.

Também é possível recuperar um item de lote já succeeded ou partial com dados enquanto billing.status permanece pending. Cobrança e desconto desse item só são consolidados no fechamento do lote. Essa distinção é detalhada em resultados.

Descontos em consultas completas

Consultas completas com resultado partial podem ter desconto, informado em billing.discount_cents.

Saldo insuficiente

Quando o saldo disponível não cobre a reserva necessária, o retorno é HTTP 402, com insufficient_balance e detalhes em centavos:

{
  "error": {
    "code": "insufficient_balance",
    "message": "Saldo insuficiente para esta consulta.",
    "request_id": "639454ac-4dcc-4a56-a240-bc273424f40a",
    "details": {
      "required_cents": 248,
      "available_cents": 100,
      "currency": "BRL"
    }
  }
}

Os identificadores e valores do exemplo são sintéticos. Nenhuma consulta é executada por essa rejeição de saldo. Em lote, required_cents considera apenas as entradas válidas e únicas.

Respostas e recuperação

Consultas individuais concluídas com succeeded, partial ou no_data retornam HTTP 200. Uma falha na primeira execução pode retornar erro HTTP; a recuperação ou repetição idempotente dessa operação terminal retorna HTTP 200 com status: "failed". Uma operação existente que continua processing retorna HTTP 202. O conteúdo de data depende do dataset; o envelope comum está em resultados.

Com um identificador conhecido, GET /queries/{request_id} recupera a operação usando a mesma chave de API. A recuperação não cria consulta e não gera cobrança adicional. Por padrão, os resultados individuais ficam disponíveis por 48 horas contadas de created_at, e os resultados de lotes por 48 horas contadas de completed_at. Ao desabilitar essa retenção em Configurações, novas consultas e lotes ficam disponíveis por 5 minutos após sua conclusão. A validade de operações existentes é preservada; consulte o expires_at definitivo de cada operação.

Em Configurações, a conta também pode ativar um aviso por email quando o saldo disponível ficar abaixo do limite escolhido, inicialmente R$ 5,00. O aviso vem desabilitado, considera reservas e pode ser agendado ao ativá-lo com saldo já abaixo do limite. Há um aviso por período de saldo baixo; outro só é liberado após aumento do saldo para valor igual ou superior ao limite vigente e nova queda. Alterar preferências não reinicia um período já notificado. O envio é assíncrono, somente ao email cadastrado e verificado, e sua falha não interfere nas consultas ou cobranças.

Respostas usam Cache-Control: no-store. Recuperação, paginação ou entrega webhook não estendem a retenção. Os erros da API distinguem operação ausente, expiração e indisponibilidade temporária.