1.3. Operações Assíncronas¶

Por que a consulta é assíncrona¶

A consulta ao SCR é executada pelo provedor do SCR, que consulta o Banco Central do Brasil mês a mês. Uma consulta de vários meses leva de segundos a alguns minutos — e, quando o provedor está instável, mais do que isso.

Por isso a solicitação não devolve o resultado na resposta. Ela devolve 202 Accepted — "recebi e vou processar" — e o resultado aparece depois, de duas formas: você consulta, ou nós avisamos.

Operação	Resposta	Como saber o resultado
Solicitar consulta	`202`	webhook ou leitura da consulta
Consultar resultado, listar consultas e bureaus habilitados	`200` síncrono	vem no corpo

O padrão: aceite, consulta, webhook¶

1. Aceite¶

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

Guarde o idConsulta: ele identifica a consulta em todas as chamadas e nas notificações. O campo consultarEm é o tempo em segundos que sugerimos aguardar antes da primeira leitura.

2. Consulta¶

GET /bureaus/scr/consultas/{idConsulta}

A leitura sempre responde 200 para uma consulta da sua credencial, inclusive quando ela ainda está em processamento ou terminou em falha. O estado está no corpo:

Campo	Para que serve
`status`	O estado da consulta — ver os estados abaixo
`emProcessamento`	`true` enquanto a consulta está `Pendente` ou `Processando`
`temErro`	`true` quando a consulta terminou em `Falha`
`motivoFalha`	O motivo da falha da consulta, com `codigo` estável — `null` fora da falha
`resumo.quantidadePeriodosComFalha`	Quantos meses falharam numa consulta `Concluída`

Não trate temErro: true como erro de HTTP

A leitura responde 200 porque a leitura funcionou. O que falhou foi a consulta ao SCR, e isso é dado, não erro de transporte. Se o seu cliente HTTP só olha o status code, ele vai concluir que deu tudo certo. Sempre inspecione status, temErro e motivoFalha.

3. Webhook¶

Quando a consulta termina, VeTrust envia uma notificação para a URL configurada para o seu grupo econômico:

Desfecho	Evento
Consulta `Concluída` (pode ter meses em falha)	`bureau.scr.concluida`
Consulta em `Falha`	`bureau.scr.falhou`

A notificação leva só o idConsulta e o status. O resultado é lido pelo GET. Ver 4.2. Eventos de Consulta SCR.

O webhook acelera, mas não substitui a leitura. Uma notificação pode não chegar — o seu servidor fora do ar, por exemplo. Mantenha o polling abaixo como plano B para toda consulta que não recebeu evento.

Estados da consulta¶

Código	Nome	O que significa para você
`1`	Pendente	Registrada, aguardando o envio ao provedor do SCR. Aguarde
`2`	Processando	Em consulta no provedor do SCR. Aguarde
`3`	Concluída	O provedor do SCR respondeu com sucesso para pelo menos um mês. Confira sempre o status de cada período: um mês pode vir em `Falha`, inclusive com `RESULTADO_ILEGIVEL`
`4`	Falha	Nenhum mês tem resultado. Veja `motivoFalha`

Concluída e Falha são terminais: a consulta não muda mais de estado.

O que fazer em cada desfecho¶

Status	`motivoFalha.codigo`	O que fazer
`3` Concluída	—	Use os períodos com status `Concluída`. Se `quantidadePeriodosComFalha` > 0, avalie refazer só os meses em falha (custo novo)
`4` Falha	`PERIODOS_SEM_RESULTADO`	Nenhum mês teve resultado. Veja `periodos[].motivoFalha` para decidir se refaz
`4` Falha	`PARAMETROS_RECUSADOS`	O provedor do SCR recusou a consulta. Revise o período e o aceite do titular antes de refazer
`4` Falha	`NAO_PROCESSADA`	Refaça a consulta; se repetir, acione o suporte
`4` Falha	`NAO_DESPACHADA`	A consulta não chegou ao provedor e não gerou custo. Refaça, se ainda precisar
`4` Falha	`ERRO_INTERNO`	Acione o suporte informando o `idConsulta`

As tabelas completas de motivos estão em 2.1. Enumerações.

Se o webhook não chegou: como fazer polling sem se machucar¶

Aguarde os consultarEm segundos (30) antes da primeira leitura.
Leia a cada 30 segundos nos primeiros 5 minutos.
Depois, a cada 5 minutos até completar 1 hora.
Depois, a cada 30 minutos até completar 24 horas.
Pare quando o status for Concluída ou Falha.

A leitura não tem custo, mas um laço agressivo sobre muitas consultas pressiona a API sem acelerar o resultado: quem define o tempo é o provedor do SCR.

Quando a consulta demora¶

Situação	O que acontece	O que fazer
`Pendente` por muito tempo	Uma consulta que não conseguiu ser enviada ao provedor do SCR é encerrada automaticamente em até cerca de 75 minutos, como `Falha` com o motivo `NAO_DESPACHADA`, sem custo, e o evento `bureau.scr.falhou` é enviado	Aguarde o encerramento e refaça, se ainda precisar
`Processando` por 30 a 60 minutos	Pode acontecer quando o provedor do SCR demora a devolver o resultado. A plataforma busca o resultado sozinha	Continue o polling. A consulta não é encerrada automaticamente nesse estado, porque pode já ter gerado custo
`Processando` por mais de 24 horas	Situação anormal	Acione o suporte informando o `idConsulta`. Não solicite uma nova consulta antes disso

Idempotência é o que torna o retry seguro¶

Numa solicitação assíncrona, timeout de rede é comum: você não sabe se a consulta foi aceita ou não. A resposta certa é repetir a chamada com a mesma Idempotency-Key e o mesmo corpo — a API devolve a consulta já criada em vez de criar uma segunda, com um segundo custo.

POST /bureaus/scr/consultas
Idempotency-Key: 8f14e45f-ea4f-4e2c-9c3e-9b1a72d0c5f1

Como ler a resposta da repetição:

202 com o header Idempotent-Replay: true: a consulta já tinha sido registrada. Use o idConsulta devolvido. O corpo é o da primeira resposta (status Pendente): para o status atual, leia a consulta.
409 com campo igual a Idempotency-Key: a primeira chamada com esta chave ainda está em processamento. Aguarde e repita com a mesma chave.
422 com campo igual a Idempotency-Key: a chave já foi usada com um corpo diferente. Não repita: gere uma chave nova para a consulta nova.
500: repita com a mesma chave.

Correlacione pelo idConsulta. A referenciaExterna não é única: depois de um 500, a repetição pode criar uma segunda consulta com a mesma referência, e a primeira termina como NAO_DESPACHADA, sem custo. Se chegar um evento de um idConsulta que você não conhece, leia a consulta: a referenciaExterna mostra a que análise ela pertence, e uma NAO_DESPACHADA pode ser ignorada.

Todos os desfechos estão em 1.1.7 Idempotência.