Skip to main content

​
POST /api/v1/sorteos

Creates a new sorteo (lottery draw) for a specific loteria. The sorteo will be created in SCHEDULED status by default.
Sorteos can be created manually or automatically via the seed sorteos endpoint.

​
Authentication

Requires ADMIN role. Vendedores and regular users cannot create sorteos.

​
Request Body

​
loteriaId
string
required
UUID of the loteria this sorteo belongs to. The loteria must be active.
​
scheduledAt
string
required
ISO 8601 datetime when the sorteo is scheduled to run. Must be in Costa Rica timezone (GMT-6).Example: "2025-03-03T12:55:00-06:00" (12:55 PM Costa Rica time)
​
name
string
required
Display name for the sorteo. Typically includes the loteria name and time.Examples: "Lotto 12:55 PM", "Tica 6:55 PM"Min: 1 character, Max: 100 characters
​
digits
integer
default:"Inherited from loteria"
Number of digits for winning numbers (2 or 3).
  • 2 digits: Times/Tiempos lotteries (00-99)
  • 3 digits: Monazos lotteries (000-999)
If not provided, inherits from the loteria’s rulesJson.digits configuration.
​
isActive
boolean
default:"true"
Whether the sorteo is active and available for ticket sales.

​
Response

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

​
Example Request

curl -X POST https://api.example.com/api/v1/sorteos \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "loteriaId": "550e8400-e29b-41d4-a716-446655440000",
    "scheduledAt": "2025-03-03T12:55:00-06:00",
    "name": "Lotto 12:55 PM",
    "digits": 2,
    "isActive": true
  }'

​
Example Response

{
  "success": true,
  "data": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "loteriaId": "550e8400-e29b-41d4-a716-446655440000",
    "scheduledAt": "2025-03-03T12:55:00-06:00",
    "name": "Lotto 12:55 PM",
    "status": "SCHEDULED",
    "digits": 2,
    "isActive": true,
    "reventadoEnabled": true,
    "winningNumber": null,
    "hasWinner": false,
    "createdAt": "2025-03-03T10:00:00-06:00",
    "updatedAt": "2025-03-03T10:00:00-06:00"
  }
}

​
Error Responses

{
  "success": false,
  "error": "Lotería no encontrada"
}

​
Sorteo Lifecycle

After creation, a sorteo goes through the following states:
1

SCHEDULED

Initial state. Sorteo is created and waiting to be opened for sales.
2

OPEN

Sorteo is accepting ticket sales. Can be opened manually or automatically.
3

EVALUATED

Winning number has been set and tickets have been evaluated for winners.
4

CLOSED

Sorteo is closed. No more operations allowed (terminal state).

​
Digits Configuration

The digits field determines the valid range of numbers: 
{
  "digits": 2,
  "validNumbers": "00-99"
}

​
Timezone Handling

All sorteo times are in Costa Rica timezone (GMT-6). The system automatically handles UTC conversion for storage.
See Timezone Handling for details.

List Sorteos

Get all sorteos with filtering

Open Sorteo

Open a sorteo for ticket sales

Evaluate Sorteo

Set winning number and evaluate tickets

Seed Sorteos

Auto-generate sorteos from schedule

Build docs developers (and LLMs) love

Get started for freeTalk to us