Limites de gastos

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 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. 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:

​

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

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

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 TRC-0125.
• 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:

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)

​

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)

Para a estrutura completa do payload e detalhes de campos, consulte a Referência da API.

---

​

Listar e consultar limites

---

Consulte limites para gerenciamento e auditoria usando GET /v1/limits.

​

Parâmetros de consulta

​

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)

---

​

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.

---

​

Ciclo de vida do limite

---

Limites seguem o mesmo ciclo de vida das regras:

​

Estados

​

Transições

---

​

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 Limite”

​

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

---

​

Referência rápida

---

Endpoints e opções de configuração-chave.

​

Endpoints

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 anteriormente neste guia e a referência da API para detalhes a nível de schema.