Multiplier Overrides - Banca Management Backend

Overview

Multiplier overrides allow you to set custom base multipliers for specific users (vendedores) or ventanas, overriding the default lottery multipliers. Use cases:

VIP vendedor incentives
Promotional multipliers for specific outlets
Testing new multiplier values
Regional pricing variations

Create Override

Endpoint

POST /api/v1/multiplier-overrides

Authorization: ADMIN, VENTANA (VENTANA can only create for their own ventana)

Request Body

scope

string

required

Override scope:

USER: User-specific override (highest priority)
VENTANA: Ventana-wide override

scopeId

string

required

UUID of the user or ventana (depending on scope)

loteriaId

string

required

UUID of the lottery

multiplierType

string

required

Type of multiplier:

NUMERO: Standard bet multiplier
REVENTADO: REVENTADO multiplier
Or custom type string

baseMultiplierX

number

required

Override multiplier value (must be positive, max 9999)

Examples

curl -X POST "https://api.example.com/api/v1/multiplier-overrides" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "USER",
    "scopeId": "vendedor-uuid",
    "loteriaId": "loteria-uuid",
    "multiplierType": "NUMERO",
    "baseMultiplierX": 85
  }'

Response

success

boolean

Indicates if the request was successful

data

object

Created multiplier override

Show properties

string

Override UUID

scope

string

USER or VENTANA

scopeId

string

User or ventana UUID

loteriaId

string

Lottery UUID

multiplierType

string

Multiplier type

baseMultiplierX

number

Override multiplier value

isActive

boolean

Whether override is active

createdAt

string

Creation timestamp

updatedAt

string

Last update timestamp

Update Override

Endpoint

PUT /api/v1/multiplier-overrides/:id

Authorization: ADMIN, VENTANA (VENTANA can only update their own overrides)

Path Parameters

string

required

UUID of the multiplier override

Request Body

baseMultiplierX

number

New multiplier value (must be positive, max 9999)

isActive

boolean

Enable or disable the override

At least one field must be provided for update.

Example

curl -X PUT "https://api.example.com/api/v1/multiplier-overrides/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "baseMultiplierX": 87,
    "isActive": true
  }'

List Overrides

Endpoint

GET /api/v1/multiplier-overrides

Authorization: Authenticated users (results filtered by role)

Query Parameters

scope

string

Filter by scope: USER or VENTANA

scopeId

string

Filter by user or ventana UUID

loteriaId

string

Filter by lottery UUID

multiplierType

string

Filter by multiplier type

isActive

boolean

Filter by active status

page

number

default:"1"

Page number for pagination

pageSize

number

default:"10"

Items per page (max 100)

Examples

curl -X GET "https://api.example.com/api/v1/multiplier-overrides?scope=USER&isActive=true" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

success

boolean

Indicates if the request was successful

data

array

Array of multiplier overrides

Get Override by ID

Endpoint

GET /api/v1/multiplier-overrides/:id

Authorization: Authenticated users (role-based access)

Path Parameters

string

required

UUID of the multiplier override

Example

curl -X GET "https://api.example.com/api/v1/multiplier-overrides/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_TOKEN"

Delete Override (Soft Delete)

Endpoint

DELETE /api/v1/multiplier-overrides/:id

Authorization: ADMIN, VENTANA (VENTANA can only delete their own overrides)

Path Parameters

string

required

UUID of the multiplier override

Optional Body

deletedReason

string

Optional reason for deletion (for audit trail)

Example

curl -X DELETE "https://api.example.com/api/v1/multiplier-overrides/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "deletedReason": "Promoción finalizada"
  }'

Restore Override

Endpoint

PATCH /api/v1/multiplier-overrides/:id/restore

Authorization: ADMIN, VENTANA (VENTANA can only restore their own overrides)

Path Parameters

string

required

UUID of the multiplier override to restore

Example

curl -X PATCH "https://api.example.com/api/v1/multiplier-overrides/550e8400-e29b-41d4-a716-446655440000/restore" \
  -H "Authorization: Bearer YOUR_TOKEN"

Resolution Priority

When determining the base multiplier for a ticket, the system follows this hierarchy:

1. User Multiplier Override

Highest priority - applies to specific vendedor + lottery

SELECT baseMultiplierX FROM MultiplierOverride
WHERE scope = 'USER' AND scopeId = userId AND loteriaId = ? AND isActive = true

2. Ventana Multiplier Override

Second priority - applies to all users in ventana

SELECT baseMultiplierX FROM MultiplierOverride
WHERE scope = 'VENTANA' AND scopeId = ventanaId AND loteriaId = ? AND isActive = true

3. Banca Loteria Setting

Third priority - banca-level setting

4. Loteria Multiplier

Fourth priority - lottery default multiplier

5. System Default

Lowest priority - global fallback from environment

First match wins - the system stops searching as soon as it finds an active override at any level.

Best Practices

Use USER overrides sparingly

User overrides are powerful but create exceptions. Use them for:

VIP vendedores with proven track record
Temporary promotional incentives
Testing before rolling out system-wide

Document all user overrides and review them regularly.

VENTANA overrides for regional pricing

If different ventanas need different multipliers:

Use VENTANA scope instead of individual USER overrides
Ensures consistency across all vendedores in that outlet
Easier to manage and audit

Set expiration reminders

For promotional overrides, create calendar reminders to:

Review performance before expiration
Decide whether to extend or remove
Clean up inactive overrides

Monitor impact on revenue

Track commission costs and revenue impact:

SELECT scope, scopeId, 
       COUNT(*) as tickets,
       SUM(amount) as total_sales,
       AVG(finalMultiplierX) as avg_multiplier
FROM tickets
WHERE createdAt >= '2025-03-01'
GROUP BY scope, scopeId

Error Responses

{
  "success": false,
  "error": "Validation failed",
  "issues": [
    {
      "path": ["scope"],
      "message": "scope must be USER or VENTANA"
    }
  ]
}

List Multipliers

View base multipliers

Create Multiplier

Create lottery multipliers

Commission Policies

Related hierarchical system

Implementation Details

From src/api/v1/controllers/multiplierOverride.controller.ts:13-17:

async create(req: Request, res: Response) {
  const actor = req.user as Actor;
  const result = await MultiplierOverrideService.create(actor, req.body);
  return createdResponse(res, result);
}

Role-based access control is enforced in the service layer, ensuring VENTANA users can only manage overrides for their own ventana.

Authentication

Tickets

Sorteos (Draws)

Loterias

Bancas & Ventanas

Users & Vendedores

Commissions

Restrictions & Rules

Multipliers

Payments

Analytics & Reports

Accounts

Activity & Audit

​Overview

​Create Override

​Endpoint

​Request Body

​Examples

​Response

​Update Override

​Endpoint

​Path Parameters

​Request Body

​Example

​List Overrides

​Endpoint

​Query Parameters

​Examples

​Response

​Get Override by ID

​Endpoint

​Path Parameters

​Example

​Delete Override (Soft Delete)

​Endpoint

​Path Parameters

​Optional Body

​Example

​Restore Override

​Endpoint

​Path Parameters

​Example

​Resolution Priority

​Best Practices

​Error Responses

​Related Endpoints

List Multipliers

Create Multiplier

Commission Policies

​Implementation Details

Build docs developers (and LLMs) love

Overview

Create Override

Endpoint

Request Body

Examples

Response

Update Override

Endpoint

Path Parameters

Request Body

Example

List Overrides

Endpoint

Query Parameters

Examples

Response

Get Override by ID

Endpoint

Path Parameters

Example

Delete Override (Soft Delete)

Endpoint

Path Parameters

Optional Body

Example

Restore Override

Endpoint

Path Parameters

Example

Resolution Priority

Best Practices

Error Responses

Related Endpoints

Implementation Details