Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/danielsl4/TFG_DAM_2526/llms.txt

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

These endpoints control the full lifecycle of a match — from creation through live event recording to finalisation. They are protected by role-based middleware and, for referee operations, require an active edit lock on the match. The table below lists all endpoints at a glance. Detailed descriptions follow in the sections beneath.
MethodPathRole requiredLock required
POST/matchesadmin—
DELETE/matches/:idadmin—
PUT/matches/:id/teamsadmin—
POST/matches/:id/lockreferee—
POST/matches/:id/unlockreferee—
PUT/matches/:id/statusrefereeyes
PUT/matches/:id/observationsrefereeyes
POST/matches/:id/eventsrefereeyes
DELETE/matches/:matchId/events/:eventIdrefereeyes
PUT/matches/:id/finishrefereeyes
POST/matches/:id/voteuser—
All endpoints in this page require a valid JWT in the Authorization: Bearer <token> header.

​
Admin endpoints

Creates a new match record. On success, invalidates all season and active-season caches. The new match starts with status "pendiente".Auth: admin

​
Body parameters

​
date
string
required
Match date and time (ISO 8601).
​
fieldId
number
required
ID of the venue field.
​
seasonId
number
required
ID of the season this match belongs to.
​
homeTeamId
number
ID of the home team. Omit for bracket matches where the team is not yet known.
​
awayTeamId
number
ID of the away team. Omit when not yet known.
​
groupId
number
Group identifier. Required for group-stage matches.
​
phase
string
Competition phase. Defaults to "fase_de_grupos".
​
homePlaceholder
string
Label for an unresolved home team slot (e.g. "Winner Group A").
​
awayPlaceholder
string
Label for an unresolved away team slot.
Response 201: { "message": "Partido creado correctamente", "id": <number> }
curl --request POST \
  --url https://api.futsalmanager.example/matches \
  --header 'Authorization: Bearer <admin-token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "date": "2026-06-01T18:00:00",
    "homeTeamId": 4,
    "awayTeamId": 7,
    "fieldId": 2,
    "groupId": 1,
    "seasonId": 3,
    "phase": "fase_de_grupos"
  }'
Permanently deletes a match and cascades the deletion to all associated events and votes. The season cache is invalidated on success.Auth: adminPath param: id (number, required) — match to delete.Response 200: { "message": "Partido eliminado correctamente" }
Response 404: Match not found.
curl --request DELETE \
  --url https://api.futsalmanager.example/matches/17 \
  --header 'Authorization: Bearer <admin-token>'
Assigns or replaces the home and away teams for a match. Useful for populating bracket slots once qualifying results are known. All four fields are optional; pass null to clear a slot.Auth: adminPath param: id (number, required)

​
Body parameters

​
homeTeamId
number
New home team ID, or omit/null to clear.
​
awayTeamId
number
New away team ID, or omit/null to clear.
​
homePlaceholder
string
Placeholder text for the home slot.
​
awayPlaceholder
string
Placeholder text for the away slot.
Response 200: { "message": "Equipos actualizados correctamente", "success": true }
Response 404: Match not found.
curl --request PUT \
  --url https://api.futsalmanager.example/matches/17/teams \
  --header 'Authorization: Bearer <admin-token>' \
  --header 'Content-Type: application/json' \
  --data '{ "homeTeamId": 5, "awayTeamId": 9 }'

​
Referee endpoints

Referee operations require both the referee (or admin) role and, where indicated, an active edit lock acquired via POST /matches/:id/lock.
Attempts to acquire an exclusive edit lock on the match. A lock is granted when no other user currently holds it, or when the existing lock is older than 2 minutes (automatic expiry). Referees should call this endpoint periodically to renew their lock during extended editing sessions.Auth: refereePath param: id (number, required)Response 200: { "message": "Bloqueo obtenido/renovado", "success": true }
Response 409: Another user holds the lock. Response includes owner (username).
curl --request POST \
  --url https://api.futsalmanager.example/matches/17/lock \
  --header 'Authorization: Bearer <referee-token>'
Releases the edit lock. A referee can only release their own lock unless they hold the admin role or pass ?force=true.Auth: refereePath param: id (number, required)
Query param: force (boolean) — admin-only override to release any lock.Response 200: { "message": "Partido desbloqueado correctamente" }
Response 403: Caller does not own the lock and force is not set.
curl --request POST \
  --url https://api.futsalmanager.example/matches/17/unlock \
  --header 'Authorization: Bearer <referee-token>'
Updates the match status. Invalidates the match cache and updates the global last-activity timestamp used for polling clients.Auth: referee + lockPath param: id (number, required)

​
Body parameters

​
status
string
required
New status. Must be one of "pendiente", "en_curso", or "finalizado".
Response 200: { "message": "Estado actualizado a <status>" }
Response 400: Invalid status value.
curl --request PUT \
  --url https://api.futsalmanager.example/matches/17/status \
  --header 'Authorization: Bearer <referee-token>' \
  --header 'Content-Type: application/json' \
  --data '{ "status": "en_curso" }'
Saves free-text observations for the match (e.g. weather, incidents). Pass null or an empty string to clear.Auth: referee + lockPath param: id (number, required)

​
Body parameters

​
observations
string
Free-text notes. Pass null to clear existing observations.
Response 200: { "message": "Observaciones actualizadas correctamente" }
curl --request PUT \
  --url https://api.futsalmanager.example/matches/17/observations \
  --header 'Authorization: Bearer <referee-token>' \
  --header 'Content-Type: application/json' \
  --data '{ "observations": "Field was wet due to rain. No injuries." }'
Records a match event and atomically updates the relevant score and player/team statistics in a single database transaction. Goal and yellow/red card events update player season stats. Rolled back automatically on any error.Auth: referee + lockPath param: id (number, required)

​
Body parameters

​
type
string
required
Event type. One of: "gol", "tarjeta_amarilla", "tarjeta_roja", "penalti_tanda_marcado", "penalti_tanda_fallado".
​
playerId
number
required
ID of the player involved in the event.
​
teamSide
string
required
Which side the player is on: "home" or "away". Used to update the correct score column.
Response 200: { "message": "Evento registrado correctamente" }
Response 400: Invalid type, missing playerId, or missing teamSide.
curl --request POST \
  --url https://api.futsalmanager.example/matches/17/events \
  --header 'Authorization: Bearer <referee-token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "gol",
    "playerId": 9,
    "teamSide": "home"
  }'
Deletes an event and reverses all associated stat changes — scores, player stats, and team stats are decremented accordingly. Uses a database transaction; rolled back on error. Scores are floored at 0.Auth: referee + lockPath params:
​
matchId
number
required
Match the event belongs to.
​
eventId
number
required
Event to remove.
Response 200: { "message": "Evento eliminado correctamente" }
Response 500: Event not found or transaction failure.
curl --request DELETE \
  --url https://api.futsalmanager.example/matches/17/events/101 \
  --header 'Authorization: Bearer <referee-token>'
Sets the match status to "finalizado", calculates and persists team standings (points, wins, draws, losses, goals), increments matches_played for participating players, evaluates prediction votes, and awards points to users who predicted the correct result. The edit lock is released as part of this operation.Auth: referee + lockPath param: id (number, required)

​
Body parameters

​
observations
string
Optional final notes to store with the match result.
Response 200: { "message": "Partido finalizado, clasificación y porra actualizadas" }
Response 500: Match already finalised, or transaction error.
curl --request PUT \
  --url https://api.futsalmanager.example/matches/17/finish \
  --header 'Authorization: Bearer <referee-token>' \
  --header 'Content-Type: application/json' \
  --data '{ "observations": "Excellent match, no incidents." }'

​
User endpoints

Submits or updates the authenticated user’s prediction for a match outcome. Votes can only be cast on matches with status "pendiente" where both teams are assigned. Calling this endpoint again with a different value replaces the previous vote (upsert).Auth: user (any authenticated role)Path param: id (number, required)

​
Body parameters

​
vote
string
required
Predicted outcome. Must be one of "local" (home win), "empate" (draw), or "visitante" (away win).
Response 200:
​
message
string
Confirmation string.
​
votingStats
object
Updated aggregate vote counts.
Response 400: Invalid vote value, match already started/finished, or teams not yet assigned.
Response 404: Match not found.
curl --request POST \
  --url https://api.futsalmanager.example/matches/17/vote \
  --header 'Authorization: Bearer <user-token>' \
  --header 'Content-Type: application/json' \
  --data '{ "vote": "local" }'

Build docs developers (and LLMs) love

Get started for freeTalk to us