> ## 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.
# Límites de gasto
> Configura los límites de gasto de Tracer por cuenta, portafolio o segmento con periodos diarios, semanales, mensuales y personalizados, ventanas de tiempo y controles de ciclo de vida.
export const GMetadata = ({children}) =>
{children}
;
export const GAuditTrail = ({children}) =>
{children}
;
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:
| Tipo | Descripción | Conteo del periodo |
| ----------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `DAILY` | Monto máximo por día | Un conteo nuevo empieza cada día calendario a las 00:00 UTC |
| `WEEKLY` | Monto máximo por semana | Un conteo nuevo empieza cada semana ISO, el lunes a las 00:00 UTC |
| `MONTHLY` | Monto máximo por mes | Un conteo nuevo empieza el día 1 del mes a las 00:00 UTC |
| `CUSTOM` | Monto máximo dentro de un rango de fechas definido por el usuario | Un solo conteo para todo el rango; a partir de `customEndDate` Tracer deja de verificar el límite |
| `PER_TRANSACTION` | Monto máximo por transacción individual | No se mantiene ningún conteo; cada transacción se verifica de forma independiente |
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](#read-consumption).
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:
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 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 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](/es/reference/products/tracer/create-limit).
***
## Listar y consultar límites
***
Consulta límites para gestión y auditoría usando `GET /v1/limits`.
### Parámetros de consulta
| Parámetro | Tipo | Descripción |
| ------------------ | ------- | ---------------------------------------------------------------------------------- |
| `name` | string | Filtra por nombre (coincidencia parcial sin distinción de mayúsculas y minúsculas) |
| `status` | string | Filtra por estado (DRAFT, ACTIVE, INACTIVE) |
| `limit_type` | string | Filtra por tipo de límite (DAILY, WEEKLY, MONTHLY, CUSTOM, PER\_TRANSACTION) |
| `account_id` | string | Filtra por alcance: ID de cuenta |
| `segment_id` | string | Filtra por alcance: ID de segmento |
| `portfolio_id` | string | Filtra por alcance: ID de portafolio |
| `merchant_id` | string | Filtra por alcance: ID de comercio |
| `transaction_type` | string | Filtra por alcance: tipo de transacción (CARD, WIRE, PIX, CRYPTO) |
| `sub_type` | string | Filtra por alcance: subtipo (por ejemplo, debit, credit) |
| `limit` | integer | Elementos por página (predeterminado: 10, máximo: 100) |
| `cursor` | string | Cursor de paginación |
| `sort_by` | string | Campo de ordenamiento: `created_at`, `updated_at`, `name`, `max_amount` |
| `sort_order` | string | Dirección de ordenamiento: `ASC`, `DESC` (predeterminado: DESC) |
### 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](#usage-tracking)). 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:
### Estados
| Estado | Descripción |
| ---------- | ------------------------------------------------------------------------------------------------------------------ |
| `DRAFT` | Límite creado pero no activo; se puede modificar libremente |
| `ACTIVE` | El límite se verifica durante las validaciones |
| `INACTIVE` | El límite no se verifica; se conserva para el registro de auditoría; se puede reactivar |
| `DELETED` | Eliminado de forma permanente; no aparece en los listados |
### Transiciones
| Operación | Desde | Hasta | Descripción |
| -------------------- | --------------- | -------- | ------------------------------------------------------------------ |
| Crear | - | DRAFT | Los límites se crean en estado DRAFT de forma predeterminada |
| Activar | DRAFT, INACTIVE | ACTIVE | Empieza a verificar este límite |
| Desactivar | ACTIVE | INACTIVE | Deja de verificar este límite |
| Convertir a borrador | INACTIVE | DRAFT | Vuelve a borrador para editar |
| Eliminar | DRAFT, INACTIVE | DELETED | Elimina de forma permanente (no se pueden eliminar límites ACTIVE) |
***
## 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 {Segment} {Type} Limit"
| Menos claro | Más claro |
| ----------- | -------------------------------- |
| `Limit 1` | `Daily Corporate Card Limit` |
| `VIP limit` | `Monthly VIP Pix Limit` |
| `BF promo` | `Custom Black Friday Card 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
| Operación | Método | Endpoint |
| --------------------------- | ------ | ---------------------------- |
| Crear límite | POST | `/v1/limits` |
| Listar límites | GET | `/v1/limits` |
| Obtener límite | GET | `/v1/limits/{id}` |
| Actualizar límite | PATCH | `/v1/limits/{id}` |
| Activar límite | POST | `/v1/limits/{id}/activate` |
| Desactivar límite | POST | `/v1/limits/{id}/deactivate` |
| Convertir límite a borrador | POST | `/v1/limits/{id}/draft` |
| Eliminar límite | DELETE | `/v1/limits/{id}` |
| Obtener uso | GET | `/v1/limits/{id}/usage` |
Para las definiciones de tipos de límite (DAILY, WEEKLY, MONTHLY, CUSTOM, PER\_TRANSACTION), consulta [Tipos de límite](#limit-types) 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](/es/reference/products/tracer/create-limit) tiene los detalles a nivel de esquema.