3.2. Solicitar Consulta¶

Endpoint¶

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

Descrição¶

Solicita uma consulta ao SCR para um titular (CPF ou CNPJ) e um intervalo de meses. A consulta é assíncrona: a resposta 202 confirma o registro e traz o idConsulta; o resultado é lido depois em 3.3. Consultar Resultado ou avisado por webhook.

Cada solicitação aceita pode gerar custo

Cada resposta 202 nova é uma consulta nova e pode gerar custo, conforme os meses consultados com sucesso — inclusive em homologação e mesmo que o documento e o período repitam uma consulta anterior. Uma consulta encerrada como NAO_DESPACHADA não gera custo. Use a Idempotency-Key em toda solicitação e leia o resultado pelo GET em vez de solicitar de novo. Ver 1.2. Conceitos.

Headers¶

Header	Obrigatório	Descrição
`Authorization`	Sim	`Bearer {seu_token}`
`GrupoEconomico`	Sim	Nome do grupo econômico
`Idempotency-Key`	Sim	Identificador único da consulta, gerado por você (UUID v4 recomendado), até 200 caracteres. Sem ele, a API responde `400` e nada é executado
`Content-Type`	Sim	`application/json`

Requisição¶

Payload¶

{
  "documento": "12345678900",
  "mesInicial": "2026-03",
  "mesFinal": "2026-04",
  "declaracaoAceiteTitular": true,
  "dataAceiteTitular": "2026-10-23T09:58:00-03:00",
  "referenciaAceite": "termo-scr-v3:77812",
  "referenciaExterna": "analise-2026-000123"
}

O documento 12345678900 é fictício e tem dígito verificador inválido de propósito: copiado como está, a solicitação é recusada com 400 e nada é cobrado. Substitua pelo documento de um titular que deu o aceite.

Detalhamento dos Campos¶

Campo	Tipo	Obrigatório	Regra
documento	string	Sim	CPF com 11 dígitos ou CNPJ com 14 caracteres (o CNPJ alfanumérico é aceito), sem pontuação. O dígito verificador é validado. Letras são convertidas para maiúsculas
mesInicial	string	Sim	Primeiro mês, `yyyy-MM`. Não pode ser anterior a 24 meses antes do mês corrente
mesFinal	string	Sim	Último mês, `yyyy-MM`, igual ou posterior a `mesInicial`. Não pode ser posterior ao mês corrente (horário de Brasília)
declaracaoAceiteTitular	boolean	Sim	A sua declaração de que o titular autorizou a consulta. Precisa ser `true`
dataAceiteTitular	string	Sim	Momento do aceite em ISO 8601 com fuso (`Z` ou `±hh:mm`). Não pode ser posterior ao momento da requisição nem anterior a 30 dias antes dela
referenciaAceite	string	Não	Identificador da evidência do aceite no seu sistema. De 1 a 100 caracteres entre letras, dígitos e `. _ : / -`. Não pode conter o documento
referenciaExterna	string	Não	Identificador da consulta no seu sistema, para reencontrá-la na listagem. Mesma regra da `referenciaAceite`. Não é única: a API não recusa uma referência repetida

O intervalo de mesInicial a mesFinal tem no máximo 12 meses. Um intervalo que termina no mês corrente é aceito, mas o mês corrente pode voltar sem resultado.

Formato de `dataAceiteTitular`¶

Valor	Resultado
`2026-10-23T09:58:00-03:00`	Aceito
`2026-10-23T12:58:00Z`	Aceito (o mesmo instante, em UTC)
`2026-10-23T09:58:00.250-03:00`	Aceito (com frações de segundo)
`2026-10-23T09:58:00`	`400`: falta o fuso horário
`2026-10-23`	`400`: falta a hora e o fuso

O instante é gravado em UTC e devolvido na leitura como aceiteTitular.dataAceite.

Ordem de avaliação¶

A API avalia a requisição nesta ordem e responde no primeiro problema encontrado:

Ordem	Verificação	Resposta
1	Token válido e header `GrupoEconomico` presente	`401`
2	Credencial vinculada ao grupo econômico	`403`
3	`Content-Type` do corpo é JSON	`415`
4	SCR habilitado para o grupo econômico	`403`
5	Formato do corpo: JSON válido, tipos, campos obrigatórios, formatos de documento, mês e data, mês inicial não posterior ao final, aceite `true`, referências	`400` por campo
6	`Idempotency-Key`: presença, tamanho, repetição	`400`, repetição da resposta original, `409` ou `422`
7	Solicitação de novas consultas disponível	`403`
8	Regras de negócio: dígito verificador, limites do período, janela do aceite, referência com o documento	`400` por campo
9	Consulta registrada	`202`

A validação acontece em duas fases

Os erros de formato (etapa 5), inclusive o do mês inicial posterior ao final, voltam todos juntos, mas antes das regras de negócio (etapa 8). Uma requisição com o mês mal formatado e o dígito verificador errado recebe primeiro só o erro de formato; corrigido o formato, a próxima tentativa recebe o erro do dígito verificador. Prepare-se para até duas idas.

Como a chave de idempotência só é registrada depois da etapa 5, uma requisição com o corpo mal formatado não consome a chave.

Exemplo de cURL¶

curl -X POST "https://api.vehub.com.br/public/v1/bureaus/scr/consultas" \
  -H "Authorization: Bearer {seu_token}" \
  -H "GrupoEconomico: {seu_grupo_economico}" \
  -H "Idempotency-Key: 8f14e45f-ea4f-4e2c-9c3e-9b1a72d0c5f1" \
  -H "Content-Type: application/json" \
  -d '{
    "documento": "12345678900",
    "mesInicial": "2026-03",
    "mesFinal": "2026-04",
    "declaracaoAceiteTitular": true,
    "dataAceiteTitular": "2026-10-23T09:58:00-03:00",
    "referenciaAceite": "termo-scr-v3:77812",
    "referenciaExterna": "analise-2026-000123"
  }'

Responses¶

202 Accepted¶

{
  "idConsulta": 98765,
  "referenciaExterna": "analise-2026-000123",
  "status": { "id": 1, "nome": "Pendente" },
  "consultarEm": 30
}

Campo	Tipo	Descrição
idConsulta	integer	Identificador da consulta. Guarde: ele endereça a leitura e chega nas notificações
referenciaExterna	string / null	A referência informada na solicitação
status	object	Sempre `{ "id": 1, "nome": "Pendente" }` na criação
consultarEm	integer	Segundos sugeridos antes da primeira leitura

A resposta não traz o documento consultado.

202 Accepted — repetição da mesma chave¶

Mesma Idempotency-Key e mesmo corpo de uma solicitação já concluída, dentro de 24 horas: a API devolve a resposta original, sem nova consulta e sem novo custo, com o header:

Idempotent-Replay: true

O corpo é o da primeira resposta — com o status Pendente daquele momento. Para o status atual, leia a consulta.

Depois de 24 horas, a mesma chave é tratada como uma chave nova: a solicitação cria uma consulta nova, com custo novo. Antes de repetir uma solicitação antiga, procure a consulta pela referenciaExterna em 3.4. Listar Consultas.

400 Bad Request — sem `Idempotency-Key`¶

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "status": 400,
  "errors": [
    { "campo": "Idempotency-Key", "mensagem": "O header Idempotency-Key é obrigatório nesta rota. Gere uma chave nova (recomendamos um UUID v4) para cada operação e repita a mesma chave só para refazer a mesma operação." }
  ]
}

400 Bad Request — formato do corpo (etapa 5)¶

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "status": 400,
  "errors": [
    { "campo": "mesInicial", "mensagem": "O mês inicial deve ser anterior ou igual ao mês final." },
    { "campo": "dataAceiteTitular", "mensagem": "Informe a data e a hora do aceite com o fuso horário, no formato ISO 8601." },
    { "campo": "declaracaoAceiteTitular", "mensagem": "É obrigatório declarar a autorização do titular para consultar o SCR." }
  ]
}

400 Bad Request — regras de negócio (etapa 8)¶

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "status": 400,
  "errors": [
    { "campo": "documento", "mensagem": "CPF inválido. Verifique os dígitos informados." },
    { "campo": "mesInicial", "mensagem": "O mês inicial não pode ser anterior a 2024-10 (24 meses retroativos)." },
    { "campo": "dataAceiteTitular", "mensagem": "A data do aceite do titular não pode ser posterior ao momento da requisição." },
    { "campo": "referenciaExterna", "mensagem": "A referência não pode conter o documento do titular." }
  ]
}

403 Forbidden — SCR não habilitado¶

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.4",
  "status": 403,
  "errors": [
    { "campo": null, "mensagem": "O Bureau/Consulta SCR não está habilitado para este grupo econômico." }
  ]
}

Os demais 403 (credencial sem vínculo e suspensão temporária) estão em 1.1.5 Estrutura de Erros.

409 Conflict — primeira execução em andamento¶

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.10",
  "status": 409,
  "errors": [
    { "campo": "Idempotency-Key", "mensagem": "Uma requisição com esta chave de idempotência ainda está em processamento. Aguarde e repita com a mesma chave para receber o resultado dela." }
  ]
}

415 Unsupported Media Type — corpo que não é JSON¶

Envie o corpo com Content-Type: application/json.

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.16",
  "status": 415,
  "errors": [
    { "campo": null, "mensagem": "Unsupported Media Type" }
  ]
}

422 Unprocessable Entity — chave usada com outro corpo¶

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.21",
  "status": 422,
  "errors": [
    { "campo": "Idempotency-Key", "mensagem": "Esta chave de idempotência já foi usada nesta rota com um corpo diferente. Use uma chave nova para uma operação nova." }
  ]
}

Próximo passo¶

Aguarde o evento bureau.scr.concluida ou bureau.scr.falhou, ou leia a consulta depois de consultarEm segundos:

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

Ver 3.3. Consultar Resultado e 1.3. Operações Assíncronas.

Observações¶

Uma chave por consulta. Gere a Idempotency-Key antes da primeira tentativa e repita a mesma chave, com o mesmo corpo, em toda nova tentativa daquela consulta. Uma chave nova é uma consulta nova.
Perdeu a resposta? Antes de gerar uma chave nova, procure a consulta pela referenciaExterna em 3.4. Listar Consultas.
A dataAceiteTitular é o momento real do aceite, não o momento da requisição. Não preencha com o relógio do servidor na hora de chamar a API.
Nada de dado pessoal nas referências. referenciaAceite e referenciaExterna aparecem em listagens e não podem conter o documento, nome ou e-mail do titular.
Não há cancelamento. Depois do 202, a consulta segue até Concluída ou Falha.
O evento de webhook pode chegar antes de você processar a resposta 202. Ver 4.2. Eventos de Consulta SCR.