Pular para o conteúdo principal
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. 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.
Este guia é para 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
  • 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:

​
Horário de reinício

resetTime move o início de cada período DAILY, WEEKLY e MONTHLY para outro horário do dia, no formato HH:MM (24 horas, UTC). Sem ele, cada período começa às 00:00 UTC. Defina-o ao criar o limite. Você não pode alterá-lo depois. O Tracer rejeita resetTime em um limite CUSTOM ou PER_TRANSACTION com o código de erro 0537. Quando o limite tem uma janela de tempo, resetTime não deve cair dentro da janela. Ele pode ser igual a activeTimeStart ou activeTimeEnd. Um horário de reinício dentro da janela retorna o código de erro 0538.

​
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. O período noturno do Pix vai das 20:00 às 06:00 no horário de Brasília (UTC-3), ou seja, das 23:00 às 09:00 UTC:
  • limitType: DAILY
  • maxAmount: "1000.00"
  • activeTimeStart: "23:00"
  • activeTimeEnd: "09:00"
  • resetTime: "09:00"
  • Escopo: transações Pix
O Tracer confere transações entre 23:00 e 09:00 UTC contra o limite de R$ 1.000. Esse limite não afeta transações fora dessa janela. resetTime: "09:00" começa cada contagem diária quando a janela fecha. Sem ele, a contagem reinicia às 00:00 UTC (21:00 em Brasília), no meio da janela. Um cliente pode então gastar os R$ 1.000 inteiros antes das 21:00 no horário de Brasília e de novo depois.
Atualize todos os pods do Tracer para o Midaz v4.2.0 ou posterior antes de criar um limite com resetTime. Um pod em uma versão anterior aceita a requisição, mas descarta o campo. Até que todos os pods rodem a v4.2.0, um pod anterior ainda reinicia a contagem às 00:00 UTC.

​
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
  • scheme: aplica-se a um esquema de pagamento, como CARD ou PIX. transactionType é o nome obsoleto desse campo
  • 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. Se a transação excede qualquer limite aplicável, o Tracer a nega. O Tracer não confere nenhum limite quando uma regra retorna DENY ou quando a requisição usa POST /v1/validations/rules-only.

​
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. Para contadores DAILY, WEEKLY e MONTHLY, expiresAt é 90 dias após o reset do período. Para contadores CUSTOM, é 90 dias após customEndDate. Contadores expirados ficam elegíveis para limpeza. A exclusão física exige um worker de limpeza habilitado que execute com sucesso.

​
Como os limites funcionam

O Tracer avalia limites durante requisições de validação.

​
Fluxo de conferência de limite

Como o Tracer confere 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 o Tracer pula um limite 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.

​
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"). Não pode ser negativo. Um maxAmount de 0 nega todas as transações no escopo do limite.
  • asset: código de ativo de 1 a 100 letras maiúsculas (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)
  • resetTime: início de cada período DAILY, WEEKLY ou MONTHLY no formato HH:MM (por exemplo, "09:00")
Os nomes de limite devem ser únicos entre os seus 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 bem-sucedida de POST /v1/validations, 201 ou 200, carrega limitUsageDetails. 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. Ele inclui a capacidade retida por reservas não confirmadas do ledger do Midaz. Para um limite PER_TRANSACTION, ou um limite que o Tracer ignorou, ele é 0
  • 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 o período atual do limite. Seu currentUsage é o que o escopo mais consumido usou nesse período, incluindo a capacidade retida por reservas não confirmadas do ledger do Midaz. Para um limite PER_TRANSACTION, ele é 0. Para um limite com maxAmount de 0, utilizationPercent é 100 e nearLimit é true.

​
Atualizar um limite

Atualize limites usando PATCH /v1/limits/{id}. Os campos limitType, asset e resetTime 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 esquemas de pagamento: 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

  • 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, esquema de pagamento 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.

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