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.

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¶

1. Autenticar¶

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¶

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.

4. Solicitar a consulta¶

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

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:

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:

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

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.

6. Ler a consulta¶

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

Verifique, nesta ordem:

status.id — 3 Concluída ou 4 Falha;
resumo.quantidadePeriodosComFalha — quantos meses não têm resultado;
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.

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. NAO_DESPACHADA não gerou custo; ERRO_INTERNO pede contato com o suporte, informando o idConsulta.