Skip to main content
Los límites de gasto son la forma en que los equipos de producto y riesgo limitan la exposición por cliente, por segmento o por portafolio sin escribir código. Casos de uso comunes: un tope diario para el gasto con tarjeta de clientes minoristas, un tope mensual para un MCC específico, un límite de ventana de campaña para una promoción de marketing. Qué cambia en tu operación: los topes de gasto ya no existen como constantes fijas en archivos de configuración ni dispersas entre servicios. Se convierten en datos versionados con un ciclo de vida claro (DRAFT → ACTIVE → INACTIVE). Cada periodo nuevo empieza a contar desde cero, y quedan registrados en la auditoría cada vez que una transacción habría superado uno. Compensación que debes conocer: los contadores necesitan mantenerse consistentes entre réplicas y ante condiciones de carrera. Tracer maneja esto de forma transaccional. Si Tracer deniega una transacción o la envía a REVIEW, el contador se revierte. Renuncias a la “lógica local ingeniosa en cada servicio” y ganas un número único y consistente.
¿Para quién es esta guía? Gerentes de producto que configuran topes, equipos de riesgo que revisan la exposición, compliance que audita lo que Tracer denegó, y desarrolladores que integran la llamada de validación. La sección Tipos de límite no supone conocimiento de la API. Las secciones de ciclo de vida y PATCH suponen conocimientos básicos de REST.
Los límites de gasto en Tracer te permiten controlar los montos de las transacciones por alcance (cuenta, portafolio, segmento) y periodo (diario, semanal, mensual, personalizado o por transacción). Tracer evalúa los límites en tiempo real junto con las reglas, en la misma llamada POST /v1/validations.

​
Por qué usar límites de gasto

  • Protección del cliente: Detecta el gasto excesivo y devuelve decisiones DENY para transacciones grandes no autorizadas
  • Gestión de riesgo: Monitorea la exposición por cuenta, segmento o portafolio
  • Alcance flexible: Aplica límites en diferentes niveles de granularidad
  • Seguimiento en tiempo real: Cada decisión reporta cuánto de cada tope consumió
  • Conteo por periodo: Los límites diarios, semanales y mensuales empiezan un conteo nuevo en cada límite de periodo
  • Ventanas de tiempo: Restringe la aplicación del límite a horas específicas del día
  • Periodos personalizados: Define límites acotados por fecha para campañas, promociones o requisitos de cumplimiento
Al final de esta guía, podrás:
  • Entender los tipos de límite, las ventanas de tiempo y las opciones de alcance
  • Crear y configurar límites de gasto con controles basados en periodos
  • Monitorear el uso de límites en tiempo real
  • Gestionar el ciclo de vida del límite

​
Conceptos básicos

Entiende los componentes básicos de los límites de gasto.

​
Tipos de límite

Tracer admite cinco tipos de límites de gasto:

​
Ventanas de tiempo

Las ventanas de tiempo restringen cuándo Tracer aplica un límite durante el día. Cuando una transacción ocurre fuera de la ventana de tiempo configurada, Tracer omite el límite y no lo aplica. La transacción continúa sin contar contra ese límite.
  • Formato: HH:MM (24 horas, UTC)
  • Ambos campos son obligatorios: Si defines activeTimeStart, también debes definir activeTimeEnd (y viceversa)
  • Intervalo semiabierto: El inicio es inclusivo, el fin es exclusivo [start, end)
  • Se admiten ventanas nocturnas: Definir activeTimeStart: "20:00" y activeTimeEnd: "06:00" crea una ventana de 8 PM a 6 AM UTC
Puedes aplicar ventanas de tiempo a cualquier tipo de límite (DAILY, WEEKLY, MONTHLY, CUSTOM o PER_TRANSACTION). Sin una ventana de tiempo, el límite está activo 24/7.
Ejemplo: cumplimiento de Pix Una institución financiera necesita aplicar límites más bajos para transferencias Pix durante las horas nocturnas (como lo recomienda BACEN):
  • limitType: DAILY
  • maxAmount: "1000.00"
  • activeTimeStart: "20:00"
  • activeTimeEnd: "06:00"
  • Alcance: transacciones Pix
Tracer verifica las transacciones entre las 20:00 y las 06:00 UTC contra el límite de R$ 1,000. Este límite no afecta las transacciones fuera de esta ventana.

​
Periodos personalizados

Los periodos personalizados definen un rango de fechas durante el cual un límite está activo. Esto es útil para campañas, promociones, eventos estacionales o requisitos de cumplimiento con límites de fecha específicos.
  • Campos obligatorios: customStartDate y customEndDate (solo para el tipo CUSTOM)
  • Intervalo semiabierto: El inicio es inclusivo, el fin es exclusivo [start, end)
  • Duración máxima: 5 años
  • No puede estar en el pasado: customEndDate no debe ser completamente anterior a la fecha actual
Los campos customStartDate y customEndDate son obligatorios para límites CUSTOM y están prohibidos para los demás tipos de límite.
Ejemplo: campaña de Black Friday Un minorista quiere establecer un límite de gasto especial para el periodo de Black Friday:
  • limitType: CUSTOM
  • maxAmount: "100000.00"
  • customStartDate: "2026-11-25T00:00:00Z"
  • customEndDate: "2026-11-30T00:00:00Z"
  • Alcance: transacciones CARD en el segmento minorista
El uso se acumula durante toda la ventana en un solo conteo. A partir de customEndDate, Tracer deja de verificar el límite.

​
Combinar ventanas de tiempo y periodos personalizados

Puedes usar ventanas de tiempo y periodos personalizados juntos en límites CUSTOM. Tracer verifica entonces una transacción contra el límite solo cuando esta cae dentro tanto del periodo personalizado como de la ventana de tiempo. Por ejemplo, toma un límite CUSTOM con customStartDate del 25 de noviembre a customEndDate del 30 de noviembre y una ventana de tiempo de 09:00 a 18:00. Tracer aplica ese límite solo durante el horario laboral dentro del periodo de Black Friday.

​
Alcances

Los alcances definen a qué transacciones se aplica un límite. A diferencia de las reglas, todo límite debe tener al menos un objeto de alcance. Los límites no pueden ser globales. Dentro de un solo objeto de alcance, los campos admitidos son:
  • segmentId - Aplica a transacciones de un segmento específico
  • portfolioId - Aplica a transacciones de un portafolio específico
  • accountId - Aplica a transacciones de una cuenta específica
  • merchantId - Aplica a transacciones hacia un comercio específico
  • transactionType - Aplica a tipos de transacción específicos (CARD, WIRE, PIX, CRYPTO)
  • subType - Aplica a un subtipo de transacción específico (por ejemplo, debit, credit)
Semántica de coincidencia:
  • Dentro de un objeto de alcance: los campos se combinan con AND. Un campo que omites funciona como comodín (coincide con cualquier valor). Debes definir al menos un campo. Tracer rechaza los objetos de alcance vacíos ({}) con el código de error 0009.
  • Entre varios objetos de alcance del mismo límite: se combinan con OR. El límite se aplica si cualquier objeto de alcance coincide con la transacción.
No hay jerarquía entre límites. Una transacción puede coincidir con varios límites, por ejemplo un límite a nivel de cuenta y uno a nivel de segmento. Tracer entonces verifica todos los límites aplicables de forma independiente en una sola transacción. Tracer deniega la transacción tan pronto como esta supera cualquiera de ellos.

​
Seguimiento de uso

Para límites DAILY, WEEKLY, MONTHLY y CUSTOM, Tracer mantiene un contador de uso por límite, por alcance coincidente, por periodo. La decisión de validación reporta ese contador. Consulta Leer el consumo. Tracer mantiene un contador durante 90 días después de que termina su periodo, luego un proceso en segundo plano lo elimina.

​
Cómo funcionan los límites

Tracer evalúa los límites durante cada solicitud de validación.

​
Flujo de verificación de límites

Cuando Tracer valida una transacción, verifica todos los límites aplicables:
Cómo Tracer verifica todos los límites de gasto aplicables durante una solicitud de validación y actualiza sus contadores de uso

Figura 1. Cómo funcionan los límites de gasto

  1. Buscar límites - Consulta todos los límites activos que coincidan con el alcance de la transacción
  2. Verificar la ventana de tiempo - Si el límite tiene una ventana de tiempo configurada, verifica que la hora actual del servidor caiga dentro de activeTimeStart/activeTimeEnd. Si está fuera, Tracer omite el límite (aquí no usa el transactionTimestamp provisto por el cliente)
  3. Verificar el periodo personalizado - Si el límite es CUSTOM, verifica que la hora actual del servidor caiga dentro de customStartDate/customEndDate. Si está fuera, Tracer omite el límite (de nuevo, no usa transactionTimestamp)
  4. Calcular el uso proyectado - Suma el monto de la transacción al uso actual
  5. Comparar contra el umbral - Verifica si el uso proyectado supera el monto del límite
  6. Devolver el resultado - Si la transacción supera cualquier límite aplicable, o si alguna regla DENY coincide, Tracer devuelve una decisión DENY (tu sistema debe entonces bloquear la transacción)
Las verificaciones de límites y los incrementos de contadores son transaccionales. Si Tracer deniega una transacción (por límites o reglas) o la marca para revisión, revierte todos los incrementos de contadores de forma atómica. Esto evita fugas de límite por operaciones parciales.
Cuando un límite se omite durante la evaluación, limitUsageDetails[i] incluye skipped: true y un campo skipReason con uno de dos valores:
  • "outside_time_window": la hora actual del servidor está fuera de la ventana activeTimeStart/activeTimeEnd del límite
  • "outside_custom_period": la hora actual del servidor está fuera del rango customStartDate/customEndDate del límite
Tracer reporta los límites omitidos por transparencia, pero no participan en la decisión DENY, y sus contadores no se incrementan. La verificación de la ventana usa la hora del servidor, no el transactionTimestamp provisto por el cliente, para evitar ataques de manipulación de marca de tiempo.
Por qué la hora del servidor en lugar de transactionTimestamp. El cliente puede definir transactionTimestamp con cualquier valor que quiera. Eso incluye un valor construido para caer dentro de una ventana activa cuando la transacción real caería fuera de ella. Si Tracer confiara en el reloj del cliente para aplicar las ventanas de tiempo, cualquiera con acceso al payload podría evadir los límites fuera de horario. Fijar la verificación de la ventana al propio reloj de Tracer elimina esa superficie de ataque. La desventaja es que una pequeña desviación de reloj entre los pods de Tracer puede causar omisiones en casos límite cerca del borde de la ventana. En la práctica, los relojes de Tracer sincronizados por NTP mantienen esto en milisegundos de un solo dígito.

​
Escenario de ejemplo

Un segmento corporativo tiene un límite diario de R$ 50,000 ("50000.00") para transacciones CARD. Si el uso actual es de R45,000yllegaunanuevatransaccioˊndeR 45,000 y llega una nueva transacción de R 8,000:
  • Uso proyectado: R45,000+R 45,000 + R 8,000 = R$ 53,000
  • Límite: R$ 50,000
  • Resultado: Tracer devuelve una decisión DENY (tu sistema debe bloquear la transacción)

​
Crear un límite

Crea límites usando POST /v1/limits. Tracer crea los límites en estado DRAFT de forma predeterminada. Un límite requiere:
  • name: Un nombre descriptivo (por ejemplo, “Daily Corporate Card Limit”)
  • limitType: DAILY, WEEKLY, MONTHLY, CUSTOM o PER_TRANSACTION
  • maxAmount: Monto máximo como valor decimal (por ejemplo, "50000.00")
  • asset: Código de activo ISO 4217 (por ejemplo, BRL, USD)
  • scopes: Al menos un alcance para definir a qué transacciones se aplica
Campos opcionales:
  • activeTimeStart: Inicio de la ventana de tiempo diaria en formato HH:MM (por ejemplo, "09:00")
  • activeTimeEnd: Fin de la ventana de tiempo diaria en formato HH:MM (por ejemplo, "17:00")
  • customStartDate: Fecha de inicio para límites CUSTOM (marca de tiempo ISO 8601, obligatoria para CUSTOM)
  • customEndDate: Fecha de fin para límites CUSTOM (marca de tiempo ISO 8601, obligatoria para CUSTOM)
Los nombres de límites deben ser únicos a nivel global entre todos los límites no eliminados, a diferencia de los nombres de reglas, que son únicos solo dentro de su contexto de alcance. Tracer aplica la unicidad sobre el nombre exactamente como está almacenado, después de recortar los espacios en blanco al inicio y al final. La comparación es sensible a mayúsculas y minúsculas y no colapsa los espacios en blanco dentro del nombre, así que Daily Card Limit y daily card limit son dos límites distintos, ambos aceptables. Eliminar un límite libera su nombre para reutilizarlo. Una colisión devuelve 409 Conflict con el código de error 0442.
Para la estructura completa del payload y los detalles de los campos, consulta la referencia de la API.

​
Listar y consultar límites

Consulta límites para gestión y auditoría usando GET /v1/limits.

​
Parámetros de consulta

​
Obtener un límite específico

Usa GET /v1/limits/{id} para obtener la definición completa del límite, incluidos los alcances y el estado actual.

​
Leer el consumo

​
Desde la decisión

Cada respuesta de POST /v1/validations incluye limitUsageDetails, con una entrada por cada límite que Tracer verificó. Cada entrada reporta:
  • limitId y limitAmount: qué tope verificó Tracer, y su techo
  • currentUsage: el consumo proyectado del periodo actual de ese tope y del alcance coincidente si Tracer permite esta transacción
  • attemptedAmount: el monto verificado contra el tope
  • exceeded: si el monto intentado empujaría este tope más allá de su techo. Tracer evalúa cada tope, así que más de una entrada puede llevar exceeded: true, y cualquiera de ellas produce el DENY

​
Desde el límite

GET /v1/limits/{id}/usage reporta un total acumulado. Su currentUsage suma los contadores de uso registrados para el límite, entre periodos y alcances. Úsalo para revisar el consumo general de un límite, no para responder cuánto le queda a un cliente en el periodo actual. Tracer elimina un contador 90 días después de que termina su periodo (consulta Seguimiento de uso). En un límite de larga duración, este total cubre solo los periodos que aún se conservan, no todo el ciclo de vida del límite.

​
Actualizar un límite

Actualiza límites usando PATCH /v1/limits/{id}. Los campos limitType y asset son inmutables. No puedes cambiarlos después de la creación.
Cambiar el monto del límite no borra el conteo actual. Si reduces un límite por debajo de lo que el periodo actual ya consumió, Tracer deniega las transacciones siguientes hasta que empiece el próximo periodo.

​
Ciclo de vida del límite

Los límites siguen el mismo ciclo de vida que las reglas:
Ciclo de vida de reglas y límites en Tracer, que muestra las transiciones de estado que atraviesa una definición desde su creación hasta la aplicación activa

Figura 2. Ciclo de vida de los límites de gasto

​
Estados

​
Transiciones

​
Mejores prácticas

Recomendaciones para una gestión eficaz de los límites.

​
Nomenclatura

  • Sé descriptivo - Incluye el alcance y el tipo en el nombre
  • Usa patrones consistentes - por ejemplo, “Daily Limit”

​
Diseño de alcances

  • Empieza amplio y refina según sea necesario - Empieza con límites a nivel de segmento y agrega a nivel de cuenta para excepciones
  • Evita alcances superpuestos - Varios límites sobre el mismo alcance pueden generar confusión
  • Usa tipos de transacción - Diferentes métodos de pago pueden necesitar límites distintos

​
Diseño de ventanas de tiempo

  • Úsalas para cumplimiento regulatorio - Los límites nocturnos de Pix exigidos por BACEN son un caso de uso común
  • Considera el impacto de la zona horaria - Las ventanas de tiempo usan UTC. Ten en cuenta el desfase de la zona horaria local de tus usuarios
  • Combínalas con periodos personalizados - Usa ventanas de tiempo dentro de periodos personalizados para controles de campaña precisos

​
Monitoreo

  • Lee el payload de la decisión - limitUsageDetails muestra cuánto de cada tope consumió cada transacción
  • Revisa las transacciones denegadas - Tasas altas de denegación pueden indicar que los límites son demasiado restrictivos
  • Ajusta según la temporada - Considera aumentos temporales de límites durante periodos de gasto alto, o usa límites CUSTOM para rangos de fechas específicos
Errores comunes al trabajar con límites:
  • “Mi cliente reporta gasto excesivo. Debería haber alcanzado el límite.” Verifica si el límite está ACTIVE. Tracer no evalúa un límite en estado DRAFT o INACTIVE. Confirma también que el alcance del límite realmente coincide con la transacción (segmento, tipo de transacción, etc.).
  • “Mi PATCH bajó el límite, pero las transacciones se siguen denegando.” Bajar el límite no borra el conteo. Si el periodo actual ya consumió más que el nuevo techo, Tracer deniega las transacciones siguientes hasta que empiece el próximo periodo.
  • “Intenté eliminar un límite ACTIVE y fue rechazado.” La eliminación devuelve 422 con el código 0363. Envía primero POST /v1/limits/{id}/deactivate, y luego DELETE /v1/limits/{id}. Esto es intencional: evita eliminar por accidente una aplicación activa.
  • “GET /v1/limits/{id}/usage reporta más de lo que el cliente gastó este periodo.” Ese endpoint totaliza los contadores de uso registrados para el límite, entre periodos y alcances. Para el periodo actual, lee limitUsageDetails en la respuesta de validación.

​
Referencia rápida

Endpoints clave y opciones de configuración.

​
Endpoints

Para las definiciones de tipos de límite (DAILY, WEEKLY, MONTHLY, CUSTOM, PER_TRANSACTION), consulta Tipos de límite más arriba en esta guía. La misma guía cubre los campos opcionales de ventana de tiempo y periodo personalizado, y la lista completa de campos de alcance. La referencia de la API tiene los detalles a nivel de esquema.