POST
/
consultas
/
executar
/
{id}
curl --request POST \
  --url https://api.periciadecredito.com.br/consultas/executar/{id} \
  --header 'Content-Type: application/json' \
  --header 'x-access-token: <api-key>' \
  --data '
{
  "cpf": "12345678900"
}
'
{
  "status": "completed",
  "success": true,
  "id": 1,
  "name": "KYC — Pessoa Física",
  "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
{
  "consulta": {
    "id": 1,
    "name": "kyc_pf",
    "display_name": "KYC — Pessoa Física",
    "parametros": [
      { "name": "cpf", "display_name": "CPF", "is_required": true }
    ]
  }
}
Com isso, você sabe que o body da execução deve conter { "cpf": "..." }. Veja todos os campos retornados em Detalhes de uma Consulta.

​
O resultado vem direto na resposta

Diferente do que você pode esperar de uma API de processamento assíncrono, não é necessário fazer polling. A requisição HTTP fica aberta enquanto a consulta é processada e a API já devolve 200 com o resultado completo: 
POST /consultas/executar/1
Content-Type: application/json
x-access-token: <seu_token>

{ "cpf": "12345678900" }
Resposta 200
{
  "status": "completed",
  "success": true,
  "id": 1,
  "name": "KYC — Pessoa Física",
  "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"]
  }
}
A maioria das consultas conclui em 1 a 3 segundos, mas alguns provedores levam mais tempo — configure o timeout do seu cliente HTTP com folga (alguns minutos).
Guarde o query_execution retornado. Ele é o ID permanente desta execução — use-o em GET /consultas/logs/details/{id} para recuperar o resultado completo a qualquer momento.

​
Consultas com múltiplos produtos

Se a consulta combina mais de um produto internamente (ex: um checklist veicular que roda restrições + gravame), resultados vem como um array, um item por produto:
Resposta 200 — múltiplos produtos
{
  "status": "completed",
  "success": true,
  "id": 9,
  "name": "Checklist Veicular",
  "query_execution": 4288,
  "data_execucao": "10/04/2026 15:02:11",
  "resultados": [
    { "product_name": "restricoes", "data": { "furto_roubo": false } },
    { "product_name": "gravame", "data": { "possui_gravame": false } }
  ]
}

​
Quando um produto falha

Se o provedor de um produto específico retornar erro, a API ainda responde com o mesmo formato do sucesso — só que com success: false e o(s) erro(s) no lugar dos dados, e o código HTTP muda para 500:
Resposta 500 — falha de negócio
{
  "status": "completed",
  "success": false,
  "id": 1,
  "name": "KYC — Pessoa Física",
  "query_execution": 4202,
  "data_execucao": "10/04/2026 14:35:00",
  "resultados": {
    "product_name": "kyc",
    "error": "Provedor retornou resposta sem dados. Tente novamente em alguns instantes.",
    "status": 502
  }
}
Em consultas com múltiplos produtos, sucessos e falhas podem aparecer misturados no mesmo array (resultados) — trate cada item pelo seu próprio data ou error. Uma falha técnica antes mesmo de chamar o provedor (ex: consulta sem produtos configurados) tem um formato mais enxuto, sem o envelope completo:
Resposta 500 — falha técnica
{
  "status": "failed",
  "error": "Essa consulta ainda não está configurada. Entre em contato com o suporte."
}

​
O caso raro: timeout (504)

Provedores excepcionalmente lentos podem ultrapassar o limite de espera do servidor. Nesse caso a API responde 504 e a execução continua rodando em segundo plano:
Resposta 504
{
  "status": "timeout",
  "consultaId": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "message": "Tempo limite excedido. O job continua rodando — use GET /consultas/resultado/:id ou GET /consultas/stream/:id para recuperar o resultado."
}
Use o consultaId retornado em GET /consultas/resultado/{consultaId} (polling) ou GET /consultas/stream/{consultaId} (SSE) para recuperar o resultado assim que estiver pronto.

​
Exemplo completo em código

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

  if (resp.status === 504) {
    const { consultaId: hash } = await resp.json();
    return aguardarViaPolling(token, hash); // fallback raro — veja /consultas/resultado
  }

  const resultado = await resp.json();

  if (resultado.success === false) {
    throw new Error(JSON.stringify(resultado.resultados));
  }

  return resultado.resultados;
}

// 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(s) provedor(es).

Envelope de uma execução concluída — devolvido tanto por POST /consultas/executar/{id} quanto por GET /consultas/resultado/{consultaId} (formato hash).

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

"completed"

​
success
boolean

true se todos os produtos da consulta retornaram dados com sucesso. false se pelo menos um produto falhou — nesse caso a resposta HTTP é 500, mas o corpo mantém este mesmo formato (resultados traz o(s) erro(s) por produto).

Example:

true

​
id
integer

ID da consulta executada (o mesmo {id} do path de POST /consultas/executar/{id})

Example:

1

​
name
string

Nome legível da consulta

Example:

"KYC — Pessoa Física"

​
query_execution
integer

ID permanente desta execução. Use em GET /consultas/logs/details/{id} ou em GET /consultas/resultado/{query_execution} para recuperar o resultado no futuro.

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(s) provedor(es). Se a consulta tem um único produto: este campo é o objeto de dados diretamente (sucesso) ou { product_name, error, status } (falha). Se a consulta tem múltiplos produtos: este campo é um array, um item por produto, cada um { product_name, data } (sucesso) ou { product_name, error, status } (falha) — misturando sucessos e falhas quando aplicável.