Seed Sorteos

POST /api/v1/loterias/:id/seed_sorteos

Generates sorteos (lottery draws) based on a loteria’s drawSchedule configuration. Supports both automatic generation from schedule and manual creation of specific dates.

This endpoint is idempotent - running it multiple times with the same parameters will not create duplicate sorteos.

Authentication

Requires authentication. Typically ADMIN role.

Path Parameters

string

required

UUID of the loteria to seed sorteos for

Query Parameters

start

string

default:"now"

Start date for sorteo generation.Format: ISO 8601 datetime or date stringExamples:

"2025-03-03T00:00:00-06:00"
"2025-03-03"

Default: Current server time

days

integer

default:"1"

Number of days to generate sorteos for.Min: 1, Max: 31

dryRun

boolean

default:"false"

Preview mode - calculate sorteos without creating them.

true: Return preview without creating
false: Actually create sorteos in database

Request Body

scheduledDates

array

Optional: Specific dates to create sorteos for (overrides schedule calculation).Format: Array of ISO 8601 datetime stringsExample:

{
  "scheduledDates": [
    "2025-03-03T12:55:00-06:00",
    "2025-03-03T18:55:00-06:00",
    "2025-03-04T12:55:00-06:00"
  ]
}

When provided, only these specific dates are processed. The start and days parameters are ignored.

Response

success

boolean

Indicates if the operation was successful

data

object

Result summary

Show Result Object

created

array | integer

Sorteos created.

Array of sorteo objects (when created)
Integer count (in some responses)

skipped

array | integer

Sorteos skipped (already exist).

alreadyExists

array

List of dates that already have sorteos.

processed

array

All dates that were processed.

preview

array

Preview data (only in dry run mode).

note

string

Additional information or warnings.

Example Request (From Schedule)

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

Example Request (Specific Dates)

curl -X POST "https://api.example.com/api/v1/loterias/550e8400-e29b-41d4-a716-446655440000/seed_sorteos" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scheduledDates": [
      "2025-03-03T12:55:00-06:00",
      "2025-03-03T18:55:00-06:00"
    ]
  }'

Example Request (Dry Run)

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

Example Response (Success)

{
  "success": true,
  "data": {
    "created": [
      {
        "id": "sorteo-uuid-1",
        "name": "Lotto 12:55",
        "scheduledAt": "2025-03-03T12:55:00-06:00"
      },
      {
        "id": "sorteo-uuid-2",
        "name": "Lotto 18:55",
        "scheduledAt": "2025-03-03T18:55:00-06:00"
      }
    ],
    "skipped": 5,
    "alreadyExists": [
      "2025-03-04T12:55:00-06:00",
      "2025-03-04T18:55:00-06:00"
    ],
    "processed": [
      "2025-03-03T12:55:00-06:00",
      "2025-03-03T18:55:00-06:00",
      "2025-03-04T12:55:00-06:00",
      "2025-03-04T18:55:00-06:00"
    ]
  }
}

Example Response (Dry Run)

{
  "success": true,
  "data": {
    "created": [],
    "skipped": [],
    "alreadyExists": [],
    "preview": [
      {
        "name": "Lotto 12:55",
        "scheduledAt": "2025-03-03T12:55:00-06:00"
      },
      {
        "name": "Lotto 18:55",
        "scheduledAt": "2025-03-03T18:55:00-06:00"
      }
    ]
  }
}

Error Responses

{
  "success": false,
  "error": "Lotería inactiva"
}

Seeding Modes

From Schedule
Specific Dates

Automatic GenerationUses loteria’s drawSchedule to calculate sorteos:

POST /api/v1/loterias/{id}/seed_sorteos?start=2025-03-03&days=7

Process:

Read drawSchedule from rulesJson
Calculate occurrences for date range
Filter by daysOfWeek if specified
Create sorteos for each occurrence
Skip duplicates (idempotent)

Manual SelectionProvide exact dates to create:

{
  "scheduledDates": [
    "2025-03-03T12:55:00-06:00",
    "2025-03-05T20:00:00-06:00"
  ]
}

Process:

Use provided dates directly
Ignore start and days parameters
Create sorteos at exact times
Skip duplicates

Use case: Special or irregular draws

Auto-Create Flag

The autoCreateSorteos flag in rulesJson controls whether automatic cron jobs can seed sorteos. It does NOT block manual seeding via this endpoint.

Auto-Create Enabled
Auto-Create Disabled

autoCreateSorteos: true

Cron jobs can seed this loteria
Manual seeding always works
Default behavior

autoCreateSorteos: false

Cron jobs skip this loteria
Manual seeding requires special flag
Returns note about manual creation

To force manual seeding when disabled, the backend uses forceCreate: true flag internally (set automatically for manual API calls).

Idempotency

Safe to run multiple times - duplicate sorteos are automatically skipped based on unique constraint: (loteriaId, scheduledAt).

Example:

# First run: Creates 14 sorteos
POST /seed_sorteos?days=7
# Result: {"created": 14, "skipped": 0}

# Second run: All already exist
POST /seed_sorteos?days=7
# Result: {"created": 0, "skipped": 14}

# Overlapping run: Creates only new ones
POST /seed_sorteos?start=2025-03-06&days=7
# Result: {"created": 10, "skipped": 4}

Dry Run Mode

Use dryRun=true to preview what would be created without actually creating sorteos.

Example:

curl -X POST ".../seed_sorteos?days=7&dryRun=true"

Response:

{
  "data": {
    "preview": [
      {"name": "Lotto 12:55", "scheduledAt": "2025-03-03T12:55:00-06:00"},
      {"name": "Lotto 18:55", "scheduledAt": "2025-03-03T18:55:00-06:00"}
    ]
  }
}

Use before actual seeding to:

Verify schedule calculation
Check sorteo names
Estimate count

Inherited Configuration

Sorteos inherit configuration from the loteria at creation time.

Inherited fields:

digits: From rulesJson.digits
reventadoEnabled: From rulesJson.reventadoConfig.enabled
loteriaId: Parent loteria
isActive: Defaults to true

Example:

// Loteria
{
  "id": "loteria-uuid",
  "name": "Lotto",
  "rulesJson": {
    "digits": 2,
    "reventadoConfig": {"enabled": true}
  }
}

// Generated Sorteo
{
  "id": "sorteo-uuid",
  "loteriaId": "loteria-uuid",
  "name": "Lotto 12:55",
  "digits": 2,
  "reventadoEnabled": true
}

Common Use Cases

Daily Cron Job

Automated daily seedingCron job runs daily to seed next 3 days:

# Run at 1:30 AM CR time daily
POST /seed_sorteos?days=3

Ensures always have upcoming sorteos ready.

Weekly Batch

Weekly sorteo generationCreate entire week on Sunday:

POST /seed_sorteos?start=2025-03-03&days=7

Initial Setup

First-time loteria setupAfter creating loteria, seed first month:

POST /seed_sorteos?days=30

Special Draw

One-off special drawCreate specific sorteo outside schedule:

{
  "scheduledDates": [
    "2025-12-31T23:59:00-06:00"
  ]
}

Backfill Missing

Fix gaps in coverageAfter schedule change, backfill missing dates:

POST /seed_sorteos?start=2025-03-01&days=7

Existing sorteos skipped, only missing ones created.

Best Practices

Preview First

Use Preview Schedule to verify before seeding.

Use Dry Run

Test with dryRun=true to see what would be created.

Start Small

Begin with 1-3 days, verify, then scale up.

Monitor Results

Check created vs skipped counts to detect issues.

Schedule Regular Jobs

Set up cron job to seed upcoming days automatically.

Preview Schedule

Preview before seeding

Get Loteria

View schedule configuration

List Sorteos

Verify created sorteos

Create Sorteo

Manually create individual sorteo

Authentication

Tickets

Sorteos (Draws)

Loterias

Bancas & Ventanas

Users & Vendedores

Commissions

Restrictions & Rules

Multipliers

Payments

Analytics & Reports

Accounts

Activity & Audit

POST /api/v1/loterias/:id/seed_sorteos

Authentication

Path Parameters

Query Parameters

Request Body

Response

Example Request (From Schedule)

Example Request (Specific Dates)

Example Request (Dry Run)

Example Response (Success)

Example Response (Dry Run)

Error Responses

Seeding Modes

Auto-Create Flag

Idempotency

Dry Run Mode

Inherited Configuration

Common Use Cases

Best Practices

Preview Schedule

Get Loteria

List Sorteos

Create Sorteo

Build docs developers (and LLMs) love

Authentication

Tickets

Sorteos (Draws)

Loterias

Bancas & Ventanas

Users & Vendedores

Commissions

Restrictions & Rules

Multipliers

Payments

Analytics & Reports

Accounts

Activity & Audit

​POST /api/v1/loterias/:id/seed_sorteos

​Authentication

​Path Parameters

​Query Parameters

​Request Body

​Response

​Example Request (From Schedule)

​Example Request (Specific Dates)

​Example Request (Dry Run)

​Example Response (Success)

​Example Response (Dry Run)

​Error Responses

​Seeding Modes

​Auto-Create Flag

​Idempotency

​Dry Run Mode

​Inherited Configuration

​Common Use Cases

​Best Practices

​Related Endpoints

Preview Schedule

Get Loteria

List Sorteos

Create Sorteo

Build docs developers (and LLMs) love

POST /api/v1/loterias/:id/seed_sorteos

Authentication

Path Parameters

Query Parameters

Request Body

Response

Example Request (From Schedule)

Example Request (Specific Dates)

Example Request (Dry Run)

Example Response (Success)

Example Response (Dry Run)

Error Responses

Seeding Modes

Auto-Create Flag

Idempotency

Dry Run Mode

Inherited Configuration

Common Use Cases

Best Practices

Related Endpoints