3.3. Consultar Resultado¶

Endpoint¶

Método	URL
	`/bureaus/scr/consultas/{idConsulta}`

Descrição¶

Devolve o estado e o resultado de uma consulta ao SCR solicitada pela sua credencial. É a mesma rota para acompanhar o processamento e para ler o resultado: ela responde 200 em qualquer status — inclusive quando a consulta ainda está em andamento ou terminou em falha.

Ler o resultado não tem custo: repita a leitura quantas vezes precisar.

Path Parameter¶

Parâmetro	Tipo	Descrição
idConsulta	integer	Identificador devolvido em 3.2. Solicitar Consulta

Headers¶

Apenas os headers padrão (Authorization e GrupoEconomico).

Exemplo de cURL¶

curl -X GET "https://api.vehub.com.br/public/v1/bureaus/scr/consultas/98765" \
  -H "Authorization: Bearer {seu_token}" \
  -H "GrupoEconomico: {seu_grupo_economico}"

Responses¶

200 OK — consulta concluída¶

Consulta de dois meses: março com resultado e abril em falha.

{
  "idConsulta": 98765,
  "referenciaExterna": "analise-2026-000123",
  "documento": "12345678900",
  "mesInicial": "2026-03",
  "mesFinal": "2026-04",
  "status": { "id": 3, "nome": "Concluída" },
  "emProcessamento": false,
  "temErro": false,
  "motivoFalha": null,
  "aceiteTitular": {
    "dataAceite": "2026-10-23T12:58:00Z",
    "referenciaAceite": "termo-scr-v3:77812"
  },
  "dataSolicitacao": "2026-10-23T13:00:02.418093Z",
  "dataConclusao": "2026-10-23T13:00:41Z",
  "resumo": {
    "quantidadePeriodos": 2,
    "quantidadePeriodosConcluidos": 1,
    "quantidadePeriodosComFalha": 1
  },
  "periodos": [
    {
      "periodo": "2026-03",
      "status": { "id": 3, "nome": "Concluída" },
      "motivoFalha": null,
      "percentualDocumentosProcessados": 98.5,
      "percentualVolumeProcessado": 99.1,
      "quantidadeInstituicoes": 3,
      "quantidadeOperacoes": 7,
      "indicadores": [
        { "codigoIndicador": "carteira_vencer", "valor": 15234.56 },
        { "codigoIndicador": "carteira_vencer_31a60", "valor": 1270.00 },
        { "codigoIndicador": "limite_credito", "valor": 8000.00 },
        { "codigoIndicador": "responsabilidade_total", "valor": 15234.56 },
        { "codigoIndicador": "risco_total", "valor": 23234.56 }
      ],
      "modalidades": [
        { "tipo": "A", "modalidade": "02", "dominio": "01", "subdominio": "10", "valorVencimento": 1000.00 }
      ],
      "mensagens": [
        { "codigo": "M01", "mensagem": "Exemplo fictício de mensagem do SCR." }
      ]
    },
    {
      "periodo": "2026-04",
      "status": { "id": 4, "nome": "Falha" },
      "motivoFalha": {
        "codigo": "PROVEDOR_INDISPONIVEL",
        "descricao": "O provedor do SCR não respondeu para este mês. Refaça a consulta deste mês."
      },
      "percentualDocumentosProcessados": null,
      "percentualVolumeProcessado": null,
      "quantidadeInstituicoes": null,
      "quantidadeOperacoes": null,
      "indicadores": [],
      "modalidades": [],
      "mensagens": []
    }
  ]
}

200 OK — em processamento¶

Logo depois da solicitação, a consulta aparece Pendente ou Processando, sem períodos:

{
  "idConsulta": 98765,
  "referenciaExterna": "analise-2026-000123",
  "documento": "12345678900",
  "mesInicial": "2026-03",
  "mesFinal": "2026-04",
  "status": { "id": 2, "nome": "Processando" },
  "emProcessamento": true,
  "temErro": false,
  "motivoFalha": null,
  "aceiteTitular": {
    "dataAceite": "2026-10-23T12:58:00Z",
    "referenciaAceite": "termo-scr-v3:77812"
  },
  "dataSolicitacao": "2026-10-23T13:00:02.418093Z",
  "dataConclusao": null,
  "resumo": {
    "quantidadePeriodos": 0,
    "quantidadePeriodosConcluidos": 0,
    "quantidadePeriodosComFalha": 0
  },
  "periodos": []
}

200 OK — consulta em falha¶

A consulta foi recusada antes de qualquer mês ser consultado:

{
  "idConsulta": 98770,
  "referenciaExterna": "analise-2026-000130",
  "documento": "12345678900",
  "mesInicial": "2026-03",
  "mesFinal": "2026-04",
  "status": { "id": 4, "nome": "Falha" },
  "emProcessamento": false,
  "temErro": true,
  "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."
  },
  "aceiteTitular": {
    "dataAceite": "2026-10-23T12:58:00Z",
    "referenciaAceite": null
  },
  "dataSolicitacao": "2026-10-23T13:10:15Z",
  "dataConclusao": "2026-10-23T13:10:19Z",
  "resumo": {
    "quantidadePeriodos": 0,
    "quantidadePeriodosConcluidos": 0,
    "quantidadePeriodosComFalha": 0
  },
  "periodos": []
}

Detalhamento dos Campos¶

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 — ver 2.1. Enumerações
emProcessamento	boolean	`true` enquanto o status é `1` Pendente ou `2` Processando
temErro	boolean	`true` quando o status é `4` Falha
motivoFalha	object / null	Motivo da falha da consulta (`codigo` e `descricao`). `null` fora da falha
aceiteTitular.dataAceite	string	O momento do aceite informado na solicitação, em UTC
aceiteTitular.referenciaAceite	string / null	A referência do aceite informada na solicitação
dataSolicitacao	string	Quando a consulta foi registrada, em UTC
dataConclusao	string / null	Quando a consulta chegou a `Concluída` ou `Falha`, em UTC. `null` em processamento
resumo.quantidadePeriodos	integer	Quantidade de itens em `periodos`
resumo.quantidadePeriodosConcluidos	integer	Quantos desses meses têm resultado (status `3`)
resumo.quantidadePeriodosComFalha	integer	Quantos desses meses falharam (status `4`)
periodos	array	Um item por mês consultado. Vazio enquanto a consulta está em processamento e quando ela falha antes de consultar os meses

`periodos[]`¶

Campo	Tipo	Descrição
periodo	string	O mês, `yyyy-MM`
status	object	`3` Concluída ou `4` Falha
motivoFalha	object / null	Motivo da falha do mês (`codigo` e `descricao`). `null` quando o mês tem resultado
percentualDocumentosProcessados	number / null	Abrangência do mês no SCR. `null` em mês com falha
percentualVolumeProcessado	number / null	Abrangência do volume no SCR. `null` em mês com falha
quantidadeInstituicoes	integer / null	Instituições com operações do titular no mês
quantidadeOperacoes	integer / null	Operações do titular no mês
indicadores	array	Pares `{ codigoIndicador, valor }`. Vazio em mês com falha
modalidades	array	Operações por modalidade `{ tipo, modalidade, dominio, subdominio, valorVencimento }`
mensagens	array	Mensagens do mês `{ codigo, mensagem }`

O significado de cada indicador, modalidade e mensagem está em 2.2. Dicionário de Indicadores SCR.

404 Not Found¶

A consulta não existe para a sua credencial:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
  "status": 404,
  "errors": [
    { "campo": null, "mensagem": "Consulta SCR não encontrada." }
  ]
}

A resposta é a mesma quando o idConsulta é de outra credencial (mesmo do seu grupo), de outro grupo econômico, de uma consulta feita pela tela da plataforma ou simplesmente não existe.

403 Forbidden¶

O SCR não está habilitado para o grupo econômico — ver 1.1.5 Estrutura de Erros.

Próximo passo¶

status 1 ou 2: aguarde o webhook ou continue o polling — ver 1.3. Operações Assíncronas.
status 3: use os meses com resultado. Se resumo.quantidadePeriodosComFalha for maior que zero, decida, pelo motivoFalha de cada mês, se solicita uma nova consulta só com esses meses.
status 4: decida pelo motivoFalha.codigo — ver 2.1. Enumerações.

Observações¶

Concluída não garante todos os meses. Sempre leia o status de cada período.
Indicador ausente significa "sem valor", não zero.
Ramifique pelo codigo do motivoFalha, nunca pela descricao, que é texto de exibição.
O resultado é dado pessoal sob sigilo bancário. Não grave a resposta em log nem a exiba a quem não precisa.
Uma consulta Concluída ou em Falha não muda mais: guarde o resultado no seu sistema em vez de depender de releituras futuras.