---
title: 5.1. Roteiro — Consulta SCR ponta a ponta
url: https://docs.vehub.com.br/Emiss%C3%A3o%20de%20Ativos/API/Bureau/5.%20Roteiros/5.1.%20Roteiro%20-%20Consulta%20SCR%20ponta%20a%20ponta/
---
# 5.1. Roteiro — Consulta SCR ponta a ponta

Roteiro completo de uma consulta ao SCR, da autenticação à leitura dos meses.

**Cenário:** pessoa física, consulta de março e abril de 2026, aceite coletado pelo seu sistema às
09:58 (horário de Brasília) do dia da consulta, webhook configurado para o grupo econômico.

!!! danger "Este roteiro pode gerar custo em homologação"
    O passo 4 solicita uma consulta real ao SCR, que pode ser cobrada também em homologação. Rode-o com um
    documento combinado com o nosso time. O documento `12345678900` dos exemplos é fictício e tem
    dígito verificador inválido: copiado como está, a solicitação é recusada com `400` e nada é cobrado.

---

## Visão geral

```mermaid
flowchart TD
    A[1. Autenticar] --> B[2. Conferir bureaus habilitados]
    B --> C[3. Coletar o aceite do titular]
    C --> D[4. Solicitar a consulta]
    D --> E{5. Webhook recebido?}
    E -- Sim --> F[6. Ler a consulta]
    E -- Não --> G[5b. Polling]
    G --> F
    F --> H{Status}
    H -- Concluída --> I[7. Ler os meses]
    H -- Falha --> J[8. Tratar a falha]
    I --> K{Meses em Falha?}
    K -- Sim --> J
```

---

## 1. Autenticar

```bash
export API="https://api.dev.vehub.com.br/public/v1"
export GE="MeuGrupo"

curl -X POST "$API/auth/login" \
  -H "Content-Type: application/json" \
  -d '{ "clientId": "seu-client-id", "clientSecret": "seu-client-secret" }'
```

Guarde o `access_token` e reaproveite-o até expirar. Nos passos seguintes, `$TOKEN` e `$GE`
representam o token e o grupo econômico. Em produção, troque `$API` por
`https://api.vehub.com.br/public/v1`.

---

## 2. Conferir bureaus habilitados

```bash
curl "$API/bureaus/habilitados" -H "Authorization: Bearer $TOKEN" -H "GrupoEconomico: $GE"
```

A resposta precisa conter `{ "id": 1, "nome": "SCR" }`. Lista vazia ⇒ o SCR não está habilitado para o
grupo: fale com o nosso time antes de seguir. `403` ⇒ a credencial não está vinculada ao grupo.

---

## 3. Coletar o aceite do titular

No seu canal de atendimento, colete a autorização do titular para a consulta ao SCR e guarde a
evidência. Anote:

- o **momento** do aceite, com fuso horário (ex.: `2026-10-23T09:58:00-03:00`);
- o **identificador** da evidência no seu sistema (ex.: `termo-scr-v3:77812`);
- o **identificador** da análise que motivou a consulta (ex.: `analise-2026-000123`), que será a
  `referenciaExterna`.

Nenhum desses identificadores pode conter dado pessoal. Ver
[1.2. Conceitos](../1.%20Início/1.2.%20Conceitos.md#aceite-do-titular).

---

## 4. Solicitar a consulta

Gere a `Idempotency-Key` **antes** da primeira tentativa e guarde-a junto da análise:

```bash
export CHAVE="$(uuidgen)"

curl -X POST "$API/bureaus/scr/consultas" \
  -H "Authorization: Bearer $TOKEN" -H "GrupoEconomico: $GE" \
  -H "Idempotency-Key: $CHAVE" \
  -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"
  }'
```

Responde `202` com o `idConsulta` (`98765`) e `consultarEm` (`30`). Se a chamada der *timeout*,
repita **com a mesma `$CHAVE` e o mesmo corpo**: a API devolve a consulta já criada, sem custo novo.

Se você perdeu a chave, procure a consulta antes de solicitar de novo:

```bash
curl "$API/bureaus/scr/consultas?referenciaExterna=analise-2026-000123" \
  -H "Authorization: Bearer $TOKEN" -H "GrupoEconomico: $GE"
```

---

## 5. Aguardar o desfecho

O caminho principal é o webhook. Ao terminar, a consulta gera um destes eventos na URL configurada:

```json
{
  "idWebhook": "019e0896-1a2b-7c3d-8e4f-5a6b7c8d9e01",
  "tipoEvento": "bureau.scr.concluida",
  "dataHora": "2026-10-23T13:00:41.512Z",
  "grupoEconomico": "MeuGrupo",
  "dados": {
    "idConsulta": 98765,
    "status": { "id": 3, "nome": "Concluída" }
  },
  "etiquetas": null
}
```

Valide a assinatura, deduplique pelo `idWebhook`, responda `2xx` e siga para o passo 6. Ver
[4.2. Eventos de Consulta SCR](../4.%20Notificações%20-%20WebHook/4.2.%20Eventos%20de%20Consulta%20SCR.md).

### 5b. Sem webhook: *polling*

Aguarde `consultarEm` segundos e leia a consulta a cada 30 segundos nos primeiros 5 minutos; depois,
a cada 5 minutos até 1 hora; depois, a cada 30 minutos até 24 horas. Pare quando o `status` for `3`
ou `4`. Ver [1.3. Operações Assíncronas](../1.%20Início/1.3.%20Operações%20Assíncronas.md).

---

## 6. Ler a consulta

```bash
curl "$API/bureaus/scr/consultas/98765" -H "Authorization: Bearer $TOKEN" -H "GrupoEconomico: $GE"
```

Verifique, nesta ordem:

1. `status.id` — `3` Concluída ou `4` Falha;
2. `resumo.quantidadePeriodosComFalha` — quantos meses não têm resultado;
3. `motivoFalha` — preenchido quando a consulta está em `Falha`.

---

## 7. Ler os meses

Para cada item de `periodos` com `status.id = 3`, leia os `indicadores` pelo `codigoIndicador`, as
`modalidades` e as `mensagens`. Um indicador ausente significa "sem valor", não zero. Ver
[2.2. Dicionário de Indicadores SCR](../2.%20Enumerações/2.2.%20Dicionário%20de%20Indicadores%20SCR.md).

Guarde o resultado no seu sistema com o mesmo sigilo exigido pelo dado: acesso restrito e nada em log.

---

## 8. Tratar a falha

- **Mês em falha numa consulta `Concluída`:** veja `periodos[].motivoFalha.codigo`. Para
  `PROVEDOR_INDISPONIVEL`, solicite mais tarde uma nova consulta **só com aquele mês** — com uma
  `Idempotency-Key` nova, porque é uma consulta nova, que pode ter custo próprio.
- **Consulta em `Falha`:** decida pelo `motivoFalha.codigo` — ver
  [2.1. Enumerações](../2.%20Enumerações/2.1.%20Enumerações.md). `NAO_DESPACHADA` não gerou custo;
  `ERRO_INTERNO` pede contato com o suporte, informando o `idConsulta`.

---

## Checklist de integração

- [ ] Token reaproveitado, não solicitado a cada chamada
- [ ] `GET /bureaus/habilitados` conferido antes de oferecer a consulta
- [ ] Aceite do titular coletado, com a evidência guardada no seu sistema e o momento real enviado em `dataAceiteTitular`
- [ ] Uma `Idempotency-Key` por consulta, repetida com o mesmo corpo em toda nova tentativa
- [ ] Consulta procurada pela `referenciaExterna` antes de gerar uma chave nova depois de um *timeout*
- [ ] Nenhum dado pessoal em `referenciaExterna`, `referenciaAceite`, URL ou log
- [ ] Webhooks com assinatura validada e deduplicação por `idWebhook`
- [ ] Disparos de teste (`etiquetas.isTeste = "true"`) ignorados no processamento real
- [ ] *Polling* como plano B para consultas sem evento
- [ ] Meses em `Falha` tratados mesmo em consultas `Concluída`
- [ ] `motivoFalha.codigo` usado para decidir, nunca o texto da `descricao`
- [ ] Consultas em homologação feitas só com documentos combinados — **elas podem ter custo**