POST
/
consultas
/
executar
/
{id}
curl --request POST \
  --url https://api.sollosconsultas.vanced.tec.br/consultas/executar/{id} \
  --header 'Content-Type: application/json' \
  --header 'x-access-token: <api-key>' \
  --data '
{
  "cpf": "12345678900"
}
'
{
  "status": "completed",
  "query_execution": 4201,
  "data_execucao": "10/04/2026 14:32:00",
  "resultados": {
    "nome": "JOÃO DA SILVA",
    "cpf": "123.456.789-00",
    "situacao_receita": "REGULAR",
    "data_nascimento": "1985-03-22",
    "emails": [
      "joao@email.com"
    ],
    "telefones": [
      "(11) 98765-4321"
    ]
  }
}

​
Como descobrir os parâmetros

Cada consulta tem um conjunto diferente de parâmetros. Antes de executar, use GET /consultas/{id} para ver quais campos enviar e quais são obrigatórios: 
GET /consultas/1
Resposta
{
  "id": 1,
  "name": "kyc_pf",
  "display_name": "KYC — Pessoa Física",
  "parameters": [{ "name": "cpf", "display_name": "CPF", "is_required": true }]
}
Com isso, você sabe que o body da execução deve conter { "cpf": "..." }.

​
Fluxo completo de execução

1

Executar a consulta

Envie o POST com os parâmetros corretos. A API retorna 202 com um consultaId imediatamente — sem aguardar o provedor.
POST /consultas/executar/1
Content-Type: application/json
x-access-token: <seu_token>

{ "cpf": "12345678900" }
Resposta 202
{
  "consultaId": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "message": "Consulta enfileirada com sucesso."
}
2

Aguardar processamento

Aguarde ~2 segundos. A maioria das consultas conclui em 1 a 3 segundos.
3

Verificar o resultado

Passe o consultaId para GET /consultas/resultado/{consultaId}. Continue tentando enquanto status for pending.

​
Exemplo completo em código

async function executarConsulta(token, consultaId, params) {
  // 1. Executa
  const exec = await fetch(
    `https://api.sollosconsultas.com.br/consultas/executar/${consultaId}`,
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-access-token": token,
      },
      body: JSON.stringify(params),
    },
  );

  const { consultaId } = await exec.json();

  // 2. Polling até completar
  for (let i = 0; i < 15; i++) {
    await new Promise((r) => setTimeout(r, 2000));

    const poll = await fetch(
      `https://api.sollosconsultas.com.br/consultas/resultado/${consultaId}`,
      { headers: { "x-access-token": token } },
    );

    const resultado = await poll.json();

    if (resultado.status === "completed") return resultado.resultados;
    if (resultado.status === "failed") throw new Error(resultado.error);
  }

  throw new Error("Timeout: consulta não concluída em 30 segundos");
}

// Uso
const dados = await executarConsulta(token, 1, { cpf: "12345678900" });
console.log(dados);

Authorizations

​
x-access-token
string
header
required

Token JWT retornado pelo endpoint POST /auth/login. Inclua este header em todas as requisições autenticadas.

Path Parameters

​
id
integer
required

ID da consulta a ser executada. Obtenha via GET /consultas.

Body

application/json

Parâmetros da consulta. Os campos e suas obrigatoriedades variam por consulta — verifique em GET /consultas/{id}.

Mapa de parâmetros da consulta. Envie apenas os campos definidos para esta consulta.

Response

Consulta executada com sucesso. O campo resultados contém a resposta completa do provedor.

​
status
enum<string>
Available options:
completed
Example:

"completed"

​
query_execution
integer

ID do registro permanente desta execução. Use em GET /consultas/logs/details/{id} para recuperar o resultado futuramente.

Example:

4201

​
data_execucao
string

Data e hora da execução no fuso de Brasília

Example:

"10/04/2026 14:32:00"

​
resultados
object

Dados retornados pelo provedor. A estrutura varia de acordo com o tipo de consulta executada.