Limites de gastos

Limites de gastos no Tracer permitem controlar valores de transação por escopo (conta, portfólio, segmento) e período (diário, mensal, por transação). Limites são avaliados em tempo real junto com as regras, fornecendo governança abrangente de transações.

​

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 e mensais resetam automaticamente

Ao final deste guia, você irá:

• Entender os tipos de limite e opções de escopo
• Criar e configurar limites de gastos
• 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 três tipos de limites de gastos:

​

Escopos

Escopos definem a quais transações um limite se aplica. Um limite corresponde a transações que se encaixam na sua definição de escopo. Campos de escopo (todos opcionais, pelo menos um obrigatório):

• 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)

Hierarquia de escopo: Escopos mais específicos têm precedência. Por exemplo, um limite no nível de conta é mais específico que um limite no nível de segmento.

​

Rastreamento de uso

Para limites DAILY e MONTHLY, o Tracer rastreia:

• Uso atual - Valor total consumido no período atual (na menor unidade da moeda)
• Percentual de utilização - Porcentagem do limite utilizado
• Tempo de reset - Quando o limite será zerado

---

​

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. Calcular uso projetado - Adiciona o valor da transação ao uso atual
3. Comparar limite - Verifica se o uso projetado excede o valor do limite
4. Retornar resultado - Retorna decisão DENY se qualquer limite for excedido (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 (5.000.000 centavos) 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, MONTHLY ou PER_TRANSACTION
• maxAmount: Valor máximo na menor unidade da moeda
• currency: Código de moeda ISO 4217 (ex.: BRL, USD)
• scopes: Pelo menos um escopo para definir a quais transações se aplica

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

---

​

Consultar uso do limite

---

Monitore o consumo do limite usando GET /v1/limits/{limitId}/usage. A resposta inclui:

• currentUsage: Valor consumido no período atual
• utilizationPercent: Porcentagem do limite utilizado
• nearLimit: True quando o uso excede 80% (para gestão proativa)
• resetAt: Quando o limite reseta (apenas DAILY/MONTHLY)

---

​

Atualizar um limite

---

Atualize limites usando PATCH /v1/limits/{limitId}. 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

​

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

---

​

Referência rápida

---

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

​

Endpoints

​

Tipos de limite

​

Campos de escopo