Ir para o conteúdo

4.2. Eventos de Consulta SCR

Eventos disparados quando uma consulta ao SCR solicitada pela API chega a um status terminal. Não há evento para Pendente nem para Processando.

O envelope, os headers, a assinatura HMAC e a política de retry estão em 4.1. Visão Geral.

bureau.scr.concluida

Disparado quando a consulta termina 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 — e o evento não diz quantos.

Payload

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

bureau.scr.falhou

Disparado quando a consulta termina em Falha, por qualquer motivo: nenhum mês teve resultado, o provedor do SCR recusou a consulta ou ela não chegou a ser enviada (NAO_DESPACHADA, sem custo).

Payload

{
  "idWebhook": "019e0897-2b3c-7d4e-9f50-6b7c8d9e0f12",
  "tipoEvento": "bureau.scr.falhou",
  "dataHora": "2026-10-23T13:10:19.204Z",
  "grupoEconomico": "MeuGrupo",
  "dados": {
    "idConsulta": 98770,
    "status": { "id": 4, "nome": "Falha" }
  },
  "etiquetas": null
}

O motivo da falha não vem no evento: leia motivoFalha na consulta.

Detalhamento dos Campos — dados

Campo Tipo Descrição
idConsulta integer A consulta que terminou. Leia-a em 3.3. Consultar Resultado
status object O status terminal: { "id": 3, "nome": "Concluída" } ou { "id": 4, "nome": "Falha" }

Os dois eventos têm o mesmo formato de dados. O evento não leva o documento, o período, a referenciaExterna, o motivo da falha nem o resultado: ele fica registrado nos logs de disparo, que qualquer credencial do grupo pode consultar.

O que fazer ao receber

Observações

  • Concluída não garante todos os meses. Leia o GET e confira resumo.quantidadePeriodosComFalha e o status de cada período.
  • O evento pode chegar antes da resposta do POST. Se o idConsulta ainda não está no seu sistema, leia a consulta: a referenciaExterna dela mostra a que análise pertence.
  • Evento de um idConsulta desconhecido também acontece quando uma repetição depois de um 500 criou uma segunda consulta: a primeira termina como NAO_DESPACHADA, sem custo, e pode ser ignorada. Correlacione sempre pelo idConsulta.
  • 404 na leitura indica uma consulta de outra credencial do seu grupo — a configuração do webhook vale para o grupo inteiro.
  • Retirada da habilitação. Se o SCR deixar de estar habilitado para o grupo com consultas em andamento, os eventos ainda chegam, mas a leitura responde 403. Ver 1.1.1 Acesso aos Serviços.
  • Falha de entrega não reenvia. Depois das 5 tentativas, recupere o desfecho pelo polling. O diagnóstico das tentativas está em GET /webhooks/{idWebhook}/disparos.