> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# Limites de gastos
> Configure limites de gastos do Tracer por conta, portfólio ou segmento, com períodos diário, semanal, mensal e personalizado, janelas de tempo e controles de ciclo de vida.
export const GMetadata = ({children}) =>
{children}
;
export const GAuditTrail = ({children}) =>
{children}
;
Limites de gastos são como times de produto e de risco limitam a exposição por cliente, por segmento ou por portfólio sem escrever código. Casos de uso comuns: um teto diário para gastos com cartão de clientes de varejo, um teto mensal para um MCC específico, um limite de janela de campanha para uma promoção de marketing.
**O que muda na sua operação:** os tetos de gastos deixam de existir como constantes fixas em arquivos de configuração ou espalhadas entre serviços. Eles passam a ser dados versionados com um ciclo de vida claro (DRAFT → ACTIVE → INACTIVE). Cada novo período começa a contar do zero, e cada um é registrado na trilha de auditoria toda vez que uma transação teria ultrapassado um deles.
**Para ser honesto sobre a contrapartida:** os contadores precisam se manter consistentes entre réplicas e condições de corrida. O Tracer trata isso de forma transacional. Se o Tracer nega uma transação ou a envia para REVIEW, o contador é revertido. Você abre mão da "lógica local inteligente em cada serviço" e ganha um número único e consistente.
**Para quem é este guia?** Gerentes de produto configurando tetos, times de risco revisando exposição, compliance auditando o que o Tracer negou, e desenvolvedores integrando a chamada de validação. A seção Tipos de limite não pressupõe conhecimento de API. As seções de ciclo de vida e PATCH pressupõem REST básico.
**Limites de gastos** no Tracer permitem controlar valores de transação por escopo (conta, portfólio, segmento) e período (diário, semanal, mensal, personalizado ou por transação). O Tracer avalia limites em tempo real junto com regras, na mesma chamada `POST /v1/validations`.
## Por que usar limites de gastos
***
* **Proteção ao cliente**: detecta gastos excessivos e retorna decisões DENY para transações grandes não autorizadas
* **Gestão de risco**: monitora a exposição por conta, segmento ou portfólio
* **Escopo flexível**: aplica limites em diferentes níveis de granularidade
* **Rastreamento em tempo real**: cada decisão reporta quanto de cada teto consumiu
* **Contagem por período**: limites diários, semanais e mensais começam uma nova contagem a cada fronteira de período
* **Janelas de tempo**: restringe a aplicação do limite a horas específicas do dia
* **Períodos personalizados**: define limites com datas fixas para campanhas, promoções ou exigências de compliance
Ao final deste guia, você vai:
* Entender tipos de limite, janelas de tempo e opções de escopo
* Criar e configurar limites de gastos com controles baseados em período
* Monitorar o uso de limites em tempo real
* Gerenciar o ciclo de vida do limite
***
## Conceitos básicos
***
Entenda os blocos de construção dos limites de gastos.
Tipos de limite
O Tracer aceita cinco tipos de limites de gastos:
| Tipo | Descrição | Contagem por período |
| ----------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- |
| `DAILY` | Valor máximo por dia | Uma nova contagem começa a cada dia civil às 00:00 UTC |
| `WEEKLY` | Valor máximo por semana | Uma nova contagem começa a cada semana ISO, segunda-feira às 00:00 UTC |
| `MONTHLY` | Valor máximo por mês | Uma nova contagem começa no dia 1º do mês às 00:00 UTC |
| `CUSTOM` | Valor máximo dentro de um intervalo de datas definido pelo usuário | Uma contagem para todo o intervalo; a partir de `customEndDate`, o Tracer para de conferir o limite |
| `PER_TRANSACTION` | Valor máximo por transação individual | Nenhuma contagem é mantida; cada transação é conferida por conta própria |
Janelas de tempo
Janelas de tempo restringem **quando** o Tracer aplica um limite durante o dia. Quando uma transação ocorre fora da janela de tempo configurada, o Tracer **pula** o limite e não o aplica. A transação prossegue sem contar contra esse limite.
* **Formato**: `HH:MM` (24 horas, UTC)
* **Os dois campos são obrigatórios**: se você define `activeTimeStart`, deve definir também `activeTimeEnd` (e vice-versa)
* **Intervalo semiaberto**: o início é inclusivo, o fim é exclusivo `[start, end)`
* **Janelas noturnas aceitas**: definir `activeTimeStart: "20:00"` e `activeTimeEnd: "06:00"` cria uma janela das 8 da noite às 6 da manhã, UTC
Você pode aplicar janelas de tempo a **qualquer** tipo de limite (DAILY, WEEKLY, MONTHLY, CUSTOM ou PER\_TRANSACTION). Sem uma janela de tempo, o limite fica ativo 24/7.
**Exemplo: compliance em Pix**
Uma instituição financeira precisa aplicar limites de transferência Pix mais baixos durante o período noturno (conforme recomendado pelo BACEN):
* `limitType`: `DAILY`
* `maxAmount`: `"1000.00"`
* `activeTimeStart`: `"20:00"`
* `activeTimeEnd`: `"06:00"`
* Escopo: transações Pix
O Tracer confere transações entre 20:00 e 06:00 UTC contra o limite de R\$ 1.000. Esse limite não afeta transações fora dessa janela.
### Períodos personalizados
Períodos personalizados definem um **intervalo de datas** durante o qual um limite fica ativo. Isso é útil para campanhas, promoções, eventos sazonais ou exigências de compliance com fronteiras de data específicas.
* **Campos obrigatórios**: `customStartDate` e `customEndDate` (apenas para o tipo `CUSTOM`)
* **Intervalo semiaberto**: o início é inclusivo, o fim é exclusivo `[start, end)`
* **Duração máxima**: 5 anos
* **Não pode estar no passado**: `customEndDate` não deve estar inteiramente antes da data atual
Os campos `customStartDate` e `customEndDate` são **obrigatórios** para limites `CUSTOM` e **proibidos** para os demais tipos de limite.
**Exemplo: campanha de Black Friday**
Um varejista quer definir um limite de gastos especial para o período da Black Friday:
* `limitType`: `CUSTOM`
* `maxAmount`: `"100000.00"`
* `customStartDate`: `"2026-11-25T00:00:00Z"`
* `customEndDate`: `"2026-11-30T00:00:00Z"`
* Escopo: transações CARD no segmento de varejo
O uso se acumula em toda a janela em uma única contagem. A partir de `customEndDate`, o Tracer para de conferir o limite.
### Combinando janelas de tempo e períodos personalizados
Você pode usar janelas de tempo e períodos personalizados juntos em limites `CUSTOM`. O Tracer então confere uma transação contra o limite apenas quando ela cai dentro **tanto** do período personalizado **quanto** da janela de tempo.
Por exemplo, tome um limite `CUSTOM` com `customStartDate` de 25 de novembro a `customEndDate` de 30 de novembro e uma janela de tempo de `09:00` a `18:00`. O Tracer aplica esse limite apenas durante o horário comercial dentro do período da Black Friday.
### Escopos
Escopos definem a quais transações um limite se aplica. Diferente das regras, **todo limite deve ter pelo menos um objeto de escopo**. Limites não podem ser globais.
Dentro de um único objeto de escopo, os campos aceitos são:
* `segmentId`: aplica-se a transações de um segmento específico
* `portfolioId`: aplica-se a transações de um portfólio específico
* `accountId`: aplica-se a transações de uma conta específica
* `merchantId`: aplica-se a transações para um comerciante específico
* `transactionType`: aplica-se a tipos de transação específicos (CARD, WIRE, PIX, CRYPTO)
* `subType`: aplica-se a um subtipo de transação específico (por exemplo, `debit`, `credit`)
**Semântica de correspondência:**
* **Dentro de um objeto de escopo:** os campos se combinam com AND. Um campo que você omite funciona como curinga (corresponde a qualquer valor). Você deve definir pelo menos um campo. O Tracer rejeita objetos de escopo vazios (`{}`) com o código de erro `0009`.
* **Entre vários objetos de escopo no mesmo limite:** eles se combinam com OR. O limite se aplica se **qualquer** objeto de escopo corresponder à transação.
**Não há hierarquia entre limites.** Uma transação pode corresponder a vários limites, por exemplo um limite de nível de conta e um de nível de segmento. O Tracer então confere **todos** os limites aplicáveis de forma independente em uma única transação. O Tracer nega a transação assim que ela excede qualquer um deles.
Rastreamento de uso
Para limites `DAILY`, `WEEKLY`, `MONTHLY` e `CUSTOM`, o Tracer mantém um contador de uso por limite, por escopo correspondido, por período. A decisão de validação reporta esse contador. Veja [Ler o consumo](#read-consumption).
O Tracer mantém um contador por **90 dias** após o fim do seu período, e então um worker em segundo plano o exclui.
***
## Como os limites funcionam
***
O Tracer avalia limites durante toda requisição de validação.
### Fluxo de conferência de limite
Quando o Tracer valida uma transação, ele confere todos os limites aplicáveis:
1. **Encontrar limites**: consulta todos os limites ativos que correspondem ao escopo da transação
2. **Conferir a janela de tempo**: se o limite tem uma janela de tempo configurada, verifica se o **horário atual do servidor** cai dentro de `activeTimeStart`/`activeTimeEnd`. Se estiver fora, o Tracer **pula** o limite (ele não usa o `transactionTimestamp` fornecido pelo cliente aqui)
3. **Conferir o período personalizado**: se o limite é `CUSTOM`, verifica se o **horário atual do servidor** cai dentro de `customStartDate`/`customEndDate`. Se estiver fora, o Tracer **pula** o limite (de novo, não usa `transactionTimestamp`)
4. **Calcular o uso projetado**: soma o valor da transação ao uso atual
5. **Comparar com o limite**: verifica se o uso projetado excede o valor do limite
6. **Retornar o resultado**: se a transação excede qualquer limite aplicável, ou qualquer regra DENY corresponde, o Tracer retorna uma decisão DENY (seu sistema deve então bloquear a transação)
As conferências de limite e os incrementos de contador são **transacionais**. Se o Tracer nega uma transação (por limites ou regras) ou a sinaliza para revisão, ele reverte todos os incrementos de contador de forma atômica. Isso evita vazamento de limite por operações parciais.
Quando um limite é **pulado** durante a avaliação, `limitUsageDetails[i]` inclui `skipped: true` e um campo `skipReason` com um de dois valores:
* `"outside_time_window"`: o horário atual do servidor está fora da janela `activeTimeStart`/`activeTimeEnd` do limite
* `"outside_custom_period"`: o horário atual do servidor está fora do intervalo `customStartDate`/`customEndDate` do limite
O Tracer reporta limites pulados para fins de transparência, mas eles **não** participam da decisão DENY, e seus contadores **não** são incrementados. A conferência da janela usa o **horário do servidor**, não o `transactionTimestamp` fornecido pelo cliente, para evitar ataques de manipulação de timestamp.
**Por que o horário do servidor em vez do `transactionTimestamp`.** O cliente pode definir `transactionTimestamp` como quiser. Isso inclui um valor forjado para cair dentro de uma janela ativa quando a transação real cairia fora dela. Se o Tracer confiasse no relógio do cliente para aplicar a janela de tempo, qualquer um com acesso ao payload poderia contornar limites de horário restrito. Fixar a conferência da janela no próprio relógio do Tracer elimina essa superfície de ataque. A desvantagem é que uma pequena variação de relógio entre pods do Tracer pode causar pulos em casos extremos perto da fronteira da janela. Na prática, os relógios do Tracer, sincronizados por NTP, mantêm essa variação em milissegundos de um único dígito.
### Cenário de exemplo
Um segmento corporativo tem um limite diário de R\$ 50.000 (`"50000.00"`) para transações CARD.
Se o uso atual é R$ 45.000 e chega uma nova transação de R$ 8.000:
* Uso projetado: R$ 45.000 + R$ 8.000 = R\$ 53.000
* Limite: R\$ 50.000
* Resultado: o Tracer retorna a decisão **DENY** (seu sistema deve bloquear a transação)
***
## Criar um limite
***
Crie limites usando `POST /v1/limits`. Por padrão, o Tracer cria limites com status `DRAFT`.
Um limite requer:
* **name**: um nome descritivo (por exemplo, "Daily Corporate Card Limit")
* **limitType**: DAILY, WEEKLY, MONTHLY, CUSTOM ou PER\_TRANSACTION
* **maxAmount**: valor máximo como um valor decimal (por exemplo, `"50000.00"`)
* **asset**: código de ativo ISO 4217 (por exemplo, BRL, USD)
* **scopes**: pelo menos um escopo para definir a quais transações se aplica
Campos opcionais:
* **activeTimeStart**: início da janela de tempo diária no formato `HH:MM` (por exemplo, `"09:00"`)
* **activeTimeEnd**: fim da janela de tempo diária no formato `HH:MM` (por exemplo, `"17:00"`)
* **customStartDate**: data de início para limites `CUSTOM` (timestamp ISO 8601, obrigatório para CUSTOM)
* **customEndDate**: data de fim para limites `CUSTOM` (timestamp ISO 8601, obrigatório para CUSTOM)
Os nomes de limite devem ser globalmente únicos entre todos os limites não excluídos, diferente dos nomes de regra, que são únicos apenas dentro do contexto do seu escopo. O Tracer aplica a unicidade sobre o nome **exatamente como armazenado**, depois de remover espaços em branco do início e do fim. A comparação **diferencia maiúsculas de minúsculas** e **não** condensa espaços em branco dentro do nome, então `Daily Card Limit` e `daily card limit` são dois limites distintos, ambos aceitáveis. Excluir um limite libera o nome para reutilização. Uma colisão retorna `409 Conflict` com o código de erro `0442`.
Para a estrutura completa do payload e detalhes de campo, veja a [referência da API](/pt/reference/products/tracer/create-limit).
***
## Listar e consultar limites
***
Consulte limites para gestão e auditoria usando `GET /v1/limits`.
### Parâmetros de consulta
| Parâmetro | Tipo | Descrição |
| ------------------ | ------- | ----------------------------------------------------------------------------------- |
| `name` | string | filtra por nome (correspondência parcial, sem diferenciar maiúsculas de minúsculas) |
| `status` | string | filtra por status (DRAFT, ACTIVE, INACTIVE) |
| `limit_type` | string | filtra por tipo de limite (DAILY, WEEKLY, MONTHLY, CUSTOM, PER\_TRANSACTION) |
| `account_id` | string | filtra por escopo: id da conta |
| `segment_id` | string | filtra por escopo: id do segmento |
| `portfolio_id` | string | filtra por escopo: id do portfólio |
| `merchant_id` | string | filtra por escopo: id do comerciante |
| `transaction_type` | string | filtra por escopo: tipo de transação (CARD, WIRE, PIX, CRYPTO) |
| `sub_type` | string | filtra por escopo: subtipo (por exemplo, debit, credit) |
| `limit` | integer | itens por página (padrão: 10, máximo: 100) |
| `cursor` | string | cursor de paginação |
| `sort_by` | string | campo de ordenação: `created_at`, `updated_at`, `name`, `max_amount` |
| `sort_order` | string | direção de ordenação: `ASC`, `DESC` (padrão: DESC) |
### Obter um limite específico
Use `GET /v1/limits/{id}` para obter a definição completa do limite, incluindo escopos e status atual.
***
Ler o consumo
***
### A partir da decisão
Toda resposta de `POST /v1/validations` carrega `limitUsageDetails`, com uma entrada para cada limite que o Tracer conferiu. Cada entrada reporta:
* **limitId** e **limitAmount**: qual teto o Tracer conferiu, e seu valor máximo
* **currentUsage**: o consumo projetado do período atual e do escopo correspondido desse teto, se o Tracer permitir esta transação
* **attemptedAmount**: o valor conferido contra o teto
* **exceeded**: se o valor tentado levaria este teto a ultrapassar seu valor máximo. O Tracer avalia todo teto, então mais de uma entrada pode carregar `exceeded: true`, e qualquer uma delas produz o DENY
### A partir do limite
`GET /v1/limits/{id}/usage` reporta um total acumulado. Seu `currentUsage` soma os contadores de uso registrados para o limite, entre períodos e escopos. Use-o para revisar o consumo geral de um limite, não para responder quanto resta a um cliente no período atual.
O Tracer exclui um contador 90 dias após o fim do seu período (veja [Rastreamento de uso](#usage-tracking)). Em um limite de longa duração, esse total cobre apenas os períodos ainda retidos, não o ciclo de vida completo do limite.
***
## Atualizar um limite
***
Atualize limites usando `PATCH /v1/limits/{id}`. Os campos `limitType` e `asset` são imutáveis. Você não pode alterá-los após a criação.
Alterar o valor do limite não limpa a contagem atual. Se você reduzir um limite abaixo do que o período atual já consumiu, o Tracer nega as transações seguintes até o próximo período começar.
***
## Ciclo de vida do limite
***
Limites seguem o mesmo ciclo de vida das regras:
### Estados
| Estado | Descrição |
| ---------- | -------------------------------------------------------------------------------------------------------------- |
| `DRAFT` | limite criado mas não ativo; pode ser modificado livremente |
| `ACTIVE` | o limite é conferido durante as validações |
| `INACTIVE` | o limite não é conferido; preservado para a trilha de auditoria; pode ser reativado |
| `DELETED` | removido permanentemente; não aparece nas listagens |
### Transições
| Operação | De | Para | Descrição |
| --------- | --------------- | -------- | -------------------------------------------------------------- |
| Criar | - | DRAFT | por padrão, os limites são criados com status DRAFT |
| Ativar | DRAFT, INACTIVE | ACTIVE | começa a conferir este limite |
| Desativar | ACTIVE | INACTIVE | para de conferir este limite |
| Rascunho | INACTIVE | DRAFT | retorna para rascunho para edição |
| Excluir | DRAFT, INACTIVE | DELETED | remove permanentemente (não é possível excluir limites ACTIVE) |
***
## Boas práticas
***
Recomendações para uma gestão eficaz de limites.
### Nomenclatura
* **Seja descritivo**: inclua o escopo e o tipo no nome
* **Use padrões consistentes**: por exemplo, "Daily {Segment} {Type} Limit"
| Menos claro | Mais claro |
| ----------- | -------------------------------- |
| `Limit 1` | `Daily Corporate Card Limit` |
| `VIP limit` | `Monthly VIP Pix Limit` |
| `BF promo` | `Custom Black Friday Card Limit` |
### Design de escopo
* **Comece amplo, refine conforme necessário**: comece com limites de nível de segmento, adicione nível de conta para exceções
* **Evite escopos sobrepostos**: vários limites no mesmo escopo podem gerar confusão
* **Use tipos de transação**: métodos de pagamento diferentes podem precisar de limites diferentes
### Design de janela de tempo
* **Use para compliance regulatório**: os limites noturnos de Pix do BACEN são um caso de uso comum
* **Considere o impacto do fuso horário**: janelas de tempo usam UTC. Leve em conta o deslocamento do fuso horário local dos seus usuários
* **Combine com períodos personalizados**: use janelas de tempo dentro de períodos personalizados para controles precisos de campanha
### Monitoramento
* **Leia o payload da decisão**: `limitUsageDetails` mostra quanto de cada teto cada transação consumiu
* **Revise as transações negadas**: taxas altas de negação podem indicar que os limites estão restritivos demais
* **Ajuste sazonalmente**: considere aumentos temporários de limite durante períodos de gasto alto, ou use limites `CUSTOM` para intervalos de data específicos
**Armadilhas comuns ao trabalhar com limites:**
* **"Meu cliente está reportando gasto excessivo. Ele deveria ter batido no limite."** Confira se o limite está `ACTIVE`. O Tracer não avalia um limite em estado DRAFT ou INACTIVE. Confirme também que o escopo do limite realmente corresponde à transação (segmento, tipo de transação etc.).
* **"Meu PATCH diminuiu o limite, mas as transações continuam sendo negadas."** Diminuir o limite não limpa a contagem. Se o período atual já consumiu mais do que o novo teto, o Tracer nega as transações seguintes até o próximo período começar.
* **"Tentei excluir um limite ACTIVE e fui rejeitado."** A exclusão volta `422` com o código `0363`. Envie `POST /v1/limits/{id}/deactivate` primeiro, depois `DELETE /v1/limits/{id}`. Isso é intencional: evita remover uma aplicação ativa por acidente.
* **"`GET /v1/limits/{id}/usage` reporta mais do que o cliente gastou neste período."** Esse endpoint totaliza os contadores de uso registrados para o limite, entre períodos e escopos. Para o período atual, leia `limitUsageDetails` na resposta de validação.
***
## Referência rápida
***
Principais endpoints e opções de configuração.
### Endpoints
| Operação | Método | Endpoint |
| ---------------- | ------ | ---------------------------- |
| Criar limite | POST | `/v1/limits` |
| Listar limites | GET | `/v1/limits` |
| Obter limite | GET | `/v1/limits/{id}` |
| Atualizar limite | PATCH | `/v1/limits/{id}` |
| Ativar limite | POST | `/v1/limits/{id}/activate` |
| Desativar limite | POST | `/v1/limits/{id}/deactivate` |
| Rascunhar limite | POST | `/v1/limits/{id}/draft` |
| Excluir limite | DELETE | `/v1/limits/{id}` |
| Obter uso | GET | `/v1/limits/{id}/usage` |
Para as definições de tipo de limite (DAILY, WEEKLY, MONTHLY, CUSTOM, PER\_TRANSACTION), veja [Tipos de limite](#limit-types) anteriormente neste guia. O mesmo guia cobre os campos opcionais de janela de tempo e de período personalizado e a lista completa de campos de escopo. A [referência da API](/pt/reference/products/tracer/create-limit) tem detalhes em nível de esquema.