Skip to main content

​
POST /api/v1/loterias

Creates a new loteria (lottery) with optional configuration rules for draw schedules, digits, and REVENTADO settings.
Loterias define the game rules and schedules. Individual draws (sorteos) are created separately based on the loteria configuration.

​
Authentication

Requires authentication. Typically ADMIN role for creation.

​
Request Body

​
name
string
required
Unique name for the loteria.Examples: "Lotto", "Tica", "Monazo"Min: 2 characters
​
rulesJson
object
Configuration rules for the loteria.
​
isActive
boolean
default:"true"
Whether the loteria is active and available for use.

​
Response

​
success
boolean
Indicates if the operation was successful
​
data
object
The created loteria object

​
Example Request (Simple)

curl -X POST https://api.example.com/api/v1/loterias \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Lotto",
    "isActive": true
  }'

​
Example Request (With Schedule)

curl -X POST https://api.example.com/api/v1/loterias \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Lotto",
    "rulesJson": {
      "digits": 2,
      "drawSchedule": {
        "frequency": "diario",
        "times": ["12:55", "18:55"]
      },
      "reventadoConfig": {
        "enabled": true
      },
      "autoCreateSorteos": true
    },
    "isActive": true
  }'

​
Example Response

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Lotto",
    "rulesJson": {
      "digits": 2,
      "drawSchedule": {
        "frequency": "diario",
        "times": ["12:55", "18:55"]
      },
      "reventadoConfig": {
        "enabled": true
      },
      "autoCreateSorteos": true
    },
    "isActive": true,
    "createdAt": "2025-03-03T10:00:00-06:00",
    "updatedAt": "2025-03-03T10:00:00-06:00"
  }
}

​
Error Responses

{
  "success": false,
  "error": "El nombre de la lotería debe tener al menos 2 caracteres"
}

​
Configuration Examples

{
  "name": "Lotto",
  "rulesJson": {
    "digits": 2,
    "drawSchedule": {
      "frequency": "diario",
      "times": ["12:55", "18:55"]
    },
    "reventadoConfig": {
      "enabled": true
    }
  }
}

​
Draw Schedule Rules

The drawSchedule configuration determines when sorteos are automatically created:
1

Set Frequency

Currently only "diario" (daily) is supported.
2

Define Times

List all draw times in 24-hour format (Costa Rica timezone).Example: ["12:55", "18:55"] creates 2 draws per day.
3

Optional: Limit Days

Use daysOfWeek to restrict to specific days.Omit this field for daily draws on all days.
4

Enable Auto-Creation

Set autoCreateSorteos: true to enable automatic generation.

​
REVENTADO Configuration

REVENTADO is an extra multiplier feature that allows additional payouts on specific numbers.
When reventadoConfig.enabled: true:
  1. Sorteos created for this loteria will have reventadoEnabled: true
  2. Vendedores can sell REVENTADO bets on tickets
  3. During evaluation, admin can specify an extraMultiplierId for REVENTADO outcomes
  4. REVENTADO bets on the winning number receive extra payouts
See Multipliers Guide for details.

​
Auto-Create Sorteos

The autoCreateSorteos flag controls automatic sorteo generation:
Automatic Generation
  • Sorteos are created by cron job based on drawSchedule
  • Runs daily (configurable)
  • Creates sorteos for upcoming dates
  • Prevents duplicates (idempotent)

​
Activity Logging

Loteria creation is logged: 
{
  "action": "LOTERIA_CREATE",
  "targetType": "LOTERIA",
  "targetId": "loteria-uuid",
  "details": {
    "name": "Lotto",
    "description": "Lotería creada: Lotto"
  }
}

​
Next Steps

After creating a loteria:
1

Create Multipliers

Define multiplier values via Create Multiplier.
2

Preview Schedule

Verify sorteo generation with Preview Schedule.
3

Seed Sorteos

Generate initial sorteos via Seed Sorteos.
4

Configure Auto-Creation

Enable auto-creation cron job for ongoing sorteo generation.

List Loterias

Get all loterias

Preview Schedule

Preview generated sorteos

Seed Sorteos

Generate sorteos from schedule

Create Multiplier

Define payout multipliers

Build docs developers (and LLMs) love

Get started for freeTalk to us