Skip to main content

​
GET /api/v1/loterias/:id/preview_schedule

Previews the sorteos that would be generated based on a loteria’s drawSchedule configuration without actually creating them in the database.
Use this endpoint to verify schedule changes before generating sorteos with Seed Sorteos.

​
Authentication

Requires authentication. Available to all roles.

​
Path Parameters

​
id
string
required
UUID of the loteria to preview

​
Query Parameters

​
start
string
default:"now"
Start date/time for preview range.Format: ISO 8601 datetime or date stringExamples:
  • "2025-03-03T00:00:00-06:00" (specific datetime)
  • "2025-03-03" (start of day in CR timezone)
Default: Current server time
​
days
integer
default:"1"
Number of days to preview.Min: 1, Max: 31
​
limit
integer
default:"200"
Maximum number of sorteos to return.Min: 1, Max: 1000
​
allowPast
boolean
default:"false"
Whether to include sorteos in the past.
  • true: Show all sorteos in date range
  • false: Only show future sorteos

​
Response

​
success
boolean
Indicates if the operation was successful
​
data
array
Array of preview sorteo objects
​
meta
object
Preview metadata

​
Example Request (Today)

curl "https://api.example.com/api/v1/loterias/550e8400-e29b-41d4-a716-446655440000/preview_schedule?days=1" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Example Request (Next Week)

curl "https://api.example.com/api/v1/loterias/550e8400-e29b-41d4-a716-446655440000/preview_schedule?start=2025-03-03&days=7" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Example Response

{
  "success": true,
  "data": [
    {
      "scheduledAt": "2025-03-03T12:55:00-06:00",
      "name": "Lotto 12:55",
      "loteriaId": "550e8400-e29b-41d4-a716-446655440000",
      "alreadyExists": false
    },
    {
      "scheduledAt": "2025-03-03T18:55:00-06:00",
      "name": "Lotto 18:55",
      "loteriaId": "550e8400-e29b-41d4-a716-446655440000",
      "alreadyExists": true
    },
    {
      "scheduledAt": "2025-03-04T12:55:00-06:00",
      "name": "Lotto 12:55",
      "loteriaId": "550e8400-e29b-41d4-a716-446655440000",
      "alreadyExists": false
    }
  ],
  "meta": {
    "count": 3,
    "from": "2025-03-03",
    "to": "2025-03-04",
    "allowPast": false
  }
}

​
Error Responses

{
  "success": false,
  "message": "start inválido"
}

​
How Scheduling Works

The preview uses the loteria’s rulesJson.drawSchedule to calculate occurrences:
1

Parse Schedule Rules

Read frequency, times, and optional daysOfWeek from loteria configuration.
2

Calculate Occurrences

Generate all possible draw times within the specified date range.
3

Filter by Days

If daysOfWeek is specified, filter to only those days.
4

Filter by allowPast

If allowPast: false, remove sorteos before current time.
5

Check Existing

Query database to see which sorteos already exist at those times.
6

Apply Limit

Return up to limit sorteos (default 200).

​
Understanding alreadyExists

The alreadyExists flag indicates whether a sorteo already exists in the database at that exact scheduledAt time.
Use cases:
Before seeding sorteosCheck which sorteos need to be created:
curl "https://api.example.com/api/v1/loterias/{id}/preview_schedule?days=7"
Result:
  • alreadyExists: false: Will be created
  • alreadyExists: true: Already exists, will be skipped

​
Date Range Examples

# Preview sorteos for today
curl "https://api.example.com/api/v1/loterias/{id}/preview_schedule?days=1"

​
Schedule Configuration Examples

Configuration:
{
  "drawSchedule": {
    "frequency": "diario",
    "times": ["12:55", "18:55"]
  }
}
Preview Result (7 days):
  • 2 draws per day
  • 7 days × 2 = 14 sorteos

​
Timezone Handling

All times in drawSchedule are in Costa Rica timezone (GMT-6).
The preview:
  1. Parses start date in Costa Rica timezone
  2. Calculates date range using CR timezone
  3. Generates sorteos with CR times
  4. Returns ISO 8601 with timezone offset (-06:00)
See Timezone Handling for details.

​
Use Cases

Preview before running Seed Sorteos to verify:
  • Correct number of sorteos
  • Correct times
  • No unexpected duplicates
After updating drawSchedule, preview to confirm:
  • New times are included
  • Old times are removed (if applicable)
  • Days of week filter working
Check sorteo coverage for a date range:
  • Find gaps where sorteos are missing
  • Verify all expected times exist
  • Plan manual creation if needed
Estimate sorteo count for resource planning:
  • Preview a month to estimate database growth
  • Calculate expected ticket volume
  • Plan server capacity

Seed Sorteos

Actually create the previewed sorteos

Get Loteria

View current schedule configuration

Update Loteria

Modify draw schedule

List Sorteos

See existing sorteos

Build docs developers (and LLMs) love

Get started for freeTalk to us