Skip to main content
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:

​
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. 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:
Como o Tracer confere todos os limites de gastos aplicáveis durante uma requisição de validação e atualiza seus contadores de uso

Figura 1. Como funcionam os limites de gastos

  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 é R45.000echegaumanovatransac\ca~odeR 45.000 e chega uma nova transação de R 8.000:
  • Uso projetado: R45.000+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.

​
Listar e consultar limites

Consulte limites para gestão e auditoria usando GET /v1/limits.

​
Parâmetros de consulta

​
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). 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:
Ciclo de vida de regras e limites no Tracer, mostrando as transições de status pelas quais uma definição passa desde a criação até a aplicação ativa

Figura 2. Ciclo de vida dos limites de gastos

​
Estados

​
Transições

​
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 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

Para as definições de tipo de limite (DAILY, WEEKLY, MONTHLY, CUSTOM, PER_TRANSACTION), veja Tipos de limite 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 tem detalhes em nível de esquema.