Skip to main content

​
PATCH /api/v1/sorteos/:id/close

Transitions a sorteo to CLOSED status, marking it as finalized. This operation also cascades to all associated tickets.
Closing a sorteo is irreversible. Once closed, the sorteo cannot be reopened and no further operations are allowed.

​
Authentication

Requires ADMIN role.

​
Path Parameters

​
id
string
required
UUID of the sorteo to close

​
Request Body

No request body required.

​
Response

​
success
boolean
Indicates if the operation was successful
​
data
object
The updated sorteo object with status: "CLOSED"

​
Example Request

curl -X PATCH https://api.example.com/api/v1/sorteos/7c9e6679-7425-40de-944b-e07fc1f90ae7/close \
  -H "Authorization: Bearer YOUR_TOKEN"

​
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": "CLOSED",
    "digits": 2,
    "isActive": true,
    "reventadoEnabled": true,
    "winningNumber": "42",
    "hasWinner": true,
    "createdAt": "2025-03-03T10:00:00-06:00",
    "updatedAt": "2025-03-03T14:00:00-06:00"
  }
}

​
Error Responses

{
  "success": false,
  "error": "Solo se puede cerrar desde OPEN o EVALUATED"
}

​
Allowed States for Closing

A sorteo can only be closed from:

OPEN

Close without evaluation (no winning number set).Use case: Cancelled or void draws

EVALUATED

Close after evaluation (winning number set, winners identified).Use case: Normal draw completion

​
Cascade Effect

Closing a sorteo automatically closes all associated tickets through a cascade operation.
The close operation:
  1. Updates sorteo status to CLOSED
  2. Finds all active, non-cancelled tickets for this sorteo
  3. Marks each ticket with deletedByCascade: true
  4. Records cascade metadata (source, reason, timestamp)
  5. Invalidates sorteo cache
Example ticket cascade: 
{
  "ticketId": "ticket-uuid",
  "status": "EVALUATED",
  "deletedByCascade": true,
  "deletedByCascadeFrom": "sorteo",
  "deletedByCascadeId": "sorteo-uuid"
}

​
What Happens When Closing?

Sorteo status changes to CLOSED (terminal state).
All associated tickets are marked as closed with cascade flags.Query result:
UPDATE "Ticket"
SET "deletedByCascade" = true,
    "deletedByCascadeFrom" = 'sorteo',
    "deletedByCascadeId" = 'sorteo-uuid'
WHERE "sorteoId" = 'sorteo-uuid'
  AND "status" != 'CANCELLED'
  AND "isActive" = true
  AND "deletedAt" IS NULL;
Sorteo cache is cleared to ensure all clients see the updated status.
Activity log entry includes cascade count:
{
  "action": "SORTEO_CLOSE",
  "details": {
    "from": "EVALUATED",
    "to": "CLOSED",
    "ticketsClosed": 147,
    "description": "Sorteo Lotto 12:55 PM CERRADO (147 tickets afectados)"
  }
}

​
Close vs Cancel

Normal completion of a sorteo lifecycle.
  • Sorteo may or may not have winning number
  • All tickets are preserved (just marked as cascade-closed)
  • Used for normal end-of-life
  • Irreversible

​
Automated Closing

Sorteos can be closed automatically using the auto-close cron job for sorteos with no sales. See Sorteo Automation for details.
Configuration: 
{
  "autoCloseEnabled": true,
  "closeCronSchedule": "*/10 * * * *"
}
Auto-close criteria:
  • Status is OPEN
  • No tickets sold
  • Scheduled time has passed

​
Typical Workflow

1

Sorteo Opens

Sorteo transitions from SCHEDULED to OPEN.
2

Tickets Sold

Vendedores create tickets throughout the sales period.
3

Sales Cutoff

Sales automatically stop based on cutoff time.
4

Draw Occurs

Physical lottery draw happens (external to system).
5

Evaluation

Admin evaluates sorteo with winning number via Evaluate.
6

Winners Pay Out

Winning tickets are paid via Payment API.
7

Close Sorteo

Admin closes sorteo to finalize and archive.

​
When to Close

Best Practice: Close after all winning tickets have been paid out.This ensures:
  • Complete payment records
  • Accurate financial reporting
  • No pending operations
Sorteos with zero tickets can be auto-closed to clean up.Prevents:
  • Clutter in sorteo lists
  • Confusion about active draws
If a draw is cancelled or void, close without evaluation.All tickets remain in their current state (no winners marked).

​
State Diagram

Open Sorteo

Open a sorteo for sales

Evaluate Sorteo

Set winning number before closing

Ticket Payments

Pay winning tickets

Activity Logs

View close operation audit

Build docs developers (and LLMs) love

Get started for freeTalk to us