Skip to main content
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), cada novo período começa a contar do zero 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: Cada decisão informa quanto consumiu de cada teto
  • Contagem por período: Limites diários, semanais e mensais começam uma nova contagem em cada fronteira de período
  • 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
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 em uma única contagem ao longo de toda a janela. A partir de customEndDate, o Tracer para de verificar o limite.

​
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 mantém um contador de uso por limite, por escopo correspondente, por período. A decisão de validação informa esse contador — veja Ler o consumo. Um contador é mantido por 90 dias após o fim do seu período, e depois um worker em segundo plano o remove.

​
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

Figura 1. Como funcionam os limites de gastos

  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 é R45.000eumanovatransac\ca~odeR 45.000 e uma nova transação de R 8.000 chega:
  • Uso projetado: R45.000+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")
  • asset: Código de ativo 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 não excluídos — diferente dos nomes de regra, que são únicos apenas dentro do seu contexto de escopo. A unicidade é imposta sobre o nome exatamente como armazenado, depois de remover os espaços no início e no fim: a comparação diferencia maiúsculas de minúsculas e não colapsa os espaços internos, então Daily Card Limit e daily card limit são dois limites distintos e ambos aceitáveis. Excluir um limite libera seu nome para reuso. Uma colisão retorna 409 Conflict com o código de erro 0442.
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.

​
Ler o consumo

​
A partir da decisão

Toda resposta de POST /v1/validations carrega limitUsageDetails, com uma entrada por limite que o Tracer verificou. Cada entrada informa:
  • limitId e limitAmount — qual teto foi verificado e o seu valor máximo
  • currentUsage — o consumo projetado do período atual e do escopo correspondente daquele teto se esta transação for permitida
  • attemptedAmount — o valor verificado contra o teto
  • exceeded — se o valor tentado levaria este teto além do seu valor máximo; todos os tetos são avaliados, então mais de uma entrada pode trazer exceeded: true, e qualquer uma delas produz o DENY

​
A partir do limite

GET /v1/limits/{id}/usage informa um total acumulado. O seu currentUsage soma os contadores de uso registrados para o limite, entre períodos e escopos, então use-o para revisar o consumo geral de um limite e não para responder quanto resta a um cliente no período atual. Um contador é removido 90 dias após o fim do seu período (veja Rastreamento de uso), então em um limite de longa duração esse total cobre apenas os períodos ainda conservados, não a vida inteira do limite.

​
Atualizar um limite

Atualize limites usando PATCH /v1/limits/{id}. Os campos limitType e asset são imutáveis e não podem ser alterados após a criação.
Alterar o valor do limite não apaga a contagem atual. Se você reduzir um limite abaixo do que o período atual já consumiu, transações subsequentes serão negadas 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 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

Figura 2. Ciclo de vida dos limites

​
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

  • Leia o payload da decisão - limitUsageDetails mostra quanto cada transação consumiu de cada teto
  • 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.” Baixar o limite não apaga a contagem. Se o período atual já consumiu mais que o novo teto, transações subsequentes serão negadas até o próximo período começar.
  • “Tentei deletar um limite ACTIVE e a chamada foi recusada.” A exclusão responde 422 com o código 0363. Envie POST /v1/limits/{id}/deactivate primeiro, depois DELETE /v1/limits/{id}. É intencional: previne remover acidentalmente um enforcement ativo.
  • “GET /v1/limits/{id}/usage informa 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

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.