Antes de empezar
- Tracer en ejecución y accesible, con una API key. Consulta Primeros pasos
- El id de la cuenta, el portafolio o el segmento al que se aplica el tope
- El código de activo 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 se ejecutan contra http://localhost:4020.
Paso 1: Decide a qué se dirige el tope
Un límite lleva una lista de objetos de scope, y cada objeto indica a qué se aplica el límite. Estos campos están disponibles dentro de un objeto:
Los campos dentro de un mismo objeto se combinan con AND. Un campo que omitas actúa como comodín. Entre objetos, la lista se combina con OR, así que un límite con dos objetos se aplica cuando cualquiera de los dos coincide.
La decisión que responde a «R$ 20,000 por cuenta» es qué id nombras:
- Una cuenta, su propio presupuesto
- Un segmento, un presupuesto compartido
- Acotado a un riel
Un límite también lleva un
asset, y Tracer solo verifica un límite contra una transacción cuando ambos coinciden. Tracer no verifica un límite creado en BRL contra una transacción en USD. 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 tope como cuándo empieza un nuevo conteo. Tracer ofrece cinco:
«al mes» corresponde a
MONTHLY.
CUSTOM toma customStartDate y customEndDate, y es la forma que sirve para una campaña o una promoción. Esos dos campos pertenecen a CUSTOM. Tracer los rechaza en los otros cuatro tipos. Para restringir un tope a ciertas horas del día en cambio, consulta ventanas de tiempo.
Paso 3: Crea el límite
POST /v1/limits almacena la definición. Tracer la crea en DRAFT y todavía no la verifica contra transacciones.
201. El cuerpo lleva el límite almacenado. Dos campos importan ahora:
Los nombres son únicos entre límites, y el conjunto de caracteres es reducido.
name acepta letras y dígitos ASCII, espacios, y -, _, ., (, ). Tracer rechaza un acento, o un guion escrito como raya, con 0371. Tracer rechaza un nombre que ya tiene otro límite activo, con 0442. Eliminar un límite libera su nombre de nuevo.Paso 4: Actívalo
Tracer no verifica un límite en
DRAFT. Activarlo es lo que lo pone en el flujo de pago:
status en ACTIVE. Desde aquí, Tracer verifica contra este límite cada POST /v1/validations cuya transacción coincida con el scope y el asset.
Activar a mitad de mes no importa el historial del mes. Tracer cuenta una transacción contra un límite en el momento en que decide sobre ella. El gasto que ocurrió mientras el límite estaba en
DRAFT no entra en el conteo. Un tope activado el día 20 rige lo que pasa desde el día 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 verificó:
En la entrada de arriba, una compra de R$ 1,500 llevó un mes de 18,500 a exactamente 20,000 y agotó el tope. Tracer deniega la siguiente transacción de esa cuenta hasta agosto.
Cuando una transacción excede un límite, la decisión es
DENY y reason es limit_exceeded. Tracer no suma al conteo el monto que habría cruzado el tope. Un límite produce una denegación, no una marca para revisión. Para ir de una denegación así hasta el 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, no de un período. Suma los contadores de uso registrados contra él, entre los períodos y scopes 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.
Tracer elimina un contador 90 días después de que termina su período. En un límite de larga duración, este total cubre solo los períodos que todavía se conservan, no todo el ciclo de vida del límite. Consulta Seguimiento de uso.
Consulta Obtener una instantánea de uso de un límite.
Paso 6: Cámbialo, páusalo, elimínalo
1
Sube o baja el tope
name, description, maxAmount y scopes son editables, igual que los campos de ventana de tiempo y de período personalizado. limitType y asset no lo son. Tracer rechaza una solicitud que envíe cualquiera de los dos con 0380, y un período o un asset distintos significan un límite nuevo. Tracer rechaza un cuerpo vacío con 0183. Consulta Actualizar un límite.Cambiar el tope no borra el conteo en curso. Si lo bajas por debajo de lo que el período actual ya consumió, Tracer deniega a la cuenta hasta que empiece el siguiente período.2
Deja de aplicarlo
INACTIVE y Tracer deja de verificarlo. Conserva su definición y su lugar en el , y POST /v1/limits/{limitId}/activate lo devuelve al flujo de pago. Consulta Desactivar un límite.3
Devuélvelo a borrador
INACTIVE a DRAFT. Consulta Devolver un límite a borrador.4
Elimínalo
204. Primero tienes que desactivar un límite que esté ACTIVE. Tracer rechaza la eliminación con 0363, que es lo que evita que un tope activo 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 scope que definiste en el paso 1:
name, status, limit_type, account_id, segment_id, portfolio_id, merchant_id, transaction_type y sub_type filtran todos. Los resultados se paginan por cursor. Consulta Listar límites, y Obtener un límite para uno por su id.
Qué sale mal
Códigos de error
La lista completa está en la lista de errores de Tracer.