> This page is for BaaS.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.api.corpx.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.api.corpx.com/_mcp/server.

# Políticas e Regras

As políticas permitem configurar regras preventivas para operações PIX. Elas são configuradas no painel (Backoffice) e avaliadas automaticamente pela API. Tudo que a tela oferece é avaliado em runtime: PIX Out, PIX In, QR Code, chaves, estorno, horário de operação e limites de DICT.

## Hierarquia de Configuração

As políticas têm dois níveis:

```
Tenant (base) -> Account (sobrescreve o tenant)
```

A resolução é por **seção**: se a conta define `pixOut`, a seção `pixOut` da conta é usada inteira, e a do tenant é ignorada. Seções não definidas na conta são herdadas do tenant. Uma seção que não existe em nenhum dos dois níveis simplesmente não é avaliada — não há um nível "default" por trás com valores implícitos.

A única exceção são os limites de DICT, que têm defaults globais da plataforma quando a policy não os define — ver [Limites de DICT Lookup](#limites-de-dict-lookup).

## Regras de PIX Out

As regras são avaliadas nesta ordem:

| Ordem | Regra                   | `rule`               | Descrição                                                                         |
| ----- | ----------------------- | -------------------- | --------------------------------------------------------------------------------- |
| 1     | **Kill Switch**         | `pixOutDisabled`     | `enabled: false` recusa toda saída. É absoluto — vence inclusive a whitelist      |
| 2     | **Whitelist**           | —                    | Documento do destinatário na whitelist: **permite e pula todas as regras abaixo** |
| 3     | **Blacklist**           | `cpfCnpjBlacklist`   | Recusa se o documento do destinatário está na blacklist                           |
| 4     | **Mesma Titularidade**  | `sameOwnershipOnly`  | Permite apenas transferências para o CPF/CNPJ do titular da conta                 |
| 5     | **Horário de Operação** | `operatingHours`     | Recusa fora da janela configurada                                                 |
| 6     | **Tipo de Pessoa**      | `allowedPersonTypes` | Restringe o destinatário a PF ou PJ (pelo tamanho do documento)                   |

Ao contrário da whitelist, que curto-circuita, as demais regras são todas avaliadas: uma transação pode violar mais de uma, e o `violations` da resposta traz todas.

### Duas fases de avaliação

O documento do destinatário nem sempre existe no momento do POST:

* **No POST** (borda): kill switch e horário. As regras de documento também, **quando** o modo é `BANK_ACCOUNT`, o único que traz `documentNumber` no corpo.
* **Depois de resolver o destinatário**: nos modos `KEY` e `QRCODE`, o documento só aparece quando a chave é consultada no DICT ou o BR Code é decodificado. As regras de documento são avaliadas nesse ponto, antes de o pagamento ser submetido ao parceiro.

Teto por valor de PIX out não é regra de policy. O disponível e o pedido
de aumento estão no [guia de limites](/baas/guias/pagar/limites). `pixOut.maxAmount` e `pixOut.nightMaxAmount` deixam de ser avaliados (o JSON antigo é ignorado). A recusa por valor é `422` `limit_exceeded_transaction`, e o disponível vem de `GET /v1/accounts/{accountId}/limits/available`.

Na prática isso significa que uma violação de blacklist no modo chave **não** devolve 422 na resposta do POST: o pagamento é aceito, o `paymentId` é criado, e o desfecho é `FAILED` com `errorCode: policy_denied`. O webhook `policy.violation` e o `pix.out.failed` avisam do resultado.

### Resposta a uma violação (fase de POST)

```http
HTTP/1.1 422 Unprocessable Entity
```

```json
{
  "errorCode": "policy_denied",
  "message": "recipient document is blacklisted",
  "violations": [
    { "rule": "cpfCnpjBlacklist", "message": "recipient document is blacklisted" }
  ]
}
```

Não é 403 (que significa falta de permissão) nem 400 (o payload é válido): a requisição está correta e foi recusada por uma regra que o próprio tenant configurou.

### Modo monitor (`NOTIFY_ONLY`)

O campo `violationAction` da seção `pixOut` define o que fazer com as violações:

| Valor            | Efeito                                                                              |
| ---------------- | ----------------------------------------------------------------------------------- |
| `BLOCK` (padrão) | Recusa o pagamento                                                                  |
| `NOTIFY_ONLY`    | Registra a violação e envia o webhook `policy.violation`, **mas o pagamento segue** |

`NOTIFY_ONLY` é o ensaio antes do bloqueio: salve a regra em modo monitor, acompanhe os avisos por alguns dias no painel e no webhook, e promova para `BLOCK` quando estiver convencido de que a regra não pega tráfego legítimo.

Em modo monitor a violação **não** aparece na timeline da transação — o pagamento seguiu e vai ter o desfecho normal (`pix_out.completed`). A violação vive no webhook e no painel.

## Regras de PIX In

> **Um recebimento não pode ser recusado**
>
> O liquidante credita a conta e só depois nos avisa. Quando a política é avaliada, o dinheiro já entrou — não existe momento em que dava para recusar. O teto e a ação valem para PIX, TED, transferência interna recebida e boleto de cobrança liquidado. A escolha é o que fazer **depois**.

| Ordem | Regra                      | `rule`                       | Descrição                                                                       |
| ----- | -------------------------- | ---------------------------- | ------------------------------------------------------------------------------- |
| 1     | **Whitelist**              | —                            | Documento do pagador na whitelist: **aceita e pula todas as regras abaixo**     |
| 2     | **Blacklist (documento)**  | `pixIn.cpfCnpjBlacklist`     | Pagador com documento na blacklist                                              |
| 3     | **Mesma Titularidade**     | `pixIn.sameOwnershipOnly`    | Aceita apenas PIX do CPF/CNPJ do titular da conta                               |
| 4     | **Limite por recebimento** | `pixIn.maxAmount`            | Valor máximo de um crédito: PIX, TED, transferência interna ou boleto liquidado |
| 5     | **Tipo de Pessoa**         | `pixIn.allowedPersonTypes`   | Restringe o pagador a PF ou PJ                                                  |
| 6     | **Bancos Permitidos**      | `pixIn.allowedBankCodes`     | Aceita apenas PIX dos bancos listados                                           |
| 7     | **Bancos Bloqueados**      | `pixIn.blacklistedBankCodes` | Recusa PIX dos bancos listados                                                  |

As listas de banco aceitam código COMPE (3 dígitos) ou ISPB (8 dígitos) — o que você tiver em mãos. Quando o crédito não identifica o banco do pagador, as regras de banco são puladas. Vale o mesmo para documento, tipo de pessoa e mesma titularidade quando o pagador não vem. TED traz esses dados. Transferência interna e boleto, se o pagador não vier, pulam essas regras. O teto de valor vale sempre.

### Ações de recebimento

A ação é uma só para a seção. O nome no JSON continua `pixIn.violationAction`.

| `violationAction`           | Efeito                                                                                                       |
| --------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `ALLOW_AND_NOTIFY` (padrão) | Registra a violação e envia `policy.violation`. O crédito permanece                                          |
| `AUTO_REFUND`               | No PIX, devolve o **valor integral**. Em TED, transferência interna e boleto só avisa: o dinheiro fica       |
| `LOCK_BALANCE`              | Trava no liquidante o valor daquele crédito. O disponível cai. Não desbloqueia sozinho                       |
| `BLOCK_ACCOUNT`             | A conta passa a `blocked` na nossa API: a saída responde 423 e consulta e entrada seguem. Não reabre sozinha |

`AUTO_REFUND` inicia uma devolução PIX comum logo após o crédito, com motivo `unauthorized-transaction`. Ela aparece no extrato do seu cliente como uma devolução e não tem como ser desfeita. Não há devolução automática de TED, nem cancelamento de boleto já liquidado.

`LOCK_BALANCE` reduz o saldo disponível no liquidante. `BLOCK_ACCOUNT` só corta saída na nossa API; o liquidante não bloqueia a conta. Marcar o caso como ciente não desfaz nenhum dos dois.

O webhook do crédito (`pix.in.completed`, `ted.in.received`, `transfer.internal.in` ou `boleto.charge.settled`) sai **antes** do `policy.violation`. Falha do lock ou do bloqueio da conta não desfaz o crédito. Quando há devolução de PIX, ela gera os eventos normais de PIX out (`pix.out.completed` ou `pix.out.failed`).

Valores antigos `QUARANTINE` e `BLOCK` salvos nesta seção continuam valendo como `ALLOW_AND_NOTIFY`.

## Regras de QR Code

Avaliadas na criação do QR Code (estático e dinâmico), antes de o QR existir no parceiro.

| Regra                   | `rule`                     | Descrição                                                                                |
| ----------------------- | -------------------------- | ---------------------------------------------------------------------------------------- |
| **Criação de estático** | `qrCode.canCreateStatic`   | `false` recusa a criação de QR estático                                                  |
| **Criação de dinâmico** | `qrCode.canCreateDynamic`  | `false` recusa a criação de QR dinâmico                                                  |
| **Valor mínimo**        | `qrCode.minAmount`         | Valor mínimo do QR                                                                       |
| **Valor máximo**        | `qrCode.maxAmount`         | Valor máximo do QR                                                                       |
| **Cota por dia**        | `qrCode.maxIssuesPerDay`   | Recusa quando a conta já criou esse número de QR no dia calendário (horário de Brasília) |
| **Cota por mês**        | `qrCode.maxIssuesPerMonth` | Recusa quando a conta já criou esse número de QR no mês calendário (horário de Brasília) |

Os limites de valor só se aplicam a QR criado **com** valor. Um QR estático aberto, em que o pagador digita o valor no app do banco dele, não tem montante para comparar na criação — as duas regras de valor são puladas.

As cotas de criação contam unidades, não valor, e por isso valem também para o QR aberto. São **por conta**: configuradas no tenant, cada conta dele tem a sua cota individual, não um teto somado. A contagem inclui todo QR criado na janela — estático, dinâmico e com vencimento — em qualquer status: cancelar ou deixar expirar um QR não devolve a vaga. Se a contagem falhar, a criação segue, pelo mesmo motivo de `keys.maxKeys`. QR de PIX Automático não entra nessa cota.

## Regras de Chaves PIX

Avaliadas na criação de chave (`POST /v1/accounts/{accountId}/pix/keys`).

| Regra                | `rule`           | Descrição                                          |
| -------------------- | ---------------- | -------------------------------------------------- |
| **Criação**          | `keys.canCreate` | `false` recusa a criação de novas chaves           |
| **Máximo de chaves** | `keys.maxKeys`   | Recusa quando a conta já tem esse número de chaves |

A contagem de chaves é consultada no parceiro no momento da criação. Se essa consulta falhar, a criação segue: indisponibilidade nossa não deve virar violação de política. Chaves que já existem nunca são removidas por uma mudança de política.

## Regras de Estorno

Avaliadas nas devoluções que você pede em `POST /v1/accounts/{accountId}/pix/out/refund`, sejam elas integrais ou parciais.

| Regra            | `rule`             | Descrição                                              |
| ---------------- | ------------------ | ------------------------------------------------------ |
| **Kill switch**  | `refund.disabled`  | `enabled: false` recusa toda devolução pedida pela API |
| **Valor máximo** | `refund.maxAmount` | Valor máximo por devolução                             |

Devoluções que não são sua escolha ficam fora desta seção: um MED aceito e o `AUTO_REFUND` da seção PIX In são obrigações, e regra de tenant não sobrepõe obrigação. Pelo mesmo motivo, as regras de documento de PIX Out (blacklist, whitelist, titularidade, tipo de pessoa) não se aplicam a devoluções — o destinatário de uma devolução é quem pagou, não uma escolha sua.

### Recusa nas três seções acima

QR Code, chaves e estorno **sempre barram**: não há modo monitor. As três são operações síncronas que ainda não moveram dinheiro quando a regra é avaliada, então a recusa cabe na resposta — `422` com `errorCode: policy_denied`, no mesmo formato do PIX Out. Avisar depois de devolver um BR Code, publicar uma chave no DICT ou submeter uma devolução seria avisar sobre fato consumado.

## Taxa de MED

Avaliada quando uma disputa (MED) nova é **recebida** contra a conta. A taxa é a mesma do painel — MEDs recebidas dividido por PIX recebidos com sucesso — só que por conta e numa janela móvel, sem corte diário. A única ação é `BLOCK_ACCOUNT`: a conta passa a `blocked` e toda saída responde `423 account_blocked` até alguém do suporte reativar. A MED em si segue o fluxo normal.

| Campo                     | `rule`                        | Descrição                                                                         |
| ------------------------- | ----------------------------- | --------------------------------------------------------------------------------- |
| `windowDays`              | —                             | Janela móvel em dias, contada para trás da MED que chegou. Ausente = 30. Teto 90. |
| `maxRatePercent`          | `med.maxRatePercent`          | Taxa (em %) a partir da qual bloqueia. Ausente ou `0` = regra desligada.          |
| `minMedCount`             | —                             | Mínimo de MEDs na janela para a taxa valer. Ausente = 1.                          |
| `critical.maxRatePercent` | `med.critical.maxRatePercent` | Mesma conta, só com MEDs **críticas**. Limite menor que o geral.                  |
| `critical.minMedCount`    | —                             | Mínimo de MEDs críticas na janela. Ausente = 1.                                   |

```json
{
  "med": {
    "windowDays": 30,
    "maxRatePercent": 1.0,
    "minMedCount": 5,
    "critical": { "maxRatePercent": 0.3, "minMedCount": 2 }
  }
}
```

Uma MED é **crítica** quando o motivo informado pelo liquidante é fraude (`scam-or-fraud`) ou quando o relato do reclamante contém uma palavra de uma lista mantida pela CorpX — termos de golpe ("golpe", "não reconheço", "conta invadida") e de apostas ("bet", "aposta", "tigrinho"). A lista é única para todas as contas e cresce com o tempo; a policy diz quantas MEDs críticas, em que taxa, bloqueiam.

O bloqueio exige as duas condições ao mesmo tempo: contagem de MEDs igual ou acima do mínimo **e** taxa igual ou acima do teto. O mínimo evita fechar uma conta por uma disputa só num mês de poucos recebimentos. Sem PIX recebido na janela a taxa conta como 100%. Como nas demais seções, a regra da conta substitui a do tenant por inteiro. Uma falha nossa ao calcular a taxa não bloqueia ninguém.

## Horário de Operação

Janela em que as saídas são permitidas. Suporta janelas que cruzam a meia-noite (ex.: `22:00`-`06:00`).

| Campo      | Descrição                                 | Exemplo             |
| ---------- | ----------------------------------------- | ------------------- |
| `start`    | Hora de início                            | `06:00`             |
| `end`      | Hora de fim                               | `22:00`             |
| `timezone` | Fuso horário (padrão `America/Sao_Paulo`) | `America/Sao_Paulo` |

Uma janela pela metade (só `start` ou só `end`) é tratada como ausente e não barra ninguém.

## Limites de DICT Lookup

Consultar uma chave PIX tem limites próprios, avaliados a cada consulta. Ao exceder, a resposta é `429` com `errorCode: dict_lookup_limit_exceeded`, e um webhook `policy.violation` com `phase: "dict_lookup"` é enviado.

> **Nem todo \`429\` é a sua cota**
>
> A mesma rota também responde `429` com `errorCode: partner_rate_limited`, que é throttling do liquidante sobre o tráfego da CorpX e não tem relação com os limites desta página — nenhum contador da sua conta fechou. Confira o `errorCode` antes de concluir que a cota acabou.

Contam como consulta as duas formas de perguntar ao DICT quem é o dono de uma chave:

* **A consulta explícita** — `GET /v1/accounts/{accountId}/pix/key/{pixKey}`.
* **O PIX Out no modo `KEY`** — `POST /v1/accounts/{accountId}/pix/out`, `/async` e `/bigpix`. A chave precisa ser resolvida antes de o dinheiro sair, e essa pergunta vai para o mesmo DICT. Ver "Pagamento por chave também consome cota", abaixo.

São três limites de **contagem absoluta**, todos medidos **por conta** (ver "Todo limite é por conta", abaixo), e **vale o mais restritivo** — qualquer um que estoure devolve `429`:

| Limite                | Janela                                 | Default global | O que protege                                                                          |
| --------------------- | -------------------------------------- | -------------- | -------------------------------------------------------------------------------------- |
| `maxLookupsPerDay`    | dia-calendário BRT (a partir de 00:00) | `50`           | Teto absoluto de consultas por dia                                                     |
| `maxLookupsPerMinute` | 60s rolantes                           | `15`           | Rajada: cabe no teto diário, mas chega tudo de uma vez                                 |
| `maxNotFoundPer5min`  | 5 min rolantes                         | `10`           | Enumeração de chaves: scan cego gera muito `NOT_FOUND` antes de o teto diário estourar |

Além deles existem os **tetos de taxa por janela de tempo**, descritos a seguir. Esses valem sempre: quem não declara números próprios herda a linha de base da frota.

> **Esta seção é a referência dos campos**
>
> Para entender por que o DICT é racionado, o que a CorpX espera do seu tráfego, como acompanhar o seu consumo no painel e o que acontece com quem desrespeita a régua, leia [Consultas de chave PIX](/baas/guias/pagar/consulta-dict).

### Tetos de taxa por janela de tempo

Os três limites acima respondem *quanto* e *quão rápido*. Nenhum responde a pergunta que o balde do DICT de fato mede: **quantas consultas você gasta por pagamento que efetiva**, e **que fração das suas consultas não resolve chave nenhuma**. Uma conta pode caber folgado em 500 consultas por dia e ainda assim gastar 40 consultas por PIX — perfil de quem varre chave, não de quem paga.

Cada janela de tempo pode ter teto para as duas taxas:

| Campo             | O que mede                                                                                            |
| ----------------- | ----------------------------------------------------------------------------------------------------- |
| `maxUsageRatio`   | Consultas ÷ PIX Out concluídos na janela                                                              |
| `maxFailureRatio` | (`NOT_FOUND` + recusadas) ÷ consultas na janela. É fração, não percentual: `0.4` = 40%                |
| `minLookups`      | Piso de amostra. Abaixo desse número de consultas na janela, **nenhuma** das duas regras pode recusar |

As janelas disponíveis são `5m`, `15m`, `30m`, `1h`, `3h`, `6h`, `12h`, `24h`, `3d`, `7d`, `14d`, `30d`, `60d` e `90d`.

```json
{
  "dictLookup": {
    "windows": {
      "5m":  { "maxFailureRatio": 0.6, "minLookups": 10 },
      "1h":  { "maxUsageRatio": 6, "maxFailureRatio": 0.4, "minLookups": 50 },
      "30d": { "maxUsageRatio": 4, "minLookups": 500 }
    }
  }
}
```

O `minLookups` existe para o rate não travar quem mal começou: uma conta com duas consultas e nenhum pagamento tem taxa de uso infinita, e sem o piso ficaria bloqueada para sempre.

**Janela sem teto declarado não é janela desligada.** Ela herda a linha de base da frota, que hoje é `maxUsageRatio` 2.0 em todas as faixas e `maxFailureRatio` 0.2 até `7d`, apertando nas janelas longas (0.18 em `14d`, 0.15 em `30d`, 0.12 em `60d` e 0.10 em `90d`), com piso de amostra de 20 nas janelas de até 30 minutos, 50 de 1h a 12h e 500 por dia de janela a partir de 24h (500 em `24h`, 1500 em `3d`, e assim por diante). Esses números partiram da medição de tráfego real da frota. Declarar valores próprios na policy especializa a conta ou o tenant; não é o que liga a proteção.

Quando mais de uma janela está acima do teto, a resposta cita **a mais curta** — é a causa imediata e a primeira a liberar. A mensagem do `429` diz qual janela, o que foi medido e qual era o teto:

```
DICT lookup usage too high for this account in the last 1h:
120 lookups for 10 successful transfers (12.0 per transfer); max 6.0
```

```
DICT lookup failure rate too high for this account in the last 5m:
18 of 24 lookups did not resolve a key (75%); max 40%
```

O `errorCode` continua sendo `dict_lookup_limit_exceeded` — nada muda para quem já trata esse código.

### Todo limite é por conta

Todos os limites são medidos **conta a conta**, sempre. Não existe teto agregado por tenant: as consultas de uma conta nunca entram na contagem de outra, mesmo que as duas pertençam ao mesmo tenant.

Isso vale inclusive quando o limite foi configurado no nível do tenant. Uma policy de tenant é um **molde aplicado a cada conta individualmente**, não um balde compartilhado:

| Configuração                                          | Leitura correta                                                          | Leitura errada                                                     |
| ----------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------ |
| Policy do tenant com `maxLookupsPerDay: 50`           | Cada conta do tenant pode fazer 50 consultas por dia                     | ~~O tenant todo pode fazer 50 por dia, divididas entre as contas~~ |
| Policy do tenant com `windows.24h.maxUsageRatio: 2.2` | A taxa de cada conta é medida contra as transferências **daquela** conta | ~~A taxa é medida contra o total de transferências do tenant~~     |

A policy de conta continua vencendo a do tenant quando existir — o que muda entre as duas não é a unidade de contagem, apenas de onde saem os números.

A conta é a unidade porque é ela que o BACEN mede no bucket de rate limit do DICT: é nela que a rajada acontece e é nela que a punição chega. Somar as contas de um tenant produzia os dois erros ao mesmo tempo — uma conta parada herdava o consumo da vizinha, e num tenant grande o excesso de uma conta se diluía no total até nenhum limite fechar.

### Pagamento por chave também consome cota

Um PIX Out no modo `KEY` precisa saber quem é o dono da chave antes de enviar o dinheiro. Essa resolução conta na mesma cota da consulta explícita, e por isso um pagamento pode receber `429` com `errorCode: dict_lookup_limit_exceeded`. Quando isso acontece, **nenhum pagamento é criado**: não há `paymentId`, não há transação, e reenviar com a mesma `Idempotency-Key` continua sendo seguro.

O cache de 24h é o que evita a dupla contagem. O fluxo mais comum — consultar a chave para exibir o destinatário e, confirmado pelo usuário, pagar — gasta **uma** consulta, não duas: a segunda é servida pelo cache. Quem paga direto, sem consultar antes, também gasta uma. Nos dois casos, 100 pagamentos por chave consomem cerca de 100 da cota, o que deixa o resto do orçamento para consultas avulsas.

O BigPix resolve a chave **uma vez** para o lote inteiro, independente de em quantas parcelas o valor é dividido.

Dois desfechos merecem atenção no POST de pagamento:

* **Chave inválida ou inexistente** devolve o erro na resposta, sem criar pagamento. É preferível a um pagamento que nasce e falha segundos depois.
* **DICT indisponível** (erro ou timeout do liquidante) não recusa nada: o pagamento segue e a chave é resolvida pelo liquidante, como antes. Indisponibilidade nossa ou dele não vira pagamento recusado nem consome cota.

### O denominador da taxa de uso

A taxa de uso de uma janela é `consultas ÷ PIX por chave concluídos na mesma janela`. Do lado do denominador entram só as transferências que de fato aconteceram, e só as **daquela conta**: `COMPLETED` e `REFUNDED` (que liquidaram e só depois foram devolvidas). Pagamento que falhou, foi recusado ou ficou indeterminado não amplia o teto — do contrário, quem estivesse repetindo uma tentativa com erro ganharia mais cota de consulta a cada falha. PIX por dados bancários e QR Code sem chave ficam fora, porque não passam pelo DICT.

O PIX por chave pago sem consulta prévia também conta como consulta, porque o liquidante resolve a chave no DICT do mesmo jeito:

| Situação                                    | Consultas                          | PIX |
| ------------------------------------------- | ---------------------------------- | --- |
| Consultou a chave e pagou com sucesso       | +1 (a consulta)                    | +1  |
| Consultou a chave e não pagou               | +1                                 | 0   |
| Pagou direto por chave, com sucesso         | +1                                 | +1  |
| Pagou direto por chave e a chave não existe | +1 (conta também na taxa de falha) | 0   |

Uma consulta cobre um pagamento: vale a consulta da mesma conta para a mesma chave nas 24 horas anteriores ao PIX. Dois PIX para a mesma chave depois de uma consulta só contam a consulta e mais uma.

Conta nova ou ociosa tem denominador zero, o que daria taxa infinita. Quem protege esse caso é o `minLookups` da janela: abaixo do piso de amostra nenhuma das duas regras pode recusar, então a conta faz suas primeiras consultas sem ser barrada por uma taxa que ainda não significa nada.

### Ausente não é ilimitado

Um limite ausente na policy **não** significa ilimitado: vale o default global da tabela acima. Para remover o teto é preciso declarar isso explicitamente (opção *No limit* no Backoffice, que grava um valor negativo). Os limites de burst continuam ativos mesmo assim — remover o teto diário não libera rajada.

### O que consome cota

Cota diária (`maxLookupsPerDay`) e ratio contam as consultas que chegaram ao DICT por vontade do integrador: chave encontrada, chave inexistente e chave recusada pelo DICT (requisição inválida, ou o limite do próprio DICT para aquele consultante). Falha técnica do liquidante e tentativa já recusada com `429` ficam de fora — não se deve queimar cota por indisponibilidade nossa, nem afundar mais fundo depois de já ter sido bloqueado. Vale igual para a consulta explícita e para a resolução feita dentro de um PIX Out.

Os limites de burst são o oposto: `maxLookupsPerMinute` conta **todos** os resultados, inclusive os recusados, porque a métrica ali é a pressão que o cliente está fazendo, não o proveito que tirou. `maxNotFoundPer5min` conta só as chaves inexistentes.

### Cache de 24h

Consultas repetidas da mesma chave são servidas de um cache de 24h, e **cache hit não consome cota**. O cache é o mesmo para os dois caminhos: uma consulta explícita serve o pagamento seguinte, e a resolução feita dentro de um pagamento serve a consulta seguinte. Para forçar uma ida ao DICT — dados desatualizados, titularidade que pode ter mudado — use `?noCache=true` na consulta explícita, lembrando que aí a consulta conta normalmente.

## Webhook `policy.violation`

Toda violação — recusada ou apenas avisada — dispara o evento `policy.violation` para quem o assinou.

```json
{
  "phase": "edge",
  "action": "BLOCK",
  "blocked": true,
  "accountId": "acc_...",
  "identifier": "PEDIDO-1234",
  "mode": "KEY",
  "amount": 5000.00,
  "violations": [
    { "rule": "cpfCnpjBlacklist", "message": "recipient document is blacklisted" }
  ],
  "counterparty": { "document": "12345678900", "name": "FULANO DE TAL" }
}
```

Em `phase: "edge"` não há `paymentId`: o gate roda antes de o pagamento ser criado, e é justamente por isso que a recusa cabe na resposta HTTP. Use o `identifier` para correlacionar. Na fase `counterparty`, que roda dentro do workflow, o `paymentId` já existe e vem no payload.

| Campo            | Descrição                                                                                                                                                                               |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `phase`          | `edge` (na requisição), `counterparty` (após resolver o destinatário), `pix_in`, `ted_in`, `internal_in`, `boleto_in` (após o crédito), `med` (ao receber uma disputa) ou `dict_lookup` |
| `action`         | `BLOCK`, `NOTIFY_ONLY`, `ALLOW_AND_NOTIFY`, `AUTO_REFUND`, `LOCK_BALANCE` ou `BLOCK_ACCOUNT`, conforme a configuração                                                                   |
| `blocked`        | `true` quando a operação foi de fato recusada. Sempre `false` num recebimento: o crédito não foi recusado                                                                               |
| `balanceLocked`  | No recebimento, `true` quando o valor daquele crédito foi travado no liquidante                                                                                                         |
| `accountBlocked` | No recebimento, `true` quando a conta passou a `blocked` por esta violação                                                                                                              |
| `violations`     | Todas as regras violadas, com o identificador em `rule`                                                                                                                                 |
| `counterparty`   | O destinatário (PIX Out) ou o pagador (PIX In), quando conhecido                                                                                                                        |

Num recebimento o payload troca `paymentId` por `transactionId` e a referência do crédito (`endToEnd` no PIX, `creditRef` nos demais), e traz `refunded`. `refunded` só é `true` na devolução de PIX. Se a ação pedida não concluiu, `balanceLocked` ou `accountBlocked` sai `false`.

Em `phase: "med"` a referência é o `medId` da disputa que disparou a avaliação, e o payload traz os números da janela: `windowDays`, `medCount`, `criticalMedCount`, `pixInCount`, `ratePercent` e `criticalRatePercent`. O `pix.med.opened` dessa mesma disputa sai com `accountBlocked: true`.

Detalhes de entrega, retentativas e assinatura no guia de [Webhooks](/baas/guias/conta/webhooks).

## Visibilidade de Violações

* **Webhook `policy.violation`** — em toda violação, em qualquer seção.
* **Timeline da transação** (`GET /v1/transactions/{id}/timeline`) — quando a violação recusa um PIX Out, o evento `pix_out.failed` traz `errorCode: policy_denied` e as regras violadas em `policyViolations`. Numa recusa na borda, em que ainda não existe `paymentId`, a âncora do evento é o `workflowId` determinístico da operação, que é o mesmo id devolvido nas respostas de PIX out. O endpoint aceita os dois, além de `endToEndId`, `txid` e o id do parceiro.
* **Painel** — a aba Violations lista o histórico, separando o que foi barrado, o que foi só avisado e o que foi devolvido, com o total por regra.

> **O extrato não mostra violações**
>
> Uma operação recusada por política nunca chega ao banco parceiro, e o extrato (`GET /v1/accounts/{accountId}/statement`) reflete o que aconteceu na conta. Violações não aparecem lá. Use o webhook, a timeline ou o painel. A exceção é a devolução de um PIX por `AUTO_REFUND`: ela é uma movimentação de verdade e aparece no extrato como devolução. `LOCK_BALANCE` reduz o disponível no liquidante; `BLOCK_ACCOUNT` não muda o saldo, só corta a saída na API.

> **Allowlist de IP e MED**
>
> A allowlist de IP que de fato bloqueia tráfego é a do WAF, configurada na tela de Security — não é uma política. Controles de MED têm guia próprio em [Disputas (MED)](/baas/guias/pagar/med).