Skip to main content

​
Overview

Commission analytics endpoints provide detailed insights into earned commissions with multi-dimensional filtering, period-based aggregation, and export capabilities.

​
Endpoints

​
List Commissions by Period

GET /api/v1/commissions
Retrieve commission totals aggregated by time period with dimension breakdowns. Authorization: VENDEDOR, VENTANA, ADMIN

​
Commission Detail by Lottery

GET /api/v1/commissions/detail
Get detailed commission breakdown by lottery and multiplier for a specific date. Authorization: VENDEDOR, VENTANA, ADMIN

​
Commission Tickets

GET /api/v1/commissions/tickets
View individual tickets that contributed to commissions with pagination. Authorization: VENDEDOR, VENTANA, ADMIN

​
Export Commissions

GET /api/v1/commissions/export
Export commission data in CSV, Excel, or PDF format. Authorization: VENDEDOR, VENTANA, ADMIN Rate Limit: 10 requests per minute

​
Query Parameters (List)

​
date
string
default:"today"
Date range preset: today, yesterday, week, month, or range
​
fromDate
string
Start date (ISO 8601 or YYYY-MM-DD) - required if date=range
​
toDate
string
End date (ISO 8601 or YYYY-MM-DD) - required if date=range
​
scope
string
required
Data scope:
  • mine: Own commissions (required for VENDEDOR and VENTANA)
  • all: System-wide (ADMIN only)
​
dimension
string
required
Aggregation dimension:
  • vendedor: By individual vendedor (VENDEDOR must use this)
  • ventana: By ventana
  • banca: By banca (ADMIN only)
​
ventanaId
string
Filter by specific ventana UUID (ADMIN only)
​
vendedorId
string
Filter by specific vendedor UUID (ADMIN and VENTANA)
​
bancaId
string
Filter by specific banca UUID (ADMIN only)

​
Query Parameters (Detail)

​
date
string
required
Specific date (YYYY-MM-DD format)
​
scope
string
required
Same as List endpoint
​
dimension
string
required
Same as List endpoint
​
ventanaId
string
Filter by ventana (ADMIN only)
​
vendedorId
string
Filter by vendedor (ADMIN and VENTANA)
​
bancaId
string
Filter by banca (ADMIN only)

​
Query Parameters (Tickets)

​
date
string
required
Specific date (YYYY-MM-DD)
​
loteriaId
string
required
Lottery UUID
​
multiplierId
string
required
Multiplier UUID
​
scope
string
required
Same as List endpoint
​
dimension
string
required
Same as List endpoint
​
page
number
default:"1"
Page number for pagination
​
pageSize
number
default:"20"
Items per page (max 100)

​
Query Parameters (Export)

​
format
string
required
Export format: csv, excel, or pdf
​
date
string
default:"today"
Same as List endpoint
​
fromDate
string
Same as List endpoint
​
toDate
string
Same as List endpoint
​
scope
string
required
Same as List endpoint
​
dimension
string
required
Same as List endpoint
​
includeBreakdown
boolean
default:"true"
Include lottery/multiplier breakdown in export
​
includeWarnings
boolean
default:"true"
Include policy resolution warnings

​
Response (List)

​
success
boolean
Indicates if the request was successful
​
data
array
Array of commission summaries by period
​
meta
object
Metadata about the response

​
Response (Detail)

​
success
boolean
Indicates if the request was successful
​
data
array
Array of commission details by lottery and multiplier

​
Response (Tickets)

​
success
boolean
Indicates if the request was successful
​
data
array
Array of tickets with commission details
​
meta
object
Pagination metadata

​
Examples

curl -X GET "https://api.example.com/api/v1/commissions?date=today&scope=mine&dimension=vendedor" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
RBAC Enforcement

Role-based access control is automatically enforced:
  • VENDEDOR: Can only view their own commissions (scope=mine, dimension=vendedor)
  • VENTANA: Can view their own and their vendedores’ commissions (scope=mine)
  • ADMIN: Can view all data with any dimension
The system automatically applies filters based on the authenticated user’s role and context: 
if (req.user.role === Role.VENDEDOR) {
  // Force scope=mine and dimension=vendedor
  filters.vendedorId = req.user.id;
} else if (req.user.role === Role.VENTANA) {
  // Force scope=mine, allow any dimension
  filters.ventanaId = req.user.ventanaId;
}

​
Implementation Details

From src/api/v1/controllers/commissions.controller.ts:19-140: 
async list(req: AuthenticatedRequest, res: Response) {
  const { date = "today", fromDate, toDate, scope, dimension, ...rest } = req.query;
  
  // Apply RBAC filters
  const context: AuthContext = {
    userId: req.user.id,
    role: req.user.role,
    ventanaId: req.user.ventanaId,
    bancaId: req.bancaContext?.bancaId || null,
  };
  const effectiveFilters = await applyRbacFilters(context, rest);
  
  // Resolve date range
  const dateRange = resolveDateRange(date, fromDate, toDate);
  
  // Fetch commission data
  const result = await CommissionsService.list(
    date, fromDate, toDate, filters, ventanaUserId
  );
  
  return success(res, result, {
    range: {
      fromAt: dateRange.fromAt.toISOString(),
      toAt: dateRange.toAt.toISOString(),
      tz: dateRange.tz,
    },
    effectiveFilters,
  });
}

Get Commission Policy

View commission policy configuration

Set Commission Policy

Update commission policy

Build docs developers (and LLMs) love

Get started for freeTalk to us