Overview Retrieve the hierarchical commission policy JSON for a specific entity. Policies define commission percentages based on lottery, bet type, and multiplier ranges.
Endpoints Get Banca Policy GET /api/v1/bancas/:id/commission-policy
Authorization: ADMIN onlyGet Ventana Policy GET /api/v1/ventanas/:id/commission-policy
Authorization: ADMIN can view any ventana, VENTANA can view their ownGet User Policy GET /api/v1/users/:id/commission-policy
Authorization: ADMIN, or the user themselves, or VENTANA viewing their vendorPath Parameters UUID of the banca, ventana, or user
Response Indicates if the request was successful
Entity details with commission policy Entity code (for banca/ventana)
User role (for user only): ADMIN, VENTANA, VENDEDOR
Commission policy configuration (null if not set) Policy schema version (currently 1)
ISO 8601 date when policy becomes active (null = no start limit)
ISO 8601 date when policy expires (null = no end limit)
Default commission percentage (0-100, max 2 decimals)
Array of commission rules (evaluated in order) Unique rule identifier (UUID)
Loteria UUID (null = wildcard, matches any loteria)
Bet type: NUMERO, REVENTADO, or null (wildcard)
Specific multiplier UUID (optional, for distinguishing multipliers with same value)
Multiplier range (inclusive)
min (number): Minimum multiplier valuemax (number): Maximum multiplier value (must equal min) Commission percentage for this rule (0-100, max 2 decimals)
Read-only: Embedded multiplier details for frontend hydration
id (string): Multiplier UUIDname (string): Multiplier namevalueX (number): Multiplier valuekind (string): NUMERO or REVENTADOloteriaId (string): Loteria UUIDisActive (boolean): Whether multiplier is active Examples Get Banca Policy
Get Ventana Policy
Get User Policy
curl -X GET "https://api.example.com/api/v1/bancas/550e8400-e29b-41d4-a716-446655440000/commission-policy" \ -H "Authorization: Bearer YOUR_TOKEN"
Response Example { "success" : true , "data" : { "id" : "550e8400-e29b-41d4-a716-446655440000" , "name" : "Banca Central" , "code" : "BC001" , "commissionPolicyJson" : { "version" : 1 , "effectiveFrom" : "2025-01-01T00:00:00.000Z" , "effectiveTo" : null , "defaultPercent" : 5.0 , "rules" : [ { "id" : "rule-uuid-1" , "loteriaId" : "loteria-uuid" , "betType" : "NUMERO" , "multiplierId" : "multiplier-uuid" , "multiplierRange" : { "min" : 80 , "max" : 80 }, "percent" : 8.5 , "multiplier" : { "id" : "multiplier-uuid" , "name" : "Base 80x" , "valueX" : 80 , "kind" : "NUMERO" , "loteriaId" : "loteria-uuid" , "isActive" : true } }, { "id" : "rule-uuid-2" , "loteriaId" : null , "betType" : "REVENTADO" , "multiplierId" : null , "multiplierRange" : { "min" : 0 , "max" : 999 }, "percent" : 12.0 , "multiplier" : null } ] } } }
Resolution Priority Commission policies follow a hierarchical resolution with first match wins :
USER policy (highest priority)VENTANA policyBANCA policy (lowest priority)
Within each policy, rules are evaluated in array order. The first rule matching all conditions (loteriaId, betType, multiplier range) is used.
The embedded multiplier object is populated by the backend for frontend convenience. It represents the actual multiplier entity that matches the rule’s criteria.
Error Responses 404 Not Found
403 Forbidden
401 Unauthorized
{ "success" : false , "error" : "Banca no encontrada" , "code" : "BANCA_NOT_FOUND" }
Set Commission Policy Update commission policy configuration
Commission Analytics View commission metrics and reports
Implementation Details From src/api/v1/controllers/commission.controller.ts:136-162:
async getBancaCommissionPolicy ( req : AuthenticatedRequest , res : Response ) { const { id } = req . params ; const banca = await prisma . banca . findUnique ({ where: { id }, select: { id: true , name: true , code: true , commissionPolicyJson: true , }, }); if ( ! banca ) { throw new AppError ( "Banca no encontrada" , 404 , { code: "BANCA_NOT_FOUND" }); } const commissionPolicyJson = await embedMultipliersInPolicy ( banca . commissionPolicyJson ); return success ( res , { ... banca , commissionPolicyJson }); }
The embedMultipliersInPolicy helper performs a single batch query to fetch all related multipliers and embed them in the policy rules for frontend hydration.