Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/fredy-rizo/gestor-backend/llms.txt

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

Games represent individual matches within a tournament event. Each game tracks two teams, the full record of in-match events (goals, yellow/red/blue cards, fouls, substitutions), and the final result. Once all events for a match are recorded, the organizer finalizes the standings table so rankings and statistics update across the tournament.

​
Match Lifecycle

Every match moves through a standard sequence before it contributes to tournament standings:
  1. Create — organizer calls POST /api/game/new-matches/:eventId/game (or the group-stage variant) to schedule the fixture.
  2. Record events — goals, cards, fouls, and substitutions are recorded as they happen.
  3. Finalize — organizer calls the finalize endpoint to calculate and persist standings.

​
Card Types

Three card types are supported for disciplinary tracking:
CardFieldEffect
YellowyellowCardCaution — player receives a warning
RedredCardEjection — player is removed from the match
BlueblueCardTemporary suspension — player sits out for a defined period
Always call the finalize endpoint after recording all goals, cards, and disciplinary data for a match. Standings are not updated in real time — they are computed only when the finalize call is made.

​
Match Creation

​
POST /api/game/new-matches/:eventId/game

Schedules a new knockout or regular match within an event. Plan-based limits apply to the number of matches that can be created under a given subscription tier. Authentication: access-token: <jwt_token> — required
​
eventId
string
required
The _id of the parent event.
​
TeamOne
object
required
The first team. Must include the team’s _id inside a nested team object: { "team": { "_id": "..." } }.
​
TeamTwo
object
required
The second team, same shape as TeamOne.
​
matchDate
string
Date of the match (e.g., "2025-03-15").
​
matchTime
string
Kick-off time (e.g., "16:00").
​
matchDay
string
Human-readable match day label (e.g., "Jornada 1").
​
scenery
string
Stadium or venue name for this specific match.
​
workingday
string
Round or stage identifier (e.g., "Cuartos de Final").
​
refereeName
string
Name of the assigned referee.
curl -X POST https://api.example.com/api/game/new-matches/64a1f2c3e4b5d6f7a8b9c0d1/game \
  -H "access-token: <jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "TeamOne": { "team": { "_id": "64b2e3d4f5a6b7c8d9e0f1a2" } },
    "TeamTwo": { "team": { "_id": "64b2e3d4f5a6b7c8d9e0f1a3" } },
    "matchDate": "2025-03-15",
    "matchTime": "16:00",
    "matchDay": "Jornada 1",
    "scenery": "Estadio Municipal",
    "workingday": "Fase Regular",
    "refereeName": "Carlos Mendoza"
  }'
​
status
boolean
true on success.
​
game
object
The newly created game document.
{
  "status": true,
  "game": {
    "_id": "64c3f4e5a6b7c8d9e0f1a2b3",
    "matchDate": "2025-03-15",
    "matchTime": "16:00",
    "refereeName": "Carlos Mendoza",
    "stade": true
  }
}

​
POST /api/game/new/:eventId/matches-group

Creates the full group stage structure for an event. Each group is named and assigned a set of teams. The server will generate the round-robin fixture schedule within each group automatically. Authentication: access-token: <jwt_token> — required
​
eventId
string
required
The _id of the event to add groups to.
​
groups
array
required
Array of group objects to create.
curl -X POST https://api.example.com/api/game/new/64a1f2c3e4b5d6f7a8b9c0d1/matches-group \
  -H "access-token: <jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "groups": [
      {
        "groupName": "Grupo A",
        "teams": [
          "64b2e3d4f5a6b7c8d9e0f1a2",
          "64b2e3d4f5a6b7c8d9e0f1a3",
          "64b2e3d4f5a6b7c8d9e0f1a4"
        ]
      },
      {
        "groupName": "Grupo B",
        "teams": [
          "64b2e3d4f5a6b7c8d9e0f1a5",
          "64b2e3d4f5a6b7c8d9e0f1a6"
        ]
      }
    ]
  }'
​
status
boolean
true on success.
{ "status": true }

​
POST /api/game/new/:eventId/matches-game-group/:groupId

Schedules a single match inside an existing group stage. Use this after creating the group structure to add or adjust individual fixtures within a group. Authentication: access-token: <jwt_token> — required
​
eventId
string
required
The _id of the parent event.
​
groupId
string
required
The _id of the group stage this match belongs to.
​
TeamOne
object
required
First team: { "team": { "_id": "..." } }.
​
TeamTwo
object
required
Second team: { "team": { "_id": "..." } }.
​
matchDate
string
Date of the match.
​
matchTime
string
Kick-off time.
​
matchDay
string
Match day label.
​
scenery
string
Venue name.
​
workingday
string
Round or stage identifier.
​
refereeName
string
Referee’s name.
curl -X POST https://api.example.com/api/game/new/64a1f2c3e4b5d6f7a8b9c0d1/matches-game-group/64d4e5f6a7b8c9d0e1f2a3b4 \
  -H "access-token: <jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "TeamOne": { "team": { "_id": "64b2e3d4f5a6b7c8d9e0f1a2" } },
    "TeamTwo": { "team": { "_id": "64b2e3d4f5a6b7c8d9e0f1a3" } },
    "matchDate": "2025-03-20",
    "matchTime": "18:00",
    "matchDay": "Jornada 2",
    "scenery": "Cancha Norte",
    "workingday": "Fase de Grupos",
    "refereeName": "Ana Ramírez"
  }'
​
status
boolean
true on success.

​
Match Updates

​
POST /api/game/update/:gameId/matches

Updates logistical details of an existing match — date, time, venue, referee, and matchday information. All body fields are optional; only provided fields are updated. Authentication: access-token: <jwt_token> — required
​
gameId
string
required
The _id of the game to update.
​
matchDate
string
New match date.
​
matchTime
string
New kick-off time.
​
matchDay
string
Updated match day label.
​
scenery
string
Updated venue name.
​
workingday
string
Updated round or stage identifier.
​
refereeName
string
Updated referee name.
curl -X POST https://api.example.com/api/game/update/64c3f4e5a6b7c8d9e0f1a2b3/matches \
  -H "access-token: <jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "matchDate": "2025-03-22",
    "matchTime": "17:00",
    "refereeName": "Luis García"
  }'
​
status
boolean
true on success.
​
game
object
The updated game document.
{
  "status": true,
  "game": {
    "_id": "64c3f4e5a6b7c8d9e0f1a2b3",
    "matchDate": "2025-03-22",
    "matchTime": "17:00",
    "refereeName": "Luis García"
  }
}

​
Recording Match Events

​
POST /api/game/goals/:gameId/:teamId/:eventId

Records goals scored by a team in a match. Each goal entry includes timing, type, and the player who scored. Player statistics in the Player model are updated automatically. Authentication: access-token: <jwt_token> — required
​
gameId
string
required
The _id of the game.
​
teamId
string
required
The _id of the team that scored.
​
eventId
string
required
The _id of the parent event.
​
goals
array
required
Array of goal objects.
curl -X POST https://api.example.com/api/game/goals/64c3f4e5a6b7c8d9e0f1a2b3/64b2e3d4f5a6b7c8d9e0f1a2/64a1f2c3e4b5d6f7a8b9c0d1 \
  -H "access-token: <jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "goals": [
      {
        "dataType": 1,
        "timeGoals": "23'"'"'",
        "typeGoals": "Normal",
        "playerData": [
          {
            "_id": "64e5f6a7b8c9d0e1f2a3b4c5",
            "namePlayer": "Jorge Torres",
            "shirtNumber": 9,
            "position": "Delantero"
          }
        ]
      },
      {
        "dataType": 1,
        "timeGoals": "67'"'"'",
        "typeGoals": "Penal",
        "playerData": [
          {
            "_id": "64e5f6a7b8c9d0e1f2a3b4c6",
            "namePlayer": "Mario Ruiz",
            "shirtNumber": 10,
            "position": "Mediocampista"
          }
        ]
      }
    ]
  }'
​
status
boolean
true on success.
{ "status": true }

​
POST /api/game/card/:gameId/:teamId/:eventId/global

Records yellow, red, and blue cards issued to players of a team during a match. All three card arrays can be submitted in a single call. Player card statistics are updated in the Player model. Authentication: access-token: <jwt_token> — required
​
gameId
string
required
The _id of the game.
​
teamId
string
required
The _id of the team receiving the cards.
​
eventId
string
required
The _id of the parent event.
​
yellowCard
array
Caution cards. Each item: { "dataType": 1, "time": "30'", "playerData": [...] }.
​
redCard
array
Ejection cards. Same shape as yellowCard.
​
blueCard
array
Temporary suspension cards. Same shape as yellowCard.
curl -X POST https://api.example.com/api/game/card/64c3f4e5a6b7c8d9e0f1a2b3/64b2e3d4f5a6b7c8d9e0f1a2/64a1f2c3e4b5d6f7a8b9c0d1/global \
  -H "access-token: <jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "yellowCard": [
      {
        "dataType": 1,
        "time": "30'"'"'",
        "playerData": [
          { "_id": "64e5f6a7b8c9d0e1f2a3b4c7", "namePlayer": "Pedro López", "shirtNumber": 5, "position": "Defensa" }
        ]
      }
    ],
    "redCard": [],
    "blueCard": []
  }'
​
status
boolean
true on success.
{ "status": true }

​
POST /api/game/disciplinarys/:gameId/:teamId/:eventId

Records additional disciplinary data for a team in a match: total fouls committed, formal sanctions, and player substitutions. This complements the card recording endpoint with non-card disciplinary information. Authentication: access-token: <jwt_token> — required
​
gameId
string
required
The _id of the game.
​
teamId
string
required
The _id of the team.
​
eventId
string
required
The _id of the parent event.
​
totalFaults
array
Array of foul records committed by this team.
​
santions
array
Array of formal sanction records. Each item should include a typeSantions field describing the sanction type.
​
playerChanges
array
Array of substitution records. Each item includes timePlayerChange (minute), playerDataOne (player coming off), and playerDataTwo (player coming on).
curl -X POST https://api.example.com/api/game/disciplinarys/64c3f4e5a6b7c8d9e0f1a2b3/64b2e3d4f5a6b7c8d9e0f1a2/64a1f2c3e4b5d6f7a8b9c0d1 \
  -H "access-token: <jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "totalFaults": [{ "minute": "12'"'"'", "description": "Foul on attacker" }],
    "santions": [{ "typeSantions": "Amonestación", "playerData": [] }],
    "playerChanges": [
      {
        "timePlayerChange": "55'"'"'",
        "playerDataOne": { "_id": "64e5f6a7b8c9d0e1f2a3b4c7", "namePlayer": "Pedro López" },
        "playerDataTwo": { "_id": "64e5f6a7b8c9d0e1f2a3b4c8", "namePlayer": "Raúl Vega" }
      }
    ]
  }'
​
status
boolean
true on success.
{ "status": true }

​
POST /api/game/goals-group/:gameId/:teamId/:eventId/:groupStageId

Records goals for a match that belongs to a group stage. Identical in payload to the standard goals endpoint but requires the groupStageId path parameter so standings are updated within the correct group. Authentication: access-token: <jwt_token> — required
​
gameId
string
required
The _id of the game.
​
teamId
string
required
The _id of the scoring team.
​
eventId
string
required
The _id of the parent event.
​
groupStageId
string
required
The _id of the group stage this match belongs to.
​
goals
array
required
Same structure as POST /api/game/goals — array of goal objects with dataType, timeGoals, typeGoals, and playerData.
curl -X POST https://api.example.com/api/game/goals-group/64c3f4e5a6b7c8d9e0f1a2b3/64b2e3d4f5a6b7c8d9e0f1a2/64a1f2c3e4b5d6f7a8b9c0d1/64d4e5f6a7b8c9d0e1f2a3b4 \
  -H "access-token: <jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "goals": [
      {
        "dataType": 1,
        "timeGoals": "12'"'"'",
        "typeGoals": "Normal",
        "playerData": [
          { "_id": "64e5f6a7b8c9d0e1f2a3b4c5", "namePlayer": "Jorge Torres", "shirtNumber": 9, "position": "Delantero" }
        ]
      }
    ]
  }'
​
status
boolean
true on success.
{ "status": true }

​
Finalizing Standings

​
POST /api/game/table/:gameId/:eventId/finalize

Finalizes the standings table for a regular (non-group) match. Computes win/loss/draw results, updates the standings table for the event, and marks the match as complete. Call this after all goals, cards, and disciplinary data have been recorded. Authentication: access-token: <jwt_token> — required
​
gameId
string
required
The _id of the game to finalize.
​
eventId
string
required
The _id of the parent event.
curl -X POST https://api.example.com/api/game/table/64c3f4e5a6b7c8d9e0f1a2b3/64a1f2c3e4b5d6f7a8b9c0d1/finalize \
  -H "access-token: <jwt_token>"
​
status
boolean
true on success.
{ "status": true }

​
POST /api/game/table/:gameId/:eventId/:groupStageId/finalize

Same as the standard finalize endpoint but for group stage matches. Standings are updated within the specified group. Authentication: access-token: <jwt_token> — required
​
gameId
string
required
The _id of the game to finalize.
​
eventId
string
required
The _id of the parent event.
​
groupStageId
string
required
The _id of the group stage.
curl -X POST https://api.example.com/api/game/table/64c3f4e5a6b7c8d9e0f1a2b3/64a1f2c3e4b5d6f7a8b9c0d1/64d4e5f6a7b8c9d0e1f2a3b4/finalize \
  -H "access-token: <jwt_token>"
​
status
boolean
true on success.
{ "status": true }

​
POST /api/game/finality/:eventId/group-table

Marks the entire group stage phase of an event as finished. Call this once all group stage matches have been played and finalized, before advancing to knockout rounds. Authentication: access-token: <jwt_token> — required
​
eventId
string
required
The _id of the event whose group table to finalize.
curl -X POST https://api.example.com/api/game/finality/64a1f2c3e4b5d6f7a8b9c0d1/group-table \
  -H "access-token: <jwt_token>"
​
status
boolean
true on success.
{ "status": true }

​
Listing & Querying

​
POST /api/game/list/:stadeParams/:pag?/:perpage?

Returns a paginated list of games filtered by their active/finished state. Authentication: None required
​
stadeParams
string
required
"true" to list active games; "false" to list finished games.
​
pag
number
Page number (1-based).
​
perpage
number
Items per page.
curl -X POST https://api.example.com/api/game/list/true/1/20

​
POST /api/game/list/:gameId/gameId

Retrieves a single game document by its ID. Authentication: None required
​
gameId
string
required
The _id of the game to fetch.
curl -X POST https://api.example.com/api/game/list/64c3f4e5a6b7c8d9e0f1a2b3/gameId

​
POST /api/game/list/:gameId/data/:teamId/game

Returns team-specific data within a game — the team’s goals, cards, faults, and player changes for that match. Authentication: None required
​
gameId
string
required
The _id of the game.
​
teamId
string
required
The _id of the team whose data to retrieve.
curl -X POST https://api.example.com/api/game/list/64c3f4e5a6b7c8d9e0f1a2b3/data/64b2e3d4f5a6b7c8d9e0f1a2/game

​
POST /api/game/list/:eventId/game/event

Lists all games scheduled within a specific event. Authentication: None required
​
eventId
string
required
The _id of the event.
curl -X POST https://api.example.com/api/game/list/64a1f2c3e4b5d6f7a8b9c0d1/game/event

​
POST /api/game/list/:eventId/table/game

Returns the current standings table for a regular (non-group) tournament event. Authentication: None required
​
eventId
string
required
The _id of the event.
curl -X POST https://api.example.com/api/game/list/64a1f2c3e4b5d6f7a8b9c0d1/table/game

​
POST /api/game/list/:eventId/table/game/group

Returns the group stage standings tables for an event — one table per group showing points, wins, draws, losses, and goal difference. Authentication: None required
​
eventId
string
required
The _id of the event.
curl -X POST https://api.example.com/api/game/list/64a1f2c3e4b5d6f7a8b9c0d1/table/game/group

​
POST /api/game/list/:teamId/games/teams

Lists all games a specific team has participated in across any event. Authentication: None required
​
teamId
string
required
The _id of the team.
curl -X POST https://api.example.com/api/game/list/64b2e3d4f5a6b7c8d9e0f1a2/games/teams

​
POST /api/game/list/match/:gameId/data/player

Returns individual player statistics for a match — goals, cards, and disciplinary data broken down per player. Authentication: None required
​
gameId
string
required
The _id of the game.
curl -X POST https://api.example.com/api/game/list/match/64c3f4e5a6b7c8d9e0f1a2b3/data/player

​
POST /api/game/list/working/day/game

Returns all games grouped by matchday (workingday), useful for building a fixture calendar view. Authentication: None required 
curl -X POST https://api.example.com/api/game/list/working/day/game

​
POST /api/game/list/:eventId/teams-groups

Lists all teams and their group assignments within an event’s group stage. Authentication: None required
​
eventId
string
required
The _id of the event.
curl -X POST https://api.example.com/api/game/list/64a1f2c3e4b5d6f7a8b9c0d1/teams-groups

​
POST /api/game/list/:eventId/table-gols

Returns the top scorer table for a specific event — players ranked by number of goals scored. Authentication: None required
​
eventId
string
required
The _id of the event.
curl -X POST https://api.example.com/api/game/list/64a1f2c3e4b5d6f7a8b9c0d1/table-gols

​
POST /api/game/list/table/goals

Returns all top scorer tables across every event in the system. Authentication: None required 
curl -X POST https://api.example.com/api/game/list/table/goals

​
POST /api/game/list/game/finality

Returns all games that have been finalized (completed matches with recorded results). Authentication: None required 
curl -X POST https://api.example.com/api/game/list/game/finality

Build docs developers (and LLMs) love

Get started for freeTalk to us