3.4. Listar Consultas¶

Endpoint¶

Método	URL
	`/bureaus/scr/consultas`

Descrição¶

Lista, de forma paginada, as consultas ao SCR solicitadas pela sua credencial, da mais recente para a mais antiga.

É a rota de reconciliação: se você perdeu um idConsulta — um timeout na solicitação, por exemplo —, é aqui que o reencontra, filtrando pela referenciaExterna que enviou. Procurar antes de solicitar de novo evita uma segunda consulta e um segundo custo.

A listagem traz o resumo de cada consulta, sem os períodos. Para o resultado, use 3.3. Consultar Resultado.

Query Parameters¶

Parâmetro	Tipo	Descrição
pagina	integer	Página, começando em `1`. Padrão `1`
quantidade	integer	Registros por página, de `1` a `100`. Padrão `10`
idsStatus	integer (repetível)	Filtra pelo status da consulta (`1` a `4`). Repita o parâmetro para mais de um: `idsStatus=3&idsStatus=4`
criadaDe	string	Consultas registradas a partir deste instante, inclusive. ISO 8601 em UTC (ex.: `2026-10-01T00:00:00Z`)
criadaAte	string	Consultas registradas até este instante, inclusive. ISO 8601 em UTC. Não pode ser anterior a `criadaDe`
referenciaExterna	string	Consultas com exatamente esta referência

As datas de criação são comparadas em UTC, com precisão de microssegundos. Para um dia inteiro no horário de Brasília, converta os limites: o dia 23/10/2026 em Brasília vai de 2026-10-23T03:00:00Z a 2026-10-24T02:59:59.999999Z. Sem as frações no limite final, uma consulta registrada no último segundo do dia fica de fora.

Por que não há filtro por documento

Os parâmetros de consulta (query string) ficam registrados em logs de acesso ao longo do caminho da requisição. Para que o CPF ou CNPJ do titular nunca apareça em uma URL, a listagem não aceita o documento como filtro. Correlacione as consultas pela referenciaExterna, que é um identificador do seu sistema.

Exemplo de cURL¶

curl -X GET "https://api.vehub.com.br/public/v1/bureaus/scr/consultas?pagina=1&quantidade=2&criadaDe=2026-10-01T00:00:00Z" \
  -H "Authorization: Bearer {seu_token}" \
  -H "GrupoEconomico: {seu_grupo_economico}"

Para reencontrar uma consulta pela sua referência:

curl -X GET "https://api.vehub.com.br/public/v1/bureaus/scr/consultas?referenciaExterna=analise-2026-000123" \
  -H "Authorization: Bearer {seu_token}" \
  -H "GrupoEconomico: {seu_grupo_economico}"

Responses¶

200 OK¶

{
  "registros": [
    {
      "idConsulta": 98770,
      "referenciaExterna": "analise-2026-000130",
      "documento": "12345678900",
      "mesInicial": "2026-03",
      "mesFinal": "2026-04",
      "status": { "id": 4, "nome": "Falha" },
      "motivoFalha": {
        "codigo": "PARAMETROS_RECUSADOS",
        "descricao": "O provedor do SCR recusou os parâmetros da consulta. Revise o período e o aceite do titular e faça uma nova consulta."
      },
      "dataSolicitacao": "2026-10-23T13:10:15Z",
      "dataConclusao": "2026-10-23T13:10:19Z",
      "quantidadePeriodos": 0,
      "quantidadePeriodosComFalha": 0
    },
    {
      "idConsulta": 98765,
      "referenciaExterna": "analise-2026-000123",
      "documento": "12345678900",
      "mesInicial": "2026-03",
      "mesFinal": "2026-04",
      "status": { "id": 3, "nome": "Concluída" },
      "motivoFalha": null,
      "dataSolicitacao": "2026-10-23T13:00:02.418093Z",
      "dataConclusao": "2026-10-23T13:00:41Z",
      "quantidadePeriodos": 2,
      "quantidadePeriodosComFalha": 1
    }
  ],
  "paginacao": {
    "paginaAtual": 1,
    "paginaTotal": 14,
    "paginaQuantidadeRegistro": 2,
    "quantidadeRegistros": 27,
    "temPaginaAnterior": false,
    "temProximaPagina": true
  },
  "mensagem": null
}

`registros[]`¶

Campo	Tipo	Descrição
idConsulta	integer	Identificador da consulta
referenciaExterna	string / null	A referência informada na solicitação
documento	string	CPF ou CNPJ consultado, sem pontuação
mesInicial / mesFinal	string	Intervalo solicitado, `yyyy-MM`
status	object	Status da consulta
motivoFalha	object / null	Motivo da falha (`codigo` e `descricao`). `null` fora da falha
dataSolicitacao	string	Quando a consulta foi registrada, em UTC
dataConclusao	string / null	Quando a consulta terminou, em UTC. `null` em processamento
quantidadePeriodos	integer	Quantidade de meses registrados na consulta
quantidadePeriodosComFalha	integer	Quantos desses meses falharam

O envelope de paginação está descrito em 1.1.4 Padrões de Resposta. Uma página além da última responde 200 com registros vazio.

400 Bad Request¶

Intervalo de datas invertido:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "status": 400,
  "errors": [
    { "campo": "criadaAte", "mensagem": "A data final de criação não pode ser anterior à data inicial." }
  ]
}

Um idsStatus fora de 1 a 4 responde 400 no campo idsStatus, com a mensagem Informe em idsStatus apenas valores de 1 a 4., e pode vir junto do erro de criadaAte.

pagina ou quantidade fora da faixa e uma data ou um idsStatus em formato inválido (por exemplo, criadaDe=abc) são recusados antes dos demais filtros, com 400 e a mensagem padrão de validação. Não dependa do texto dessas mensagens. Na paginação, o campo vem com a inicial maiúscula: Pagina ou Quantidade.

Próximo passo¶

Para ler o resultado de uma consulta da lista, use o idConsulta em 3.3. Consultar Resultado.

Observações¶

Só aparecem as consultas da sua credencial. Consultas de outras credenciais do grupo e as feitas pela tela da plataforma não aparecem.
A referenciaExterna não é única. O filtro pode devolver mais de uma consulta — por exemplo, quando uma repetição criou uma segunda consulta depois de um erro. Confira o status e o motivoFalha de cada uma: uma consulta NAO_DESPACHADA não gerou custo.
A ordem é sempre da consulta mais recente para a mais antiga (idConsulta decrescente) e não pode ser alterada.