Antes de empezar
- Tracer en ejecución y alcanzable, con una API key — consulta Primeros pasos
- El id de la cuenta, el portafolio o el segmento al que aplica el tope
- La moneda de las transacciones que quieres limitar
- Familiaridad con los tipos de límite, las ventanas de tiempo y los períodos personalizados — consulta Límites de gasto
X-API-Key y corren contra http://localhost:4020.
Paso 1: Decide a qué se dirige el tope
Un límite lleva una lista de objetos de alcance, y cada objeto nombra a qué aplica el límite. Estos campos están disponibles dentro de un objeto:
Los campos dentro de un objeto se combinan con AND. Un campo que dejas fuera es un comodín. Entre objetos la lista se combina con OR, así que un límite con dos objetos aplica cuando cualquiera de los dos coincide.
La elección que decide la respuesta a “R$ 20.000 por cuenta” es qué id nombras:
- Una cuenta, su propio presupuesto
- Un segmento, un presupuesto compartido
- Restringido a un solo riel
Un límite también lleva una
currency, y Tracer comprueba un límite contra una transacción solo cuando las dos coinciden. Un límite creado en BRL no se comprueba contra una transacción en USD, así que una cartera que liquida en dos monedas necesita un límite para cada una.Paso 2: Elige el período
limitType decide tanto el tamaño de la ventana del techo como cuándo empieza un nuevo conteo. Tracer ofrece cinco:
“al mes” es
MONTHLY.
CUSTOM toma customStartDate y customEndDate y es la forma para una campaña o una promoción. Esos dos campos pertenecen a CUSTOM y se rechazan en los otros cuatro tipos. Para restringir un tope a ciertas horas del día, consulta las ventanas de tiempo.
Paso 3: Crea el límite
POST /v1/limits almacena la definición. Se crea en DRAFT, lo que significa que está almacenada pero todavía no se comprueba.
201. El cuerpo es el límite almacenado; dos campos importan ahora:
Los nombres son únicos entre límites, y el conjunto de caracteres es estrecho.
name acepta letras y dígitos ASCII, espacios y -, _, ., (, ). Un acento o un guion escrito como raya se rechaza con 0371. Un nombre que ya tiene otro límite vigente se rechaza con 0442; eliminar un límite libera su nombre de nuevo.Paso 4: Actívalo
Un límite en
DRAFT no se comprueba. La activación es lo que lo pone en el camino:
status en ACTIVE. Desde aquí, cada POST /v1/validations cuya transacción coincida con el alcance y la moneda se mide contra él.
Activar a mitad de mes no importa la historia del mes. Tracer cuenta una transacción contra un límite en el momento en que decide sobre ella, así que el gasto ocurrido mientras el límite estaba en
DRAFT no está en el conteo. Un tope activado el día 20 gobierna lo que pasa del 20 en adelante.Paso 5: Lee cuánto queda
Cada respuesta de
POST /v1/validations lleva limitUsageDetails, con una entrada por cada límite que Tracer comprobó:
En la entrada de arriba, una compra de R$ 1.500 llevó un mes de 18.500 a exactamente 20.000 — el tope está agotado, y la siguiente transacción de esa cuenta se deniega hasta agosto.
Cuando se supera un límite, la decisión es
DENY y reason es limit_exceeded; el importe que habría cruzado el techo no se suma al conteo. Un límite produce una denegación, no una marca para revisión. Para ir desde esa denegación de vuelta al límite que la causó, consulta Revisar una transacción denegada.
La otra lectura
GET /v1/limits/{limitId}/usage responde con un total del límite en lugar de un total de un período: suma los contadores de uso registrados contra él, entre los períodos y alcances que ha acumulado. Úsalo para revisar cuánto ha absorbido un límite en total — no para responder cuánto le queda a un cliente este mes.
Un contador se elimina 90 días después de que termina su período, 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. Consulta Seguimiento de uso.
Consulta Recuperar el uso de un límite.
Paso 6: Cámbialo, páusalo, quítalo
1
Sube o baja el techo
name, description, maxAmount y scopes son editables, y también lo son los campos de ventana de tiempo y de período personalizado. limitType y currency no lo son — una solicitud que envía cualquiera de los dos se rechaza con 0380, y un período o una moneda distintos significan un límite nuevo. Un cuerpo sin nada dentro se rechaza con 0183. Consulta Actualizar un límite.Cambiar el techo no borra el conteo en curso. Bájalo por debajo de lo que el período actual ya consumió y la cuenta queda denegada hasta que empiece el período siguiente.2
Detén la aplicación
INACTIVE y deja de comprobarse. Conserva su definición y su lugar en el , y POST /v1/limits/{limitId}/activate lo devuelve al camino. Consulta Desactivar un límite.3
Devuélvelo a borrador
INACTIVE a DRAFT. Consulta Devolver un límite a borrador.4
Quítalo
204. Un límite que está ACTIVE tiene que desactivarse primero — Tracer rechaza la eliminación con 0363, que es lo que impide que un techo vigente desaparezca por accidente. Consulta Eliminar un límite.Encuentra los límites que ya tienes
GET /v1/limits los lista, y filtra por los mismos campos de alcance que fijaste en el paso 1:
name, status, limit_type, account_id, segment_id, portfolio_id, merchant_id, transaction_type y sub_type filtran; los resultados se paginan con cursor. Consulta Listar límites, y Recuperar un límite para uno por id.
Qué sale mal
Códigos de error
La lista completa está en la Lista de errores de Tracer.