Límites de gasto

Documentation Index

Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt

Use this file to discover all available pages before exploring further.

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), se reinician automáticamente en la frontera del período, 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. 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: Monitorea el uso y los montos restantes instantáneamente
• Reinicios automáticos: Los límites diarios, semanales, mensuales y personalizados se reinician automáticamente
• 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

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

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 durante todo el período de 5 días. Después del 30 de noviembre, el límite ya no se aplica.

​

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 TRC-0125.
• 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 rastrea:

• Uso actual - Monto total consumido en el período actual (como valor decimal)
• Porcentaje de utilización - Porcentaje del límite usado
• Tiempo de reinicio - Cuándo el límite se reiniciará a cero

Los contadores de uso se retienen por 90 días después de la expiración para fines de auditoría, y luego son limpiados automáticamente por un worker en segundo plano.

---

​

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:

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)

​

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 R$45.000 y llega una nueva transacción de R$ 8.000:

• Uso proyectado: 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)

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.

---

​

Consultar uso del límite

---

Monitorea el consumo del límite usando GET /v1/limits/{id}/usage. La respuesta incluye:

• currentUsage: Monto consumido en el período actual
• utilizationPercent: Porcentaje del límite utilizado
• nearLimit: True cuando utilizationPercent > 80 — estrictamente mayor que 80%, no igual (para gestión proactiva)
• resetAt: Cuándo se reinicia el límite (solo DAILY, WEEKLY, MONTHLY y CUSTOM)

---

​

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.

---

​

Ciclo de vida de los límites

---

Los límites siguen el mismo ciclo de vida que las reglas:

​

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

• Observa los indicadores nearLimit - Contacta proactivamente a los clientes que se acercan a los límites
• 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

---

​

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.