--- title: 3.4. Listar Consultas url: https://docs.vehub.com.br/Emiss%C3%A3o%20de%20Ativos/API/Bureau/3.%20Consulta%20SCR/3.4.%20Listar%20Consultas/ --- # 3.4. Listar Consultas ## Endpoint | Método | URL | |--------|-----| | ![GET](https://img.shields.io/badge/GET-green) | `/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](3.3.%20Consultar%20Resultado.md). ### 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. !!! info "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 ```bash 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: ```bash 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 ```json { "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](../1.%20Início/1.1.%20Primeiros%20Passos.md#114-padroes-de-resposta). Uma página além da última responde `200` com `registros` vazio. ### 400 Bad Request Intervalo de datas invertido: ```json { "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](3.3.%20Consultar%20Resultado.md). --- ## 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.