{
  "openapi": "3.0.3",
  "info": {
    "title": "Play Shop Public API",
    "version": "1.0.0",
    "description": "Server-to-server donation/top-up API. No CORS. HMAC or API key+secret."
  },
  "servers": [{ "url": "/api/v1" }],
  "paths": {
    "/health": {
      "get": {
        "summary": "Health check",
        "security": [],
        "responses": { "200": { "description": "OK" } }
      }
    },
    "/games": {
      "get": {
        "summary": "List games and packages",
        "parameters": [
          { "name": "page", "in": "query", "schema": { "type": "integer" } },
          { "name": "per_page", "in": "query", "schema": { "type": "integer", "maximum": 100 } },
          { "name": "search", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Catalog" } }
      }
    },
    "/balance": {
      "get": {
        "summary": "Account balance",
        "responses": { "200": { "description": "Balance USD" } }
      }
    },
    "/check-player": {
      "post": {
        "summary": "Validate player ID",
        "responses": { "200": { "description": "valid + player_name" } }
      }
    },
    "/orders": {
      "get": {
        "summary": "List own orders",
        "responses": { "200": { "description": "Order list" } }
      },
      "post": {
        "summary": "Create order",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": { "type": "string", "format": "uuid" }
          }
        ],
        "responses": {
          "201": { "description": "Created/completed" },
          "202": { "description": "Accepted pending" },
          "402": { "description": "Insufficient balance" }
        }
      }
    },
    "/orders/{order_id}": {
      "get": {
        "summary": "Get order",
        "parameters": [
          { "name": "order_id", "in": "path", "required": true, "schema": { "type": "integer" } }
        ],
        "responses": { "200": { "description": "Order" }, "404": { "description": "Not found" } }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKey": { "type": "apiKey", "in": "header", "name": "X-API-KEY" },
      "ApiSecret": { "type": "apiKey", "in": "header", "name": "X-API-SECRET" }
    },
    "security": [{ "ApiKey": [], "ApiSecret": [] }]
  }
}