Saltar al contenido principal
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: 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.
Esta guía es para 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 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
  • 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:

​
Hora de reinicio

resetTime mueve el inicio de cada periodo DAILY, WEEKLY y MONTHLY a otra hora del día, en formato HH:MM (24 horas, UTC). Sin él, cada periodo empieza a las 00:00 UTC. Defínelo al crear el límite. No puedes cambiarlo después. Tracer rechaza resetTime en un límite CUSTOM o PER_TRANSACTION con el código de error 0537. Cuando el límite tiene una ventana de tiempo, resetTime no debe caer dentro de la ventana. Puede ser igual a activeTimeStart o activeTimeEnd. Una hora de reinicio dentro de la ventana devuelve el código de error 0538.

​
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. La ventana nocturna de Pix va de las 20:00 a las 06:00 en hora de Brasilia (UTC-3), es decir, de las 23:00 a las 09:00 UTC:
  • limitType: DAILY
  • maxAmount: "1000.00"
  • activeTimeStart: "23:00"
  • activeTimeEnd: "09:00"
  • resetTime: "09:00"
  • Alcance: transacciones Pix
Tracer verifica las transacciones entre las 23:00 y las 09:00 UTC contra el límite de R$ 1,000. Este límite no afecta las transacciones fuera de esta ventana. resetTime: "09:00" inicia cada conteo diario cuando la ventana cierra. Sin él, el conteo se reinicia a las 00:00 UTC (21:00 en Brasilia), en medio de la ventana. Un cliente puede entonces gastar los R$ 1,000 completos antes de las 21:00 hora de Brasilia y otra vez después.
Actualiza todos los pods de Tracer a Midaz v4.2.0 o posterior antes de crear un límite con resetTime. Un pod en una versión anterior acepta la solicitud, pero descarta el campo. Hasta que todos los pods ejecuten v4.2.0, un pod anterior todavía reinicia el conteo a las 00:00 UTC.

​
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
  • scheme - Aplica a un esquema de pago, como CARD o PIX. transactionType es el nombre obsoleto de este campo
  • 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 de nivel de cuenta y uno de nivel de segmento. Tracer entonces verifica todos los límites aplicables de forma independiente en una sola transacción. Si la transacción supera cualquier límite aplicable, Tracer la deniega. Tracer no verifica ningún límite cuando una regla devuelve DENY o cuando la solicitud usa POST /v1/validations/rules-only.

​
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. Para contadores DAILY, WEEKLY y MONTHLY, expiresAt es 90 días después del reinicio del periodo. Para contadores CUSTOM, es 90 días después de customEndDate. Los contadores vencidos son elegibles para limpieza. La eliminación física requiere un proceso de limpieza habilitado que se ejecute correctamente.

​
Cómo funcionan los límites

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

​
Flujo de verificación de límites

Cómo Tracer verifica 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 Tracer omite un límite 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.

​
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"). No puede ser negativo. Un maxAmount de 0 deniega todas las transacciones en el alcance del límite.
  • asset: Código de activo de 1 a 100 letras mayúsculas (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)
  • resetTime: Inicio de cada periodo DAILY, WEEKLY o MONTHLY en formato HH:MM (por ejemplo, "09:00")
Los nombres de límites deben ser únicos entre tus 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 correcta de POST /v1/validations, 201 o 200, incluye limitUsageDetails. 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. Incluye la capacidad que retienen las reservas no confirmadas del ledger de Midaz. Para un límite PER_TRANSACTION, o un límite que Tracer omitió, es 0
  • 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 el periodo actual del límite. Su currentUsage es lo que consumió el alcance más usado en ese periodo, incluida la capacidad que retienen las reservas no confirmadas del ledger de Midaz. Para un límite PER_TRANSACTION, es 0. Para un límite con un maxAmount de 0, utilizationPercent es 100 y nearLimit es true.

​
Actualizar un límite

Actualiza límites usando PATCH /v1/limits/{id}. Los campos limitType, asset y resetTime 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 de nivel de segmento y agrega el nivel de cuenta para excepciones
  • Evita alcances superpuestos - Varios límites sobre el mismo alcance pueden generar confusión
  • Usa esquemas de pago - 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

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

​
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 de nivel de esquema.