> ## 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 > Guia para configurar e gerenciar limites de gastos no Tracer para controle de transações e proteção do cliente. export const GMetadata = ({children}) => {children} ; export const GAuditTrail = ({children}) => {children} ; Limites de gastos são como times de produto e risco capam exposição por cliente, por segmento ou por portfólio sem escrever código. Casos comuns: um teto diário de gastos em cartão para clientes do 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:** tetos de gastos deixam de ser constantes hardcoded em arquivos de configuração ou espalhadas por vários serviços. Viram dados versionados com ciclo de vida claro (DRAFT → ACTIVE → INACTIVE), resetam automaticamente na fronteira do período e ficam trilhadas em auditoria toda vez que uma transação seria excedida. **O trade-off honesto:** os contadores precisam ficar consistentes entre réplicas e corridas. O Tracer cuida disso transacionalmente — se uma transação é negada ou vai para REVIEW, o contador faz rollback. Você abre mão de "esperteza local em cada serviço" e ganha um número único e consistente. **Para quem é este guia?** Product managers configurando tetos, times de risco revisando exposição, compliance auditando o que foi negado e devs integrando a chamada de validação. A seção de "Tipos de limite" não exige conhecimento de API; ciclo de vida e PATCH assumem 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). Limites são avaliados em tempo real junto com as regras, na mesma chamada `POST /v1/validations`. ## Por que usar limites de gastos *** * **Proteção do cliente**: Detecte gastos excessivos e retorne decisões DENY para transações de grande valor não autorizadas * **Gestão de risco**: Monitore a exposição por conta, segmento ou portfólio * **Escopo flexível**: Aplique limites em diferentes níveis de granularidade * **Rastreamento em tempo real**: Monitore uso e valores restantes instantaneamente * **Resets automáticos**: Limites diários, semanais, mensais e personalizados resetam automaticamente * **Janelas de tempo**: Restrinja a aplicação de limites a horários específicos do dia * **Períodos personalizados**: Defina limites com datas específicas para campanhas, promoções ou requisitos regulatórios Ao final deste guia, você irá: * Entender os tipos de limite, janelas de tempo e opções de escopo * Criar e configurar limites de gastos com controles por período * Monitorar o uso de limites em tempo real * Gerenciar o ciclo de vida dos limites *** ## Conceitos principais *** Entenda os componentes básicos dos limites de gastos. ### Tipos de limite O Tracer suporta cinco tipos de limites de gastos: | Tipo | Descrição | Comportamento de reset | | ----------------- | ------------------------------------------------------------------ | ----------------------------------------------------------- | | `DAILY` | Valor máximo por dia | Reseta à meia-noite UTC | | `WEEKLY` | Valor máximo por semana | Reseta toda segunda-feira às 00:00 UTC | | `MONTHLY` | Valor máximo por mês | Reseta no 1º do mês, meia-noite UTC | | `CUSTOM` | Valor máximo dentro de um intervalo de datas definido pelo usuário | Reseta em `customEndDate` + 1 dia à meia-noite UTC | | `PER_TRANSACTION` | Valor máximo por transação individual | Sem rastreamento; cada transação avaliada independentemente | ### Janelas de tempo Janelas de tempo restringem **quando** um limite é aplicado durante o dia. Quando uma transação ocorre fora da janela de tempo configurada, o limite é **ignorado** (não aplicado) e a transação pode prosseguir sem ser contabilizada naquele limite. * **Formato**: `HH:MM` (24 horas, UTC) * **Ambos os campos obrigatórios**: Se `activeTimeStart` estiver definido, `activeTimeEnd` também deve estar (e vice-versa) * **Intervalo semi-aberto**: Início inclusivo, fim exclusivo `[início, fim)` * **Janelas noturnas suportadas**: Definir `activeTimeStart: "20:00"` e `activeTimeEnd: "06:00"` cria uma janela das 20h às 6h UTC Janelas de tempo podem ser aplicadas a **qualquer** tipo de limite (DAILY, WEEKLY, MONTHLY, CUSTOM ou PER\_TRANSACTION). Se nenhuma janela de tempo for configurada, o limite fica ativo 24/7. **Exemplo: Conformidade PIX** Uma instituição financeira precisa aplicar limites menores para transferências PIX durante o período noturno (conforme recomendação do BACEN): * `limitType`: `DAILY` * `maxAmount`: `"1000.00"` * `activeTimeStart`: `"20:00"` * `activeTimeEnd`: `"06:00"` * Escopo: transações PIX Transações entre 20:00 e 06:00 UTC são verificadas contra o limite de R\$ 1.000. Transações fora dessa janela não são afetadas por esse limite. ### Períodos personalizados Períodos personalizados definem um **intervalo de datas** durante o qual um limite está ativo. Isso é útil para campanhas, promoções, eventos sazonais ou requisitos regulatórios com datas específicas. * **Campos obrigatórios**: `customStartDate` e `customEndDate` (apenas para tipo `CUSTOM`) * **Intervalo semi-aberto**: Início inclusivo, fim exclusivo `[início, fim)` * **Duração máxima**: 5 anos * **Não pode estar no passado**: O `customEndDate` não pode estar inteiramente antes da data atual Os campos `customStartDate` e `customEndDate` são **obrigatórios** para limites `CUSTOM` e **proibidos** para outros tipos de limite. **Exemplo: Campanha Black Friday** Um varejista deseja definir um limite especial de gastos 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 varejo O uso acumula ao longo de todo o período de 5 dias. Após 30 de novembro, o limite não é mais aplicado. ### Combinando janelas de tempo e períodos personalizados Janelas de tempo e períodos personalizados podem ser usados juntos em limites `CUSTOM`. Quando combinados, uma transação deve estar dentro **tanto** do período personalizado **quanto** da janela de tempo para ser avaliada contra o limite. Por exemplo, um limite `CUSTOM` com `customStartDate` 25 Nov a `customEndDate` 30 Nov e uma janela de tempo de `09:00` a `18:00` aplicaria o 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 de 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 suportados são: * `segmentId` - Aplicar a transações de um segmento específico * `portfolioId` - Aplicar a transações de um portfólio específico * `accountId` - Aplicar a transações de uma conta específica * `merchantId` - Aplicar a transações para um comerciante específico * `transactionType` - Aplicar a tipos de transação específicos (CARD, WIRE, PIX, CRYPTO) * `subType` - Aplicar a um subtipo de transação específico (ex.: `debit`, `credit`) **Semântica de correspondência:** * **Dentro de um objeto de escopo:** os campos combinam com AND. Um campo não especificado funciona como wildcard (corresponde a qualquer valor). Pelo menos um campo deve estar definido — objetos de escopo vazios (`{}`) são rejeitados com o código de erro `0009`. * **Entre múltiplos objetos de escopo no mesmo limite:** combinam com OR. O limite se aplica se **qualquer** objeto de escopo corresponder à transação. **Sem hierarquia entre limites.** Quando uma transação corresponde a múltiplos limites (por exemplo, um limite no nível de conta e outro no nível de segmento), o Tracer verifica **todos** os limites aplicáveis independentemente em uma única transação. A transação é negada assim que qualquer um deles for excedido. ### Rastreamento de uso Para limites `DAILY`, `WEEKLY`, `MONTHLY` e `CUSTOM`, o Tracer rastreia: * **Uso atual** - Valor total consumido no período atual (como valor decimal) * **Percentual de utilização** - Porcentagem do limite utilizado * **Tempo de reset** - Quando o limite será zerado Contadores de uso são retidos por **90 dias** após a expiração para fins de auditoria, sendo automaticamente limpos por um worker em segundo plano. *** ## Como os limites funcionam *** O Tracer avalia limites durante cada requisição de validação. ### Fluxo de verificação de limite Quando uma transação é validada, o Tracer verifica todos os limites aplicáveis: Como o Tracer verifica todos os limites de gasto aplicáveis durante uma requisição de validação e atualiza seus contadores de uso 1. **Encontrar limites** - Consulta todos os limites ativos correspondendo ao escopo da transação 2. **Verificar janela de tempo** - Se o limite possui janela de tempo configurada, verifica se o **horário atual do servidor** está dentro de `activeTimeStart`/`activeTimeEnd`. Se estiver fora, o limite é **ignorado** (o `transactionTimestamp` enviado pelo cliente não é usado aqui) 3. **Verificar período personalizado** - Se o limite é `CUSTOM`, verifica se o **horário atual do servidor** está dentro de `customStartDate`/`customEndDate`. Se estiver fora, o limite é **ignorado** (novamente, o `transactionTimestamp` não é usado) 4. **Calcular uso projetado** - Adiciona o valor da transação ao uso atual 5. **Comparar limite** - Verifica se o uso projetado excede o valor do limite 6. **Retornar resultado** - Se qualquer limite aplicável for excedido — ou qualquer regra DENY corresponder — o Tracer retorna uma decisão DENY (seu sistema deve então bloquear a transação) Verificações de limite e incrementos de contadores são **transacionais**. Se uma transação for negada (por limites ou regras) ou marcada para revisão, todos os incrementos de contadores são revertidos atomicamente. Isso previne vazamento de limites por operações parciais. Quando um limite é **ignorado** durante a avaliação, `limitUsageDetails[i]` inclui `skipped: true` e um campo `skipReason` com um dos dois valores: * `"outside_time_window"` — a hora atual do servidor está fora da janela `activeTimeStart`/`activeTimeEnd` do limite * `"outside_custom_period"` — a hora atual do servidor está fora do intervalo `customStartDate`/`customEndDate` do limite Limites ignorados são reportados por transparência, mas **não** participam da decisão DENY e seus contadores **não** são incrementados. A verificação da janela usa **horário do servidor**, não o `transactionTimestamp` enviado pelo cliente, para prevenir ataques de manipulação de timestamp. **Por que horário do servidor em vez de `transactionTimestamp`.** O cliente pode definir `transactionTimestamp` como qualquer valor — inclusive um valor forjado para cair dentro de uma janela ativa quando a transação real cairia fora. Se o Tracer confiasse no relógio do cliente para enforcement de janela de tempo, qualquer um com acesso ao payload poderia burlar limites de horário restrito. Pinar a verificação ao relógio do próprio Tracer remove essa superfície de ataque. O lado negativo é que pequenos desvios de relógio entre pods do Tracer podem causar skips em casos de borda perto da fronteira da janela; na prática, os relógios sincronizados via NTP mantêm isso em milissegundos de um 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 uma nova transação de R$ 8.000 chega: * Uso projetado: R$ 45.000 + R$ 8.000 = R\$ 53.000 * Limite: R\$ 50.000 * Resultado: Tracer retorna **DENY** (seu sistema deve bloquear a transação) *** ## Criar um limite *** Crie limites usando `POST /v1/limits`. Limites são criados em status `DRAFT` por padrão. Um limite requer: * **name**: Um nome descritivo (ex.: "Limite Diário Cartão Corporativo") * **limitType**: DAILY, WEEKLY, MONTHLY, CUSTOM ou PER\_TRANSACTION * **maxAmount**: Valor máximo como valor decimal (ex., `"50000.00"`) * **currency**: Código de moeda ISO 4217 (ex.: 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` (ex.: `"09:00"`) * **activeTimeEnd**: Fim da janela de tempo diária no formato `HH:MM` (ex.: `"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) Nomes de limite devem ser globalmente únicos (entre todos os limites). A comparação de nomes ignora maiúsculas/minúsculas e espaços extras. Tentar criar ou atualizar um limite com nome duplicado retorna resposta `409 Conflict`. Para a estrutura completa do payload e detalhes de campos, consulte a [Referência da API](/pt/reference/tracer/create-limit). *** ## Listar e consultar limites *** Consulte limites para gerenciamento e auditoria usando `GET /v1/limits`. ### Parâmetros de consulta | Parâmetro | Tipo | Descrição | | ------------------ | ------- | ---------------------------------------------------------------------------------- | | `name` | string | Filtrar por nome (correspondência parcial, sem distinção de maiúsculas/minúsculas) | | `status` | string | Filtrar por status (DRAFT, ACTIVE, INACTIVE) | | `limit_type` | string | Filtrar por tipo de limite (DAILY, WEEKLY, MONTHLY, CUSTOM, PER\_TRANSACTION) | | `account_id` | string | Filtrar por escopo: ID da conta | | `segment_id` | string | Filtrar por escopo: ID do segmento | | `portfolio_id` | string | Filtrar por escopo: ID do portfólio | | `merchant_id` | string | Filtrar por escopo: ID do comerciante | | `transaction_type` | string | Filtrar por escopo: tipo de transação (CARD, WIRE, PIX, CRYPTO) | | `sub_type` | string | Filtrar por escopo: subtipo (ex.: debit, credit) | | `limit` | integer | Itens por página (padrão: 10, máx: 100) | | `cursor` | string | Cursor de paginação | | `sort_by` | string | Campo de ordenação: `createdAt`, `updatedAt`, `name`, `maxAmount` | | `sort_order` | string | Direção de ordenação: `ASC`, `DESC` (padrão: DESC) | ### Obter um limite específico Use `GET /v1/limits/{id}` para recuperar a definição completa do limite incluindo escopos e status atual. *** ## Consultar uso do limite *** Monitore o consumo do limite usando `GET /v1/limits/{id}/usage`. A resposta inclui: * **currentUsage**: Valor consumido no período atual * **utilizationPercent**: Porcentagem do limite utilizado * **nearLimit**: True quando `utilizationPercent > 80` — **estritamente maior que 80%**, não igual (para gestão proativa) * **resetAt**: Quando o limite reseta (apenas DAILY, WEEKLY, MONTHLY e CUSTOM) O flag `nearLimit` fica true quando `utilizationPercent > 80` — estritamente maior que 80%, não igual — então uso exatamente em 80% ainda não ativa o flag. *** ## Atualizar um limite *** Atualize limites usando `PATCH /v1/limits/{id}`. Os campos `limitType` e `currency` são imutáveis e não podem ser alterados após a criação. Alterar o valor do limite não reseta o uso atual. Se você reduzir um limite abaixo do uso atual, transações subsequentes serão negadas até o período resetar. *** ## Ciclo de vida do limite *** Limites seguem o mesmo ciclo de vida das regras: Ciclo de vida das regras e dos limites no Tracer, com as transições de estado pelas quais uma definição passa da criação até a aplicação ativa ### Estados | Estado | Descrição | | ---------- | ----------------------------------------------------------------------------------------------------------- | | `DRAFT` | Limite criado mas não ativo; pode ser modificado livremente | | `ACTIVE` | Limite é verificado durante validações | | `INACTIVE` | Limite não é verificado; preservado para trilha de auditoria; pode ser reativado | | `DELETED` | Removido permanentemente; não aparece em listagens | ### Transições | Operação | De | Para | Descrição | | --------- | --------------- | -------- | --------------------------------------------------------- | | Criar | - | DRAFT | Limites são criados em status DRAFT por padrão | | Ativar | DRAFT, INACTIVE | ACTIVE | Iniciar verificação deste limite | | Desativar | ACTIVE | INACTIVE | Parar de verificar este limite | | Rascunhar | INACTIVE | DRAFT | Retornar ao rascunho para edição | | Deletar | DRAFT, INACTIVE | DELETED | Remover permanentemente (não pode deletar limites ACTIVE) | *** ## Melhores práticas *** Recomendações para gerenciamento eficaz de limites. ### Nomenclatura * **Seja descritivo** - Inclua o escopo e o tipo no nome * **Use padrões consistentes** - ex.: "Diário {Segmento} {Tipo} Limite" | Menos claro | Mais claro | | ------------ | ----------------------------------- | | `Limite 1` | `Limite Diário Cartão Corporativo` | | `Limite VIP` | `Limite Mensal PIX VIP` | | `Promo BF` | `Limite Custom Black Friday Cartão` | ### Design de escopo * **Comece amplo, refine conforme necessário** - Comece com limites no nível de segmento, adicione no nível de conta para exceções * **Evite escopos sobrepostos** - Múltiplos limites no mesmo escopo podem causar confusão * **Use tipos de transação** - Diferentes métodos de pagamento podem precisar de limites diferentes ### Design de janela de tempo * **Use para conformidade regulatória** - Limites noturnos de PIX do BACEN são um caso de uso comum * **Considere o impacto de fuso horário** - Janelas de tempo usam UTC; considere o offset do fuso horário dos seus usuários * **Combine com períodos personalizados** - Use janelas de tempo dentro de períodos personalizados para controles precisos de campanhas ### Monitoramento * **Observe os flags nearLimit** - Contate proativamente clientes próximos dos limites * **Revise transações negadas** - Taxas de negação altas podem indicar limites muito restritivos * **Ajuste sazonalmente** - Considere aumentos temporários de limite durante períodos de alto gasto ou use limites `CUSTOM` para intervalos de datas específicos **Tropeços comuns ao trabalhar com limites:** * **"Meu cliente está reportando estouro — deveria ter batido no limite."** Verifique se o limite está `ACTIVE`. Limite em DRAFT ou INACTIVE não é avaliado. Confirme também que o escopo do limite de fato casa com a transação (segmento, tipo de transação, etc.). * **"Meu PATCH baixou o limite mas transações continuam sendo negadas mesmo depois do reset do período."** Baixar o limite não reseta o contador. Se o uso atual já está acima do novo teto, transações subsequentes serão negadas até o próximo `resetAt`. * **"Tentei deletar um limite ACTIVE e tomei 400."** Limites ACTIVE não podem ser deletados — `POST /v1/limits/{id}/deactivate` primeiro, depois `DELETE /v1/limits/{id}`. É intencional: previne remover acidentalmente um enforcement ativo. * **"Meu flag `nearLimit` não está disparando em 80% mesmo com o uso exatamente lá."** O flag usa estritamente maior (`utilizationPercent > 80`), então uso exatamente em 80% não ativa. *** ## Referência rápida *** Endpoints e opções de configuração-chave. ### 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` | | Deletar limite | DELETE | `/v1/limits/{id}` | | Obter uso | GET | `/v1/limits/{id}/usage` | Para a definição dos tipos de limite (DAILY, WEEKLY, MONTHLY, CUSTOM, PER\_TRANSACTION), os campos opcionais de janela de tempo e período personalizado, e a lista completa de campos de escopo, consulte [Tipos de limite](#tipos-de-limite) anteriormente neste guia e a [referência da API](/pt/reference/tracer/create-limit) para detalhes a nível de schema.