Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Danielsl4/TFG_DAM_2526_Consulta2/llms.txt

Use this file to discover all available pages before exploring further.

Events track everything that happens inside a match: goals, yellow cards, red cards, and penalty-shootout kicks. Every write operation updates the match scoreline, individual player statistics, and team card tallies atomically within a database transaction. All write endpoints require both a valid JWT and an active match lock held by the calling user.
All write operations (POST, DELETE, PUT) require both authentication (referee or admin role) and a valid match lock. Acquire a lock with POST /matches/:id/lock before making any changes.

​
Add an event

POST /matches/:id/events
Inserts a new event and applies all side-effects in a single atomic transaction:
  • gol — increments home_goals or away_goals on the match, and adds 1 goal to player_stats.
  • tarjeta_amarilla / tarjeta_roja — adds 1 to the appropriate card column in player_stats and team_stats.
  • penalti_tanda_marcado — increments home_penalty_goals or away_penalty_goals. Does not affect player_stats.
  • penalti_tanda_fallado — recorded for audit purposes only; no counters are incremented.

​
Body parameters

​
type
string
required
Event type. Must be one of:
ValueDescription
golRegular goal
tarjeta_amarillaYellow card
tarjeta_rojaRed card
penalti_tanda_marcadoPenalty shootout — scored
penalti_tanda_falladoPenalty shootout — missed
​
playerId
integer
required
ID of the player involved in the event.
​
teamSide
string
required
Which side the player belongs to: home or away.

​
Response

{ "message": "Evento registrado correctamente" }
Returns 400 when type, playerId, or teamSide are missing or invalid. Returns 409 when the match lock is held by a different referee.

​
Remove an event

DELETE /matches/:matchId/events/:eventId
Deletes a previously recorded event and reverses all associated stat changes in a single transaction. The correction mirrors the original insertion logic:
  • Goal removed — decrements the corresponding goal counter (floor 0).
  • Penalty shootout goal removed — decrements the corresponding penalty counter (floor 0).
  • Card removed — decrements the card counter in player_stats and, where applicable, team_stats (floor 0 in both).

​
Path parameters

​
matchId
integer
required
Match ID.
​
eventId
integer
required
ID of the event to delete.

​
Response

{ "message": "Evento eliminado correctamente" }
Returns 500 with { message: "Evento no encontrado" } if the event does not exist in the specified match.

​
Update match status

PUT /matches/:id/status
Sets the match status. Triggers a global last-activity timestamp update and invalidates match cache entries.

​
Body parameters

​
status
string
required
New status. Must be one of: pendiente, en_curso, finalizado.

​
Response

{ "message": "Estado actualizado a en_curso" }
Returns 400 for any value outside the allowed set.

​
Update observations

PUT /matches/:id/observations
Sets or clears the referee’s free-text notes for the match.

​
Body parameters

​
observations
string
Referee notes. Pass null or omit to clear existing notes.

​
Response

{ "message": "Observaciones actualizadas correctamente" }

​
Finalize a match

PUT /matches/:id/finish
Finalizes the match in a single atomic transaction. This endpoint:
  1. Sets status = 'finalizado' and clears the match lock.
  2. Increments matches_played in player_stats for every player who appeared in an event.
  3. Calculates standings (wins, draws, losses, goals for/against, points) and upserts team_stats.
  4. Determines the correct vote outcome (local, empate, or visitante) and awards 1 prediction point to every user who voted correctly.
Finalizing a match is irreversible. The PUT /matches/:id/finish endpoint cannot be undone through the API.

​
Body parameters

​
observations
string
Optional referee notes to save alongside the finalization.

​
Response

{ "message": "Partido finalizado, clasificación y porra actualizadas" }
Returns 500 with { message: "El partido ya está finalizado" } if called on an already-finished match.

​
Lock a match

POST /matches/:id/lock
Acquires or renews a 2-minute exclusive lock on the match for the calling referee. Only one referee may hold the lock at a time. The lock expires automatically after 2 minutes of inactivity; any write operation through verifyMatchLock will clean up an expired lock proactively.

​
Response

{ "message": "Bloqueo obtenido/renovado", "success": true }
Returns 409 when the match is actively locked by a different referee: 
{
  "message": "El partido está siendo editado por maria_arbitro",
  "success": false,
  "owner": "maria_arbitro"
}

​
Unlock a match

POST /matches/:id/unlock
Releases the lock on a match. A referee can only release a lock they own. Admins can release any lock regardless of ownership.

​
Query parameters

​
force
boolean
Set to true to force-release a lock regardless of ownership. Only effective for users with the admin role.

​
Response

{ "message": "Partido desbloqueado correctamente" }
Returns 403 when the calling user does not own the lock and force is not true.

Build docs developers (and LLMs) love

Get started for freeTalk to us