{
  "openapi": "3.0.3",
  "info": {
    "title": "SharkGame Partner Aggregator API",
    "version": "1.0.0",
    "description": "OpenAPI specification for the SharkGame partner aggregator endpoints under /api/partner/v1."
  },
  "servers": [
    {
      "url": "http://api.sharkgame.com.br/api/partner/v1",
      "description": "Default environment"
    }
  ],
  "tags": [
    { "name": "Core", "description": "Health and core partner gateway endpoints." },
    { "name": "Casino", "description": "Casino providers, games, and launch endpoints." },
    { "name": "Sports Catalog", "description": "Local sports catalog and filter endpoints." },
    { "name": "Sports Feed", "description": "Prematch and live feed endpoints." },
    { "name": "Sports Events", "description": "Provider event, odds, lineup, stats, and result endpoints." }
  ],
  "security": [
    { "bearerAuth": [] },
    { "partnerKeyHeader": [] }
  ],
  "paths": {
    "/status": {
      "get": {
        "tags": ["Core"],
        "summary": "Validate partner token",
        "operationId": "getPartnerStatus",
        "responses": {
          "200": { "$ref": "#/components/responses/GenericSuccess" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/providers": {
      "get": {
        "tags": ["Casino"],
        "summary": "List casino providers",
        "operationId": "listCasinoProviders",
        "responses": {
          "200": { "$ref": "#/components/responses/GenericSuccess" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/games": {
      "get": {
        "tags": ["Casino"],
        "summary": "List casino games",
        "operationId": "listCasinoGames",
        "parameters": [
          { "$ref": "#/components/parameters/ProviderIdQuery" },
          { "$ref": "#/components/parameters/SearchQuery" },
          { "$ref": "#/components/parameters/PageQuery" },
          { "$ref": "#/components/parameters/PerPageQuery" }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/GenericSuccess" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/launch": {
      "post": {
        "tags": ["Casino"],
        "summary": "Launch a casino game for a partner player",
        "operationId": "launchCasinoGame",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/LaunchRequest" },
              "examples": {
                "default": {
                  "value": {
                    "external_player_id": "player-1001",
                    "player_name": "Joao Silva",
                    "player_email": "joao@partner.com",
                    "player_balance": 250.75,
                    "game_code": "aviator",
                    "provider": "spribe",
                    "game_original": true,
                    "lang": "pt",
                    "user_rtp": 96
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "$ref": "#/components/responses/GenericSuccess" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "422": { "$ref": "#/components/responses/ValidationError" }
        }
      }
    },
    "/sports/status": {
      "get": {
        "tags": ["Sports Events"],
        "summary": "Check sports gateway status",
        "operationId": "getSportsStatus",
        "responses": {
          "200": { "$ref": "#/components/responses/GenericSuccess" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/sports/catalog/overview": {
      "get": {
        "tags": ["Sports Catalog"],
        "summary": "Get local catalog overview",
        "operationId": "getSportsCatalogOverview",
        "responses": {
          "200": { "$ref": "#/components/responses/GenericSuccess" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/sports/catalog/refresh": {
      "post": {
        "tags": ["Sports Catalog"],
        "summary": "Refresh local sports catalog",
        "operationId": "refreshSportsCatalog",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CatalogRefreshRequest" },
              "examples": {
                "default": {
                  "value": {
                    "sport_id": 1,
                    "import_leagues": true,
                    "import_events": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "$ref": "#/components/responses/GenericSuccess" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "422": { "$ref": "#/components/responses/ValidationError" }
        }
      }
    },
    "/sports/catalog/sports": {
      "get": {
        "tags": ["Sports Catalog"],
        "summary": "List sports from local catalog",
        "operationId": "listCatalogSports",
        "parameters": [
          { "$ref": "#/components/parameters/SearchQuery" },
          { "$ref": "#/components/parameters/PageQuery" },
          { "$ref": "#/components/parameters/PerPageQuery" },
          { "$ref": "#/components/parameters/ActiveQuery" }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/GenericSuccess" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/sports/catalog/countries": {
      "get": {
        "tags": ["Sports Catalog"],
        "summary": "List countries from local catalog",
        "operationId": "listCatalogCountries",
        "parameters": [
          { "$ref": "#/components/parameters/SearchQuery" },
          { "$ref": "#/components/parameters/PageQuery" },
          { "$ref": "#/components/parameters/PerPageQuery" },
          { "$ref": "#/components/parameters/ActiveQuery" },
          { "$ref": "#/components/parameters/SportIdQuery" }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/GenericSuccess" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/sports/catalog/leagues": {
      "get": {
        "tags": ["Sports Catalog"],
        "summary": "List leagues from local catalog",
        "operationId": "listCatalogLeagues",
        "parameters": [
          { "$ref": "#/components/parameters/SearchQuery" },
          { "$ref": "#/components/parameters/PageQuery" },
          { "$ref": "#/components/parameters/PerPageQuery" },
          { "$ref": "#/components/parameters/ActiveQuery" },
          { "$ref": "#/components/parameters/SportIdQuery" },
          { "$ref": "#/components/parameters/CountryQuery" },
          { "$ref": "#/components/parameters/LeagueIdQuery" }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/GenericSuccess" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/sports/catalog/teams": {
      "get": {
        "tags": ["Sports Catalog"],
        "summary": "List teams from local catalog",
        "operationId": "listCatalogTeams",
        "parameters": [
          { "$ref": "#/components/parameters/SearchQuery" },
          { "$ref": "#/components/parameters/PageQuery" },
          { "$ref": "#/components/parameters/PerPageQuery" },
          { "$ref": "#/components/parameters/ActiveQuery" },
          { "$ref": "#/components/parameters/SportIdQuery" },
          { "$ref": "#/components/parameters/CountryQuery" },
          { "$ref": "#/components/parameters/LeagueIdQuery" },
          { "$ref": "#/components/parameters/TeamIdQuery" }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/GenericSuccess" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/sports/catalog/filters": {
      "get": {
        "tags": ["Sports Catalog"],
        "summary": "Get dynamic filter options for catalog feeds",
        "operationId": "getCatalogFilters",
        "parameters": [
          {
            "name": "source",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["prematch", "live"]
            },
            "description": "Feed source used to derive filter options."
          },
          { "$ref": "#/components/parameters/SportIdQuery" },
          { "$ref": "#/components/parameters/CountryQuery" },
          { "$ref": "#/components/parameters/LeagueIdQuery" }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/GenericSuccess" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/sports/feed/prematch": {
      "get": {
        "tags": ["Sports Feed"],
        "summary": "Get prematch feed",
        "operationId": "getPrematchFeed",
        "parameters": [
          { "$ref": "#/components/parameters/PageQuery" },
          { "$ref": "#/components/parameters/PerPageQuery" },
          { "$ref": "#/components/parameters/SportIdQuery" },
          { "$ref": "#/components/parameters/CountryQuery" },
          { "$ref": "#/components/parameters/LeagueIdQuery" },
          { "$ref": "#/components/parameters/TeamIdQuery" },
          { "$ref": "#/components/parameters/SearchQuery" },
          { "$ref": "#/components/parameters/DateFromQuery" },
          { "$ref": "#/components/parameters/DateToQuery" },
          { "$ref": "#/components/parameters/SortByQuery" },
          { "$ref": "#/components/parameters/SortDirectionQuery" }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/GenericSuccess" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/sports/feed/live": {
      "get": {
        "tags": ["Sports Feed"],
        "summary": "Get live feed",
        "operationId": "getLiveFeed",
        "parameters": [
          { "$ref": "#/components/parameters/PageQuery" },
          { "$ref": "#/components/parameters/PerPageQuery" },
          { "$ref": "#/components/parameters/SportIdQuery" },
          { "$ref": "#/components/parameters/CountryQuery" },
          { "$ref": "#/components/parameters/LeagueIdQuery" },
          { "$ref": "#/components/parameters/TeamIdQuery" },
          { "$ref": "#/components/parameters/SearchQuery" },
          { "$ref": "#/components/parameters/SortByQuery" },
          { "$ref": "#/components/parameters/SortDirectionQuery" }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/GenericSuccess" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/sports/leagues": {
      "get": {
        "tags": ["Sports Events"],
        "summary": "Get leagues from provider gateway",
        "operationId": "getProviderLeagues",
        "parameters": [
          { "$ref": "#/components/parameters/SportIdQuery" },
          { "$ref": "#/components/parameters/PageQuery" }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/GenericSuccess" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "502": { "$ref": "#/components/responses/ProviderError" }
        }
      }
    },
    "/sports/events/upcoming": {
      "get": {
        "tags": ["Sports Events"],
        "summary": "Get upcoming events",
        "operationId": "getUpcomingEvents",
        "parameters": [
          { "$ref": "#/components/parameters/SportIdQuery" },
          { "$ref": "#/components/parameters/PageQuery" },
          { "$ref": "#/components/parameters/LeagueIdQuery" }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/GenericSuccess" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "502": { "$ref": "#/components/responses/ProviderError" }
        }
      }
    },
    "/sports/events/live": {
      "get": {
        "tags": ["Sports Events"],
        "summary": "Get live events",
        "operationId": "getLiveEvents",
        "parameters": [
          { "$ref": "#/components/parameters/SportIdQuery" },
          { "$ref": "#/components/parameters/PageQuery" }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/GenericSuccess" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "502": { "$ref": "#/components/responses/ProviderError" }
        }
      }
    },
    "/sports/events/live/{eventId}": {
      "get": {
        "tags": ["Sports Events"],
        "summary": "Get live event detail",
        "operationId": "getLiveEventDetail",
        "parameters": [
          { "$ref": "#/components/parameters/EventIdPath" }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/GenericSuccess" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "502": { "$ref": "#/components/responses/ProviderError" }
        }
      }
    },
    "/sports/events/ended": {
      "get": {
        "tags": ["Sports Events"],
        "summary": "Get ended events",
        "operationId": "getEndedEvents",
        "parameters": [
          { "$ref": "#/components/parameters/SportIdQuery" },
          { "$ref": "#/components/parameters/PageQuery" },
          { "$ref": "#/components/parameters/DayQuery" }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/GenericSuccess" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "502": { "$ref": "#/components/responses/ProviderError" }
        }
      }
    },
    "/sports/events/{eventId}/odds": {
      "get": {
        "tags": ["Sports Events"],
        "summary": "Get prematch odds for an event",
        "operationId": "getEventOdds",
        "parameters": [
          { "$ref": "#/components/parameters/EventIdPath" }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/GenericSuccess" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "502": { "$ref": "#/components/responses/ProviderError" }
        }
      }
    },
    "/sports/events/{eventId}/odds/live": {
      "get": {
        "tags": ["Sports Events"],
        "summary": "Get live odds for an event",
        "operationId": "getLiveOdds",
        "parameters": [
          { "$ref": "#/components/parameters/EventIdPath" }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/GenericSuccess" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "502": { "$ref": "#/components/responses/ProviderError" }
        }
      }
    },
    "/sports/events/{eventId}/lineup": {
      "get": {
        "tags": ["Sports Events"],
        "summary": "Get lineup for an event",
        "operationId": "getEventLineup",
        "parameters": [
          { "$ref": "#/components/parameters/EventIdPath" }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/GenericSuccess" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "502": { "$ref": "#/components/responses/ProviderError" }
        }
      }
    },
    "/sports/events/{eventId}/stats-trend": {
      "get": {
        "tags": ["Sports Events"],
        "summary": "Get stats trend for an event",
        "operationId": "getEventStatsTrend",
        "parameters": [
          { "$ref": "#/components/parameters/EventIdPath" }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/GenericSuccess" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "502": { "$ref": "#/components/responses/ProviderError" }
        }
      }
    },
    "/sports/events/{eventId}/result": {
      "get": {
        "tags": ["Sports Events"],
        "summary": "Get final result for an event",
        "operationId": "getEventResult",
        "parameters": [
          { "$ref": "#/components/parameters/EventIdPath" }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/GenericSuccess" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "502": { "$ref": "#/components/responses/ProviderError" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "Token"
      },
      "partnerKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Partner-Key"
      }
    },
    "parameters": {
      "PageQuery": {
        "name": "page",
        "in": "query",
        "schema": { "type": "integer", "minimum": 1, "default": 1 },
        "required": false,
        "description": "Page number."
      },
      "PerPageQuery": {
        "name": "per_page",
        "in": "query",
        "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 },
        "required": false,
        "description": "Items per page."
      },
      "SearchQuery": {
        "name": "search",
        "in": "query",
        "schema": { "type": "string" },
        "required": false,
        "description": "Free text search."
      },
      "ProviderIdQuery": {
        "name": "provider",
        "in": "query",
        "schema": { "oneOf": [{ "type": "integer" }, { "type": "string" }] },
        "required": false,
        "description": "Provider identifier or slug."
      },
      "SportIdQuery": {
        "name": "sport_id",
        "in": "query",
        "schema": { "oneOf": [{ "type": "integer" }, { "type": "string" }] },
        "required": false,
        "description": "Sport identifier."
      },
      "CountryQuery": {
        "name": "country",
        "in": "query",
        "schema": { "type": "string" },
        "required": false,
        "description": "Country filter."
      },
      "LeagueIdQuery": {
        "name": "league_id",
        "in": "query",
        "schema": { "type": "string" },
        "required": false,
        "description": "League identifier."
      },
      "TeamIdQuery": {
        "name": "team_id",
        "in": "query",
        "schema": { "type": "string" },
        "required": false,
        "description": "Team identifier."
      },
      "ActiveQuery": {
        "name": "active",
        "in": "query",
        "schema": { "type": "boolean" },
        "required": false,
        "description": "Filter active records only."
      },
      "DateFromQuery": {
        "name": "date_from",
        "in": "query",
        "schema": { "type": "string", "format": "date" },
        "required": false,
        "description": "Initial date filter."
      },
      "DateToQuery": {
        "name": "date_to",
        "in": "query",
        "schema": { "type": "string", "format": "date" },
        "required": false,
        "description": "Final date filter."
      },
      "SortByQuery": {
        "name": "sort_by",
        "in": "query",
        "schema": { "type": "string" },
        "required": false,
        "description": "Sort field."
      },
      "SortDirectionQuery": {
        "name": "sort_direction",
        "in": "query",
        "schema": { "type": "string", "enum": ["asc", "desc"] },
        "required": false,
        "description": "Sort direction."
      },
      "DayQuery": {
        "name": "day",
        "in": "query",
        "schema": { "type": "string", "format": "date" },
        "required": false,
        "description": "Day used to query ended events."
      },
      "EventIdPath": {
        "name": "eventId",
        "in": "path",
        "required": true,
        "schema": { "type": "string" },
        "description": "Event identifier."
      }
    },
    "schemas": {
      "LaunchRequest": {
        "type": "object",
        "required": [
          "external_player_id",
          "player_name",
          "player_email",
          "player_balance",
          "game_code",
          "provider"
        ],
        "properties": {
          "external_player_id": { "type": "string", "maxLength": 255 },
          "player_name": { "type": "string", "maxLength": 255 },
          "player_email": { "type": "string", "format": "email", "maxLength": 255 },
          "player_balance": { "type": "number", "format": "float" },
          "game_code": { "type": "string", "maxLength": 255 },
          "provider": { "type": "string", "maxLength": 255 },
          "game_original": { "type": "boolean", "default": true },
          "lang": { "type": "string", "default": "pt" },
          "user_rtp": { "type": "number", "format": "float" }
        }
      },
      "CatalogRefreshRequest": {
        "type": "object",
        "properties": {
          "sport_id": { "oneOf": [{ "type": "integer" }, { "type": "string" }] },
          "import_leagues": { "type": "boolean", "default": true },
          "import_events": { "type": "boolean", "default": true }
        }
      },
      "Partner": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "name": { "type": "string" },
          "slug": { "type": "string" },
          "status": { "type": "string" }
        },
        "additionalProperties": true
      },
      "SuccessEnvelope": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "partner": { "$ref": "#/components/schemas/Partner" },
          "data": {
            "type": "object",
            "additionalProperties": true
          },
          "provider_response": {
            "type": "object",
            "additionalProperties": true
          },
          "message": { "type": "string" }
        },
        "required": ["success"]
      },
      "ErrorEnvelope": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": false },
          "message": { "type": "string" },
          "errors": {
            "type": "object",
            "additionalProperties": {
              "type": "array",
              "items": { "type": "string" }
            }
          }
        },
        "required": ["success", "message"]
      }
    },
    "responses": {
      "GenericSuccess": {
        "description": "Successful response",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing, invalid, or inactive partner token",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorEnvelope" },
            "example": {
              "success": false,
              "message": "Parceiro invalido ou inativo."
            }
          }
        }
      },
      "ValidationError": {
        "description": "Validation error",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorEnvelope" },
            "example": {
              "success": false,
              "message": "The given data was invalid.",
              "errors": {
                "game_code": ["The game code field is required."]
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "Requested resource was not found",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorEnvelope" },
            "example": {
              "success": false,
              "message": "Evento nao encontrado."
            }
          }
        }
      },
      "ProviderError": {
        "description": "Upstream provider communication failed",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorEnvelope" },
            "example": {
              "success": false,
              "message": "Falha ao consultar o provider esportivo."
            }
          }
        }
      }
    }
  }
}