Referees (and admins) control the entire live match workflow: acquiring the editing lock, starting the match, recording events, and finalising the result. All write operations require an active lock on the match.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/Danielsl4/TFG_DAM_2526_Consulta/llms.txt
Use this file to discover all available pages before exploring further.
Every endpoint that modifies live match data — changing status, adding or removing events, updating observations, and finishing the match — requires you to hold the match lock. Acquire and renew the lock before performing any of these operations.
Full workflow
Acquire the lock
Send The lock expires after 2 minutes of inactivity. You must renew it by calling the same endpoint again before it lapses — otherwise another referee can claim it. Call the lock endpoint periodically while you are actively editing.
POST /matches/:id/lock to claim exclusive editing rights on the match. If the lock is free (or has expired), you acquire it immediately. If another referee holds the lock, the API returns 409 with the current owner’s username.Start the match
Change the match status to Changing the status invalidates the match cache and updates the global last-activity timestamp, which triggers connected clients to refresh.
en_curso using PUT /matches/:id/status. Valid statuses are pendiente, en_curso, and finalizado.Record match events
Add events during the match with Required fields:
Event types:
POST /matches/:id/events. You must hold the lock to use this endpoint.| Field | Type | Description |
|---|---|---|
type | string | Event type (see table below) |
playerId | integer | ID of the player involved |
teamSide | string | "home" or "away" |
| Type | Effect |
|---|---|
gol | Increments home_goals or away_goals; updates player and team stats |
tarjeta_amarilla | Records a yellow card; updates player and team stats |
tarjeta_roja | Records a red card; updates player and team stats |
penalti_tanda_marcado | Increments home_penalty_goals or away_penalty_goals only — not counted in regular goals or player stats |
penalti_tanda_fallado | Records a missed penalty shootout attempt — no score or stat update |
Penalty shootout events (
penalti_tanda_marcado and penalti_tanda_fallado) are tracked separately in home_penalty_goals / away_penalty_goals and do not affect player statistics or the regular scoreline.Correct mistakes by removing events
If you record an event in error, remove it with
DELETE /matches/:matchId/events/:eventId. You must hold the lock. Removing an event reverses its effect on the scoreline and on player and team statistics.Add referee observations (optional)
Record any referee notes using Send
PUT /matches/:id/observations. You must hold the lock. Observations are stored as free text and appear on the match detail page and in the season report.null or an empty string to clear existing observations.Finish the match
Finalise the match with Points allocation: win = 3 points, draw = 1 point each, loss = 0 points. The porra winner determination compares
PUT /matches/:id/finish. You must hold the lock. This endpoint:- Sets
statustofinalizado - Saves any final observations you pass in the body
- Calculates and updates league standings (
team_stats) based on the scoreline - Increments
matches_playedfor all players who participated - Awards porra (voting) points to users who correctly predicted the result
- Releases the lock automatically
home_goals vs away_goals — penalty shootout goals are not used to determine the result for porra or standings purposes.Release the lock
After finishing, the lock is released automatically. If you need to release it manually at any point (e.g. you are done editing before finishing), call Only the lock owner or an admin can unlock. Admins can also pass
POST /matches/:id/unlock.?force=true to override the lock regardless of ownership.Lock conflict handling
If you attempt to acquire a lock that another referee holds, the API responds with409: