Skip to main content
Los límites de gasto son cómo los equipos de producto y riesgo limitan la exposición por cliente, por segmento o por portafolio sin escribir código. Casos comunes: un tope diario de gasto con tarjeta para clientes minoristas, un tope mensual sobre un MCC específico, un límite con ventana de campaña para una promoción de marketing. Qué cambia en tu operación: los topes de gasto dejan de ser constantes hardcoded en archivos de configuración o dispersos por varios servicios. Se vuelven datos versionados con un ciclo de vida claro (DRAFT → ACTIVE → INACTIVE), cada período nuevo empieza a contar desde cero, y quedan en el rastro de auditoría cada vez que una transacción habría pasado sobre uno de ellos. El trade-off honesto: los contadores necesitan mantenerse consistentes entre réplicas y races. Tracer maneja eso transaccionalmente — si una transacción se deniega o va a REVIEW, el contador hace rollback. Renuncias a “lógica local astuta en cada servicio” y ganas un número único y consistente.
¿Para quién es esta guía? Product managers configurando topes, equipos de riesgo revisando exposición, compliance auditando lo que se denegó, y devs integrando la llamada de validación. La sección “Tipos de límite” no asume conocimiento de API; las secciones de ciclo de vida y PATCH asumen REST básico.
Los límites de gasto en Tracer te permiten controlar los montos de transacción por alcance (cuenta, portafolio, segmento) y período (diario, semanal, mensual, personalizado o por transacción). Los límites se evalúan 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 consumió de cada tope
  • Conteo por período: Los límites diarios, semanales y mensuales empiezan un conteo nuevo en cada frontera de período
  • Ventanas de tiempo: Restringe la aplicación de límites a horarios específicos del día
  • Períodos personalizados: Define límites con fechas específicas para campañas, promociones o requisitos regulatorios
Al final de esta guía, podrás:
  • Comprender los tipos de límites, ventanas de tiempo y opciones de alcance
  • Crear y configurar límites de gasto con controles por período
  • Monitorear el uso de límites en tiempo real
  • Gestionar el ciclo de vida de los límites

​
Conceptos principales

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

​
Tipos de límites

Tracer soporta cinco tipos de límites de gasto:

​
Ventanas de tiempo

Las ventanas de tiempo restringen cuándo se aplica un límite durante el día. Cuando una transacción ocurre fuera de la ventana de tiempo configurada, el límite se omite (no se aplica) y la transacción puede continuar sin contabilizarse contra ese límite.
  • Formato: HH:MM (24 horas, UTC)
  • Ambos campos requeridos: Si activeTimeStart está definido, activeTimeEnd también debe estarlo (y viceversa)
  • Intervalo semi-abierto: Inicio inclusivo, fin exclusivo [inicio, fin)
  • Ventanas nocturnas soportadas: Definir activeTimeStart: "20:00" y activeTimeEnd: "06:00" crea una ventana de 20:00 a 06:00 UTC
Las ventanas de tiempo pueden aplicarse a cualquier tipo de límite (DAILY, WEEKLY, MONTHLY, CUSTOM o PER_TRANSACTION). Si no se configura ninguna ventana de tiempo, el límite está activo 24/7.
Ejemplo: Cumplimiento PIX Una institución financiera necesita aplicar límites menores para transferencias PIX durante el horario nocturno (según recomendación del BACEN):
  • limitType: DAILY
  • maxAmount: "1000.00"
  • activeTimeStart: "20:00"
  • activeTimeEnd: "06:00"
  • Alcance: transacciones PIX
Las transacciones entre las 20:00 y las 06:00 UTC se verifican contra el límite de R$ 1.000. Las transacciones fuera de esta ventana no son afectadas por este límite.

​
Períodos personalizados

Los períodos 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 regulatorios con fechas específicas.
  • Campos requeridos: customStartDate y customEndDate (solo para tipo CUSTOM)
  • Intervalo semi-abierto: Inicio inclusivo, fin exclusivo [inicio, fin)
  • Duración máxima: 5 años
  • No puede estar en el pasado: El customEndDate no puede estar completamente antes de la fecha actual
Los campos customStartDate y customEndDate son requeridos para límites CUSTOM y prohibidos para otros tipos de límite.
Ejemplo: Campaña Black Friday Un minorista desea establecer un límite especial de gasto para el período 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 en un solo conteo durante toda la ventana. Desde customEndDate en adelante, Tracer deja de verificar el límite.

​
Combinando ventanas de tiempo y períodos personalizados

Las ventanas de tiempo y los períodos personalizados pueden usarse juntos en límites CUSTOM. Cuando se combinan, una transacción debe estar dentro tanto del período personalizado como de la ventana de tiempo para ser evaluada contra el límite. Por ejemplo, un límite CUSTOM con customStartDate 25 Nov a customEndDate 30 Nov y una ventana de tiempo de 09:00 a 18:00 aplicaría el límite solo durante el horario comercial dentro del período 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 único objeto de alcance, los campos soportados son:
  • segmentId - Aplicar a transacciones de un segmento específico
  • portfolioId - Aplicar a transacciones de un portafolio específico
  • accountId - Aplicar a transacciones de una cuenta específica
  • merchantId - Aplicar a transacciones hacia un comercio específico
  • transactionType - Aplicar a tipos de transacción específicos (CARD, WIRE, PIX, CRYPTO)
  • subType - Aplicar a un subtipo de transacción específico (ej.: debit, credit)
Semántica de coincidencia:
  • Dentro de un objeto de alcance: los campos se combinan con AND. Un campo no especificado funciona como comodín (coincide con cualquier valor). Al menos un campo debe estar definido — objetos de alcance vacíos ({}) son rechazados con el código de error 0009.
  • Entre múltiples objetos de alcance en el mismo límite: se combinan con OR. El límite aplica si cualquier objeto de alcance coincide con la transacción.
Sin jerarquía entre límites. Cuando una transacción coincide con múltiples límites (por ejemplo, un límite a nivel de cuenta y otro a nivel de segmento), Tracer verifica todos los límites aplicables de forma independiente en una sola transacción. La transacción se deniega tan pronto como cualquiera de ellos sea excedido.

​
Seguimiento de uso

Para límites DAILY, WEEKLY, MONTHLY y CUSTOM, Tracer mantiene un contador de uso por límite, por alcance coincidente, por período. La decisión de validación reporta ese contador — consulta Leer el consumo. Un contador se conserva por 90 días después de que termina su período, y luego un worker 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 se valida una transacción, Tracer 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. Encontrar límites - Consultar todos los límites activos que coinciden con el alcance de la transacción
  2. Verificar ventana de tiempo - Si el límite tiene ventana de tiempo configurada, verificar que la hora actual del servidor esté dentro de activeTimeStart/activeTimeEnd. Si está fuera, el límite se omite (el transactionTimestamp provisto por el cliente no se usa aquí)
  3. Verificar período personalizado - Si el límite es CUSTOM, verificar que la hora actual del servidor esté dentro de customStartDate/customEndDate. Si está fuera, el límite se omite (de nuevo, el transactionTimestamp no se usa)
  4. Calcular uso proyectado - Agregar el monto de la transacción al uso actual
  5. Comparar umbral - Verificar si el uso proyectado excede el monto del límite
  6. Devolver resultado - Si algún límite aplicable es excedido — o alguna regla DENY coincide — Tracer devuelve una decisión DENY (tu sistema debe entonces bloquear la transacción)
Las verificaciones de límite e incrementos de contadores son transaccionales. Si una transacción es denegada (por límites o reglas) o marcada para revisión, todos los incrementos de contadores se revierten atómicamente. Esto previene fugas de límites 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
Los límites omitidos se reportan por transparencia pero no participan de la decisión DENY y sus contadores no se incrementan. La verificación de la ventana usa hora del servidor, no el transactionTimestamp provisto por el cliente, para prevenir ataques de manipulación de timestamp.
Por qué hora del servidor en vez de transactionTimestamp. El cliente puede establecer transactionTimestamp con cualquier valor — incluyendo uno forjado para caer dentro de una ventana activa cuando la transacción real caería fuera. Si Tracer confiara en el reloj del cliente para enforcement de ventana de tiempo, cualquiera con acceso al payload podría burlar límites de horario restringido. Anclar la verificación al reloj del propio Tracer elimina esa superficie de ataque. La desventaja es que pequeños desvíos de reloj entre pods de Tracer pueden causar skips en casos de borda cerca del límite de la ventana; en la práctica, los relojes sincronizados vía NTP mantienen esto en milisegundos de un 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 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 decisión DENY (tu sistema debe bloquear la transacción)

​
Crear un límite

Crea límites usando POST /v1/limits. Los límites se crean en estado DRAFT por defecto. Un límite requiere:
  • name: Un nombre descriptivo (ej.: “Límite Diario Tarjeta Corporativa”)
  • limitType: DAILY, WEEKLY, MONTHLY, CUSTOM o PER_TRANSACTION
  • maxAmount: Monto máximo como valor decimal (ej., "50000.00")
  • currency: Código de moneda ISO 4217 (ej.: 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 (ej.: "09:00")
  • activeTimeEnd: Fin de la ventana de tiempo diaria en formato HH:MM (ej.: "17:00")
  • customStartDate: Fecha de inicio para límites CUSTOM (timestamp ISO 8601, requerido para CUSTOM)
  • customEndDate: Fecha de fin para límites CUSTOM (timestamp ISO 8601, requerido para CUSTOM)
Los nombres de límite deben ser globalmente únicos entre todos los límites no eliminados — a diferencia de los nombres de regla, que son únicos solo dentro de su contexto de alcance. La unicidad se impone sobre el nombre tal como se almacena, después de recortar los espacios iniciales y finales: la comparación distingue mayúsculas y minúsculas y no colapsa los espacios interiores, así que Daily Card Limit y daily card limit son dos límites distintos y 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 detalles de campos, consulta la Referencia de 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 recuperar la definición completa del límite incluyendo alcances y estado actual.

​
Leer el consumo

​
Desde la decisión

Cada respuesta de POST /v1/validations lleva limitUsageDetails, con una entrada por límite que Tracer verificó. Cada entrada reporta:
  • limitId y limitAmount — qué tope se verificó y su techo
  • currentUsage — el consumo proyectado del período actual y del alcance coincidente de ese tope si esta transacción se permite
  • attemptedAmount — el monto verificado contra el tope
  • exceeded — si el monto intentado llevaría este tope más allá de su techo; todos los topes se evalúan, así que más de una entrada puede traer 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 períodos y alcances, así que úsalo para revisar el consumo general de un límite y no para responder cuánto le queda a un cliente en el período actual. Un contador se elimina 90 días después de que termina su período (consulta Seguimiento de uso), así que en un límite de larga duración este total cubre solo los períodos aún conservados, no toda la vida del límite.

​
Actualizar un límite

Actualiza límites usando PATCH /v1/limits/{id}. Los campos limitType y currency son inmutables y no pueden cambiarse 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 período actual ya consumió, las transacciones subsiguientes serán denegadas hasta que empiece el período siguiente.

​
Ciclo de vida de los límites

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

Figura 2. Ciclo de vida de los límites

​
Estados

​
Transiciones

​
Mejores prácticas

Recomendaciones para gestión efectiva de límites.

​
Nomenclatura

  • Sé descriptivo - Incluye el alcance y tipo en el nombre
  • Usa patrones consistentes - ej., “Diario Límite”

​
Diseño de alcance

  • Comienza amplio, refina según sea necesario - Comienza con límites a nivel de segmento, agrega a nivel de cuenta para excepciones
  • Evita alcances superpuestos - Múltiples límites en el mismo alcance pueden causar confusión
  • Usa tipos de transacción - Diferentes métodos de pago pueden necesitar diferentes límites

​
Diseño de ventanas de tiempo

  • Usa para cumplimiento regulatorio - Límites nocturnos de PIX del BACEN son un caso de uso común
  • Considera el impacto de zona horaria - Las ventanas de tiempo usan UTC; considera el desfase horario de tus usuarios
  • Combina con períodos personalizados - Usa ventanas de tiempo dentro de períodos personalizados para controles precisos de campañas

​
Monitoreo

  • Lee el payload de la decisión - limitUsageDetails muestra cuánto consumió cada transacción de cada tope
  • Revisa las transacciones denegadas - Tasas altas de denegación pueden indicar límites demasiado restrictivos
  • Ajusta estacionalmente - Considera aumentos temporales de límites durante períodos de alto gasto o usa límites CUSTOM para rangos de fechas específicos
Tropezones comunes al trabajar con límites:
  • “Mi cliente está reportando sobregasto — debería haber chocado con el límite.” Verifica si el límite está ACTIVE. Un límite en DRAFT o INACTIVE no se evalúa. 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 período actual ya consumió más que el nuevo techo, las transacciones subsecuentes se denegarán hasta que empiece el período siguiente.
  • “Intenté eliminar un límite ACTIVE y fue rechazado.” La eliminación responde 422 con el código 0363. Envía POST /v1/limits/{id}/deactivate primero, luego DELETE /v1/limits/{id}. Es intencional: previene eliminar accidentalmente un enforcement activo.
  • “GET /v1/limits/{id}/usage reporta más de lo que el cliente gastó en este período.” Ese endpoint totaliza los contadores de uso registrados para el límite, entre períodos y alcances. Para el período actual, lee limitUsageDetails en la respuesta de validación.

​
Referencia rápida

Endpoints y opciones de configuración clave.

​
Endpoints

Para la definición de los tipos de límite (DAILY, WEEKLY, MONTHLY, CUSTOM, PER_TRANSACTION), los campos opcionales de ventana de tiempo y período personalizado, y la lista completa de campos de alcance, consulta Tipos de límite anteriormente en esta guía y la referencia de la API para detalles a nivel de schema.