---
title: 1.3. Operações Assíncronas
url: https://docs.vehub.com.br/Emiss%C3%A3o%20de%20Ativos/API/Bureau/1.%20In%C3%ADcio/1.3.%20Opera%C3%A7%C3%B5es%20Ass%C3%ADncronas/
---
# 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](../3.%20Consulta%20SCR/3.2.%20Solicitar%20Consulta.md) | `202` | webhook ou leitura da consulta |
| [Consultar resultado](../3.%20Consulta%20SCR/3.3.%20Consultar%20Resultado.md), [listar consultas](../3.%20Consulta%20SCR/3.4.%20Listar%20Consultas.md) e [bureaus habilitados](../3.%20Consulta%20SCR/3.1.%20Bureaus%20Habilitados.md) | `200` síncrono | vem no corpo |

---

## O padrão: aceite, consulta, webhook

### 1. Aceite

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

!!! danger "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](../4.%20Notificações%20-%20WebHook/4.2.%20Eventos%20de%20Consulta%20SCR.md).

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

```mermaid
stateDiagram-v2
    state "Concluída" as Concluida
    [*] --> Pendente: solicitação aceita (202)
    Pendente --> Processando: enviada ao provedor do SCR
    Pendente --> Falha: não enviada (NAO_DESPACHADA)
    Processando --> Concluida: sucesso no provedor em pelo menos um mês
    Processando --> Falha: nenhum mês com resultado ou consulta recusada
    Concluida --> [*]
    Falha --> [*]
```

| 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](../2.%20Enumerações/2.1.%20Enumerações.md).

---

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

1. Aguarde os `consultarEm` segundos (30) antes da primeira leitura.
2. Leia a cada **30 segundos** nos primeiros **5 minutos**.
3. Depois, a cada **5 minutos** até completar **1 hora**.
4. Depois, a cada **30 minutos** até completar **24 horas**.
5. 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.

```http
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](1.1.%20Primeiros%20Passos.md#117-idempotencia).