---
title: 3.2. Solicitar Consulta
url: https://docs.vehub.com.br/Emiss%C3%A3o%20de%20Ativos/API/Bureau/3.%20Consulta%20SCR/3.2.%20Solicitar%20Consulta/
---
# 3.2. Solicitar Consulta

## Endpoint

| Método | URL |
|--------|-----|
| ![POST](https://img.shields.io/badge/POST-blue) | `/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](3.3.%20Consultar%20Resultado.md) ou avisado por
[webhook](../4.%20Notificações%20-%20WebHook/4.2.%20Eventos%20de%20Consulta%20SCR.md).

!!! danger "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](../1.%20Início/1.2.%20Conceitos.md#cobranca).

### 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

```json
{
  "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](3.4.%20Listar%20Consultas.md). 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` |

!!! info "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

```bash
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

```json
{
  "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:

```http
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](3.4.%20Listar%20Consultas.md).

### 400 Bad Request — sem `Idempotency-Key`

```json
{
  "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)

```json
{
  "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)

```json
{
  "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

```json
{
  "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](../1.%20Início/1.1.%20Primeiros%20Passos.md#115-estrutura-de-erros).

### 409 Conflict — primeira execução em andamento

```json
{
  "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`.

```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

```json
{
  "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:

```bash
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](3.3.%20Consultar%20Resultado.md) e
[1.3. Operações Assíncronas](../1.%20Início/1.3.%20Operações%20Assíncronas.md).

---

## 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](3.4.%20Listar%20Consultas.md).
- **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](../4.%20Notificações%20-%20WebHook/4.2.%20Eventos%20de%20Consulta%20SCR.md).