​
Bem-vindo à API Reference

A API da Perícia de Crédito permite executar consultas de dados cadastrais, financeiros e jurídicos de forma programática. Toda a comunicação é feita via HTTP REST com respostas em application/json.

Comece pelo Login

Obtenha seu token JWT para autenticar as requisições

Execute uma Consulta

O resultado vem direto na resposta — sem polling

Recupere um Resultado

Para os casos raros de timeout (504)

Monitore o Consumo

Estatísticas de uso por período

​
Base URL

https://api.periciadecredito.com.br

​
Autenticação

Todas as rotas (exceto POST /auth/login) exigem o header abaixo: 
x-access-token: <seu_token_jwt>
O token é obtido via POST /auth/login. Sem ele, qualquer requisição retorna 401 Unauthorized.
Trate o token como uma senha. Não o exponha em repositórios públicos, variáveis de ambiente versionadas ou código client-side. Em ambientes de produção, armazene-o de forma segura (ex: secrets manager, variável de ambiente no servidor).

​
Códigos de status

CódigoSignificado
200 OKRequisição processada com sucesso
202 AcceptedResultado ainda pendente (só ocorre no polling de GET /consultas/resultado/{id})
400 Bad RequestParâmetros ausentes ou inválidos na requisição
401 UnauthorizedToken ausente, inválido ou expirado
403 ForbiddenSem permissão para este recurso ou limite de uso atingido
404 Not FoundRecurso não encontrado
410 GonePayload expirado pela política de retenção (90 dias)
500 Internal Server ErrorErro interno ou falha no provedor externo
504 Gateway TimeoutTempo limite excedido aguardando o provedor — a consulta continua rodando em segundo plano

​
Modelo de execução

POST /consultas/executar/{id} devolve o resultado diretamente na resposta — não é necessário fazer polling em fluxo normal.
1

Executar

Envie POST /consultas/executar/{id} com os parâmetros da consulta. A requisição HTTP fica aberta enquanto a consulta é processada.
2

Resultado pronto

Quando o provedor responde, a API retorna 200 com o resultado completo no campo resultados. Guarde o query_execution para recuperar o resultado futuramente em GET /consultas/logs/details/{id}.
A maioria das consultas conclui em 1 a 3 segundos, mas a requisição pode ficar aberta por mais tempo dependendo do provedor. Configure o timeout do seu cliente HTTP para pelo menos alguns minutos.

​
Se a resposta demorar demais: 504

Provedores mais lentos podem levar mais tempo do que o limite configurado no servidor. Nesse caso, a API responde 504 com um consultaId (hash) e o processamento continua em segundo plano. Recupere o resultado depois com:
  • GET /consultas/resultado/{consultaId} — polling, tente a cada 2 segundos.
  • GET /consultas/stream/{consultaId} — SSE, recebe um único evento quando o worker terminar.
Isso é a exceção, não a regra — a maior parte das integrações nunca precisa desses dois endpoints.

​
Formato de erro

Todos os erros seguem o mesmo formato: 
{
  "message": "Descrição do que deu errado."
}