List Tickets

Retrieves a paginated list of tickets with filtering capabilities. Results are filtered based on user role and RBAC permissions.

Authentication

Requires authentication. Available to roles: VENDEDOR, VENTANA, ADMIN.

Query Parameters

page

number

default:"1"

Page number for pagination.

pageSize

number

default:"10"

Number of tickets per page.

scope

string

default:"mine"

Filter scope based on user role:

mine: User’s own tickets (VENDEDOR: their tickets, VENTANA: their ventana’s tickets)
all: All tickets (ADMIN only)

date

string

default:"today"

Date filter preset. Options:

today: Today’s tickets (Costa Rica timezone)
yesterday: Yesterday’s tickets
thisWeek: Current week
thisMonth: Current month
lastWeek: Previous week
lastMonth: Previous month

Ignored if fromDate or toDate are provided.

fromDate

string

Start date for custom range (ISO 8601 format). When provided, overrides date parameter.

toDate

string

End date for custom range (ISO 8601 format). When provided, overrides date parameter.

number

string

Filter by ticket number (e.g., “T260303-00042A-15”).

winningNumber

string

Filter by lottery winning number (shows tickets with jugadas matching this number).

scheduledTime

string

Filter by sorteo scheduled time.

isActive

boolean

Filter by active status.

true: Only active tickets
false: Only inactive tickets

winnersOnly

boolean

Filter to show only winning tickets.

true: Only tickets with isWinner=true
false: Only non-winning tickets

loteriaId

string

Filter by lottery UUID.

sorteoId

string

Filter by sorteo UUID. When provided without explicit date range, date filters are skipped.

ventanaId

string

Filter by ventana UUID. Subject to RBAC validation:

VENDEDOR: Cannot specify (always filtered to their ventana)
VENTANA: Cannot specify other ventanas
ADMIN: Can specify any ventana

vendedorId

string

Filter by vendedor UUID (maps to userId internally). Subject to RBAC validation:

VENDEDOR: Cannot specify (always filtered to themselves)
VENTANA: Can only specify vendedores in their ventana
ADMIN: Can specify any vendedor

multiplierId

string

Filter by multiplier UUID (shows tickets with jugadas using this multiplier).

status

string

Filter by ticket status. Options:

ACTIVE: Active tickets
CANCELLED: Cancelled tickets
EVALUATED: Evaluated tickets (sorteo completed)
PAID: Paid winning tickets
EXCLUDED: Excluded from reports

Response Fields

data

array

Array of ticket objects.

Show Ticket Object

string

Ticket UUID.

ticketNumber

string

Unique ticket number (e.g., “T260303-00042A-15”).

totalAmount

number

Total bet amount.

status

string

Ticket status: ACTIVE, CANCELLED, EVALUATED, PAID, EXCLUDED.

isActive

boolean

Whether the ticket is active.

isWinner

boolean

Whether the ticket has winning jugadas.

loteriaId

string

Lottery UUID.

sorteoId

string

Sorteo UUID.

ventanaId

string

Ventana UUID.

vendedorId

string

Vendedor UUID.

clienteNombre

string

Customer name.

createdAt

string

ISO 8601 creation timestamp.

businessDate

string

Business date (Costa Rica timezone).

totalCommission

number

Total commission amount.

totalPayout

number

Total payout for winning tickets. Null for non-winners.

totalPaid

number

Total amount paid out so far (for winners).

remainingAmount

number

Remaining payout amount (for partially paid winners).

jugadas

array

Array of jugadas (see Create Ticket endpoint for jugada structure).

loteria

object

Lottery details (id, name, etc.).

sorteo

object

Sorteo details (id, name, scheduledAt, status, winningNumber, etc.).

vendedor

object

Vendedor details (id, name, etc.).

ventana

object

Ventana details (id, name, etc.).

RBAC Filtering

The endpoint automatically applies role-based filters:

VENDEDOR

Automatically filters to tickets where vendedorId = user.id
Cannot see tickets from other vendedores
scope is always mine

VENTANA

Automatically filters to tickets where ventanaId = user.ventanaId
Can see all vendedores in their ventana
scope is always mine
If ventanaId is not in JWT, it’s fetched from database

ADMIN

Can use scope=all to see all tickets
Can use scope=mine to see tickets from their assigned ventana
Can filter by any ventanaId or vendedorId

Date Range Resolution

Special Rule: sorteoId with No Explicit Dates

When sorteoId is provided without fromDate or toDate, date filters are skipped to show all tickets for that sorteo regardless of when they were created.

Normal Date Resolution

When no sorteoId is provided, or when explicit dates are given:

Explicit Range: fromDate and toDate take precedence
Date Preset: Uses date parameter (e.g., “today”, “thisWeek”)
Default: “today” if nothing is specified

All date ranges use Costa Rica timezone (America/Costa_Rica) for business date calculations.

Example Requests

Get Today’s Tickets (VENDEDOR)

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

Get Tickets for Specific Sorteo (ADMIN)

curl -X GET "https://api.example.com/api/v1/tickets?sorteoId=223e4567-e89b-12d3-a456-426614174000&scope=all" \
  -H "Authorization: Bearer YOUR_TOKEN"

Get Winners Only with Custom Date Range

curl -X GET "https://api.example.com/api/v1/tickets?winnersOnly=true&fromDate=2026-03-01&toDate=2026-03-31" \
  -H "Authorization: Bearer YOUR_TOKEN"

Get Tickets by Number

curl -X GET "https://api.example.com/api/v1/tickets?number=T260303-00042A-15" \
  -H "Authorization: Bearer YOUR_TOKEN"

Example Response

{
  "success": true,
  "data": [
    {
      "id": "623e4567-e89b-12d3-a456-426614174000",
      "ticketNumber": "T260303-00042A-15",
      "totalAmount": 1700,
      "status": "ACTIVE",
      "isActive": true,
      "isWinner": false,
      "loteriaId": "123e4567-e89b-12d3-a456-426614174000",
      "sorteoId": "223e4567-e89b-12d3-a456-426614174000",
      "ventanaId": "323e4567-e89b-12d3-a456-426614174000",
      "vendedorId": "423e4567-e89b-12d3-a456-426614174000",
      "clienteNombre": "Juan Pérez",
      "createdAt": "2026-03-03T14:30:00.000Z",
      "businessDate": "2026-03-03",
      "totalCommission": 93.5,
      "totalPayout": null,
      "totalPaid": 0,
      "remainingAmount": 0,
      "jugadas": [
        {
          "id": "723e4567-e89b-12d3-a456-426614174000",
          "number": "05",
          "amount": 1000,
          "type": "NUMERO",
          "finalMultiplierX": 75,
          "commissionPercent": 5.5,
          "commissionAmount": 55
        }
      ],
      "loteria": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "TICA"
      },
      "sorteo": {
        "id": "223e4567-e89b-12d3-a456-426614174000",
        "name": "TICA 7:00 PM",
        "scheduledAt": "2026-03-03T19:00:00.000Z",
        "status": "SCHEDULED"
      },
      "vendedor": {
        "id": "423e4567-e89b-12d3-a456-426614174000",
        "name": "Vendedor #1"
      },
      "ventana": {
        "id": "323e4567-e89b-12d3-a456-426614174000",
        "name": "Ventana Central"
      }
    }
  ],
  "meta": {
    "total": 42,
    "page": 1,
    "pageSize": 10,
    "totalPages": 5
  }
}

Error Responses

403 Forbidden

{
  "success": false,
  "error": "FORBIDDEN",
  "message": "Solo los administradores pueden usar scope='all'"
}

Notes

Results are automatically filtered based on user role and permissions
The vendedorId query parameter is mapped to userId internally for repository compatibility
Date filters use Costa Rica timezone for business date calculations
When filtering by sorteoId without explicit dates, all tickets for that sorteo are returned regardless of creation date
Activity logs track all list queries for audit purposes

Authentication

Tickets

Sorteos (Draws)

Loterias

Bancas & Ventanas

Users & Vendedores

Commissions

Restrictions & Rules

Multipliers

Payments

Analytics & Reports

Accounts

Activity & Audit

Authentication

Query Parameters

Response Fields

RBAC Filtering

VENDEDOR

VENTANA

ADMIN

Date Range Resolution

Special Rule: sorteoId with No Explicit Dates

Normal Date Resolution

Example Requests

Get Today’s Tickets (VENDEDOR)

Get Tickets for Specific Sorteo (ADMIN)

Get Winners Only with Custom Date Range

Get Tickets by Number

Example Response

Error Responses

403 Forbidden

Notes

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

​Authentication

​Query Parameters

​Response Fields

​RBAC Filtering

​VENDEDOR

​VENTANA

​ADMIN

​Date Range Resolution

​Special Rule: sorteoId with No Explicit Dates

​Normal Date Resolution

​Example Requests

​Get Today’s Tickets (VENDEDOR)

​Get Tickets for Specific Sorteo (ADMIN)

​Get Winners Only with Custom Date Range

​Get Tickets by Number

​Example Response

​Error Responses

​403 Forbidden

​Notes

Build docs developers (and LLMs) love

Authentication

Query Parameters

Response Fields

RBAC Filtering

VENDEDOR

VENTANA

ADMIN

Date Range Resolution

Special Rule: sorteoId with No Explicit Dates

Normal Date Resolution

Example Requests

Get Today’s Tickets (VENDEDOR)

Get Tickets for Specific Sorteo (ADMIN)

Get Winners Only with Custom Date Range

Get Tickets by Number

Example Response

Error Responses

403 Forbidden

Notes