Skip to main content

​
GET /api/v1/sorteos

Retrieves a list of sorteos (lottery draws) with support for pagination, filtering, and grouping.
For VENDEDOR role, results are automatically filtered based on their commission policy. Only sorteos with applicable commission rules are shown.

​
Authentication

Requires authentication. Available to all roles with different access levels:
  • ADMIN: See all sorteos
  • VENTANA: See all sorteos
  • VENDEDOR: See only sorteos matching their commission policy

​
Query Parameters

​
page
integer
default:"1"
Page number for pagination (min: 1)
​
pageSize
integer
default:"10"
Number of items per page (min: 1, max: 100)
​
loteriaId
string
Filter by loteria UUID. Returns only sorteos for the specified loteria.
​
status
string
Filter by sorteo status.Values: SCHEDULED, OPEN, EVALUATED, CLOSED
​
isActive
boolean
Filter by active status.
  • true: Show only active sorteos
  • false: Show only inactive sorteos
  • Omit: Show all sorteos
​
search
string
Search by sorteo name or winning number (min: 1, max: 100 characters)
​
date
string
Preset date range filter.Values: today, yesterday, week, month, year, rangeWhen using range, also provide fromDate and toDate.
​
fromDate
string
Start date for custom range filter (format: YYYY-MM-DD)Example: 2025-03-01
​
toDate
string
End date for custom range filter (format: YYYY-MM-DD)Example: 2025-03-31
​
groupBy
string
Group sorteos by specific criteria.Values:
  • hour: Group by scheduled hour only
  • loteria-hour: Group by loteria + scheduled hour
When grouping is active, pagination is disabled.

​
Response

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

​
Example Request

curl "https://api.example.com/api/v1/sorteos?page=1&pageSize=20&status=OPEN&date=today" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Example Response (Paginated)

{
  "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": "OPEN",
      "digits": 2,
      "isActive": true,
      "reventadoEnabled": true,
      "winningNumber": null,
      "hasWinner": false,
      "loteria": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Lotto"
      }
    }
  ],
  "meta": {
    "total": 45,
    "page": 1,
    "pageSize": 20,
    "totalPages": 3,
    "hasNextPage": true,
    "hasPrevPage": false,
    "grouped": false,
    "groupBy": null
  }
}

​
Example Response (Grouped by Hour)

curl "https://api.example.com/api/v1/sorteos?groupBy=hour&date=today" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "success": true,
  "data": [
    {
      "hour": "12:55 PM",
      "hour24": "12:55",
      "sorteoIds": [
        "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "8d9e6679-7425-40de-944b-e07fc1f90ae8"
      ],
      "count": 2,
      "mostRecentSorteoId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "mostRecentDate": "2025-03-03"
    },
    {
      "hour": "6:55 PM",
      "hour24": "18:55",
      "sorteoIds": [
        "9e9e6679-7425-40de-944b-e07fc1f90ae9"
      ],
      "count": 1,
      "mostRecentSorteoId": "9e9e6679-7425-40de-944b-e07fc1f90ae9",
      "mostRecentDate": "2025-03-03"
    }
  ],
  "meta": {
    "total": 2,
    "grouped": true,
    "groupBy": "hour",
    "fromDate": "2025-03-03",
    "toDate": "2025-03-03"
  }
}

​
Example Response (Grouped by Loteria + Hour)

curl "https://api.example.com/api/v1/sorteos?groupBy=loteria-hour&date=week" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "success": true,
  "data": [
    {
      "loteriaId": "550e8400-e29b-41d4-a716-446655440000",
      "loteriaName": "Lotto",
      "hour": "12:55 PM",
      "hour24": "12:55",
      "sorteoIds": [
        "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "8d9e6679-7425-40de-944b-e07fc1f90ae8"
      ],
      "count": 7,
      "mostRecentSorteoId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "mostRecentDate": "2025-03-03"
    }
  ],
  "meta": {
    "total": 1,
    "grouped": true,
    "groupBy": "loteria-hour",
    "fromDate": "2025-02-24",
    "toDate": "2025-03-03"
  }
}

​
Commission Policy Filtering (VENDEDOR)

For VENDEDOR users, sorteos are automatically filtered based on their commission policy. Only sorteos with at least one active multiplier that has a specific commission rule are shown.
The filtering logic:
  1. Retrieves the vendedor’s commission policy
  2. Gets all active multipliers for each sorteo’s loteria
  3. Checks if any multiplier has a specific commission rule (not just defaultPercent)
  4. Only shows sorteos where at least one multiplier matches a commission rule
This ensures vendedores only see sorteos they can earn commission on.

​
Date Range Presets

curl "https://api.example.com/api/v1/sorteos?date=today"

​
Grouping Modes

​
Group by Hour

Groups sorteos by their scheduled hour, useful for displaying all loterias at the same time: 
curl "https://api.example.com/api/v1/sorteos?groupBy=hour&date=today"

​
Group by Loteria + Hour

Groups sorteos by both loteria and hour, useful for showing recurring schedules: 
curl "https://api.example.com/api/v1/sorteos?groupBy=loteria-hour&loteriaId=550e8400-e29b-41d4-a716-446655440000"

Get Sorteo

Get a single sorteo by ID

Create Sorteo

Create a new sorteo

Filter by Loteria

Get loteria details

Commission Policy

Understand commission filtering

Build docs developers (and LLMs) love

Get started for freeTalk to us