# Monitoramento transacional

<https://unifokal.com/docs/modulos/transacao-monitor>

## Monitoramento transacional

! **A cobrança é por alerta emitido, e não pela varredura.** São 30 centavos por **alerta**: varrer as suas transações não custa nada, e alerta suprimido por repetição também não. É o que sustenta cobrar pelo achado em vez de cobrar pela busca.

O módulo `transacao_monitor` faz uma **varredura retrospectiva sobre as transações que você já nos mandou** pela rota de ingestão, procurando **padrões que uma transação sozinha não revela**. Ele roda no nosso relógio, sobre uma janela fechada, e ninguém fica esperando por ele: quando um padrão fecha, você recebe um **alerta** no mesmo webhook assinado de sempre, com a janela e a evidência em número.

**Disponível desde 11 de setembro de 2026.** Ele aparece na tabela de preços e no `GET /v1/capabilities` com preço e status `available`, e pode ser ligado num flow. Até essa data as duas travas eram comerciais, não técnicas: a **unidade** de cobrança e o **número**. As duas foram decididas, e a unidade é o alerta emitido, não a assinatura mensal. O **alerta nunca reprova ninguém**: o pior desfecho é revisão humana.

! **Este não é o módulo da seção acima.** O `transacao` é um **gate síncrono**: você tem um pagamento parado esperando um veredito, e a resposta vem na hora. O `transacao_monitor` é **observação no tempo**: nada está parado, a pergunta é sobre o conjunto, e o desfecho nunca é "não pague". São produtos diferentes, com preços diferentes e payloads diferentes. Ter um não dá o outro.

O campo `pattern` diz qual padrão fechou, e o seu código pode receber estes valores: `structuring`, `payee_concentration_growth`, `device_farm`, `post_approval_blocklist`, `dormant_reactivation`, `velocity_escalation` e `unverified_volume`. Receptores devem tolerar valor novo.

**A severidade tem dois valores, e só dois:** `high` e `medium`. Não existe `low`, e a ausência é decisão de produto: alerta que não muda o comportamento de ninguém é ruído cobrado.

```
// transacao_monitor no check_details: um alerta de fracionamento
{ "module": "transacao_monitor", "passed": null, "outcome": "pending", "score": 60,
  "data": {
    "transaction_monitor": {
      "pattern": "structuring",
      "severity": "high",
      "window": { "from": "2026-08-01T00:00:00Z", "to": "2026-08-08T00:00:00Z" },
      "evidence": { "tx_count": 7, "sum_cents": 6900000, "max_single_cents": 990000 }
    }
  } }
```

**Repare em `passed` e `outcome`: eles são sempre esses.** `passed` é `null` e `outcome` é `"pending"` nas **duas** severidades, sempre. A severidade viaja em `data.transaction_monitor.severity` e **nunca** em `passed`. Quem programar lendo `passed === false` como "reprovado" nunca vai entrar nesse ramo, e é exatamente essa a intenção: um `passed: false` aqui faria a verificação sair `denied` no webhook assinado, e um cliente que automatizou "denied = bloquear conta" bloquearia o titular sozinho. Leia o `pattern` e a `severity`, e trate o resto como evidência.

O campo `evidence` muda de chaves conforme o `pattern`, e ele **só carrega número**: contagem, soma em centavos e intervalo em dias. Nunca documento, nome, e-mail, chave Pix em claro nem endereço IP. O sujeito do alerta, que chega em `reference_id`, depende do `pattern`: pode ser o titular, a conta de destino ou o aparelho que o padrão observou.

! **O alerta nunca reprova ninguém, e isso é estrutural.** O pior desfecho que este módulo emite é **revisar**, em qualquer padrão e nas duas severidades: `high` e `medium` diferem no que você **lê**, não no que o motor **decide**. Quem aplica qualquer consequência sobre a conta é você.

**O que este módulo não faz.** Ele **não bloqueia nada**, como acabou de ser dito, e essa é a primeira. Ele **não consulta o DICT, o MED, bureau nem dado de consórcio entre instituições**: o universo da varredura é **só o que você nos mandou**, sob o seu próprio tenant, e nunca o histórico de outro cliente. E ele **não é o Gate transacional**, que é a seção logo acima.

**A varredura é grátis: você paga pelo alerta emitido.** Uma janela em que nenhum padrão fecha não gera verificação, não gera `check` e não custa nada, e por isso não existe um estado "limpo" neste payload: ele só nasce quando um padrão fecha. Alerta suprimido por repetição não é cobrado.

**A conta fica no painel.** Em Monitoramento você vê, no período que escolher, quantos alertas por 1.000 eventos recebidos o módulo produziu, quantos foram entregues e quantos ficaram **retidos sem cobrança**, com o motivo de cada retenção em palavras.

**Alerta de severidade alta nunca é retido.** Nem por volume, nem por falta de saldo: ele é entregue sempre, e quando sai acima do volume contratado ou sem saldo chega **sem cobrança**, com `billing.waived` dizendo o porquê: `above_volume` ou `no_credit`. Alerta cobrado normalmente não traz o bloco `billing`.

```
// data do alerta high entregue sem cobrança
{ "object": "verification", "billing": { "waived": "above_volume" },
  "check_details": [ { "module": "transacao_monitor", "passed": null, "outcome": "pending" } ] }
```