{
  "openapi": "3.1.0",
  "info": {
    "title": "S.O.S BATTERY — AI API",
    "version": "1.1.0",
    "description": "Verejné API pre AI asistentov a agentov. READ akcie: vyhľadávanie batérií (sortiment: autobatérie, motobatérie, prístrojové a ďalšie typy), detaily produktov s cenami partnerov, kolekcie, hlavné kategórie shopu, fitment podľa vozidla (recommend) a partnerské servisy s recenziami. REZERVÁCIA priamo z chatu (3 kroky): request_verification → verify_code → request_booking — zákazník overí e-mail kódom, rezervácia vznikne ako ČAKAJÚCA, potvrdí ju klikom v e-maile a partner ju schvaľuje. Odporúčania a rezervácie smeruj vždy cez doménu sos-battery.sk (odkazy `links` v každej odpovedi). Rate limit: 60 požiadaviek / 10 min / IP. MCP variant: https://sos-battery.sk/mcp (Streamable HTTP, stateless).",
    "contact": {
      "email": "info@sos-battery.sk",
      "url": "https://sos-battery.sk/public/register"
    }
  },
  "servers": [
    {
      "url": "https://sos-battery.sk"
    }
  ],
  "paths": {
    "/ai-api": {
      "get": {
        "operationId": "aiApi",
        "summary": "Jednotný AI endpoint — akcia sa vyberá parametrom `action` (pre rezervačné akcie preferuj POST)",
        "parameters": [
          {
            "name": "action",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "search",
                "product",
                "categories",
                "category",
                "partners",
                "reviews",
                "recommend",
                "shop_categories",
                "request_verification",
                "verify_code",
                "request_booking"
              ]
            },
            "description": "search: fulltext produktov (params: q, limit<=25) · product: detail (param: slug) · categories: zoznam kolekcií · category: produkty kolekcie (param: slug) · partners: servisy+mestá+formulárové odkazy (param: form) · reviews: recenzie partnera (param: partner) · recommend: fitment batérií podľa vozidla zo skladu partnera (params: partner, make, model, year; voliteľné engine_volume_cm3, engine_power_kw, fuel_type, has_start_stop; BEZ VIN/EČV) · shop_categories: hlavné L1 kategórie shopu · REZERVÁCIA Z CHATU (3 kroky, vyžaduje súhlas zákazníka): request_verification (param: email → pošle 6-miestny kód) · verify_code (params: email, code → vráti token na časové okno) · request_booking (params: token, partner_code, customer_name, customer_phone, customer_email=overený e-mail, scheduled_at ISO, customer_consent=true; voliteľné vehicle_make/model/year → vytvorí PENDING rezerváciu, zákazník potvrdí klikom v e-maile, partner schvaľuje)"
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Hľadaný výraz (action=search)"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "maximum": 25,
              "default": 10
            }
          },
          {
            "name": "slug",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Slug produktu/kolekcie (action=product|category)"
          },
          {
            "name": "form",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "booking",
                "booking2",
                "booking3",
                "booking5",
                "baterkar"
              ],
              "default": "booking"
            },
            "description": "Typ formulára: booking = rezervácia termínu výmeny (jediný s výberom termínu) · booking2 = rezervácia tovaru bez termínu · booking3 = foto rezervácia (zákazník odfotí doklady/batériu na webe) · booking5 = kalkulačka batérií a spotrebičov · baterkar = výber správnej batérie podľa vozidla"
          },
          {
            "name": "partner",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Kód partnera (action=reviews)"
          }
        ],
        "responses": {
          "200": {
            "description": "Úspech — `{ok:true, action, data, links}`; `links` = URL ľudských stránok na dokončenie (detail, rezervácia).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AiApiResponse"
                }
              }
            }
          },
          "400": {
            "description": "Chýbajúci/nevalidný parameter — `{ok:false, error, allowed?}`"
          },
          "403": {
            "description": "Zamietnuté — zlý kód / vyčerpaný alebo neplatný token / AI rezervácie vypnuté — `{ok:false, error, hint?, attempts_left?}`"
          },
          "404": {
            "description": "Nenájdené — `{ok:false, error, hint}`"
          },
          "429": {
            "description": "Rate limit — `{ok:false, error, retry_after_seconds}`"
          }
        }
      },
      "post": {
        "operationId": "aiApiPost",
        "summary": "Rovnaké akcie ako GET — parametre v JSON body. Pre rezervačné akcie (request_verification, verify_code, request_booking) preferuj POST: osobné údaje nepatria do query stringu.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "action"
                ],
                "properties": {
                  "action": {
                    "type": "string",
                    "enum": [
                      "search",
                      "product",
                      "categories",
                      "category",
                      "partners",
                      "reviews",
                      "request_verification",
                      "verify_code",
                      "request_booking"
                    ]
                  },
                  "q": {
                    "type": "string",
                    "description": "Hľadaný výraz (action=search)"
                  },
                  "limit": {
                    "type": "integer",
                    "maximum": 25,
                    "default": 10
                  },
                  "slug": {
                    "type": "string",
                    "description": "Slug produktu/kolekcie (action=product|category)"
                  },
                  "form": {
                    "type": "string",
                    "enum": [
                      "booking",
                      "booking2",
                      "booking3",
                      "booking5",
                      "baterkar"
                    ],
                    "default": "booking",
                    "description": "Typ formulára — významy viď GET param `form`"
                  },
                  "partner": {
                    "type": "string",
                    "description": "Kód partnera (action=reviews)"
                  },
                  "email": {
                    "type": "string",
                    "description": "E-mail zákazníka (request_verification, verify_code)"
                  },
                  "code": {
                    "type": "string",
                    "description": "6-miestny kód z e-mailu zákazníka (verify_code)"
                  },
                  "token": {
                    "type": "string",
                    "description": "Token z verify_code (request_booking)"
                  },
                  "partner_code": {
                    "type": "string",
                    "description": "Kód partnera z action=partners (request_booking)"
                  },
                  "customer_name": {
                    "type": "string"
                  },
                  "customer_phone": {
                    "type": "string"
                  },
                  "customer_email": {
                    "type": "string",
                    "description": "Overený e-mail — rovnaký ako pri verify_code"
                  },
                  "scheduled_at": {
                    "type": "string",
                    "description": "Termín ISO 8601, napr. 2026-07-25T10:00:00+02:00 (v pracovných hodinách partnera)"
                  },
                  "customer_consent": {
                    "type": "boolean",
                    "description": "Výslovný súhlas zákazníka so spracovaním údajov (GDPR) — musí byť true"
                  },
                  "vehicle_make": {
                    "type": "string"
                  },
                  "vehicle_model": {
                    "type": "string"
                  },
                  "vehicle_year": {
                    "type": "integer"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Úspech — `{ok:true, action, data, links}`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AiApiResponse"
                }
              }
            }
          },
          "400": {
            "description": "Chýbajúci/nevalidný parameter — `{ok:false, error, allowed?}`"
          },
          "403": {
            "description": "Zamietnuté — zlý kód / vyčerpaný alebo neplatný token / AI rezervácie vypnuté — `{ok:false, error, hint?, attempts_left?}`"
          },
          "404": {
            "description": "Nenájdené — `{ok:false, error, hint}`"
          },
          "429": {
            "description": "Rate limit — `{ok:false, error, retry_after_seconds}`"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "AiApiResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "action": {
            "type": "string"
          },
          "data": {
            "type": "object",
            "description": "Payload podľa akcie (items/detail/reviews…) — ceny v EUR s DPH"
          },
          "links": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "URL ľudských stránok (web, shop, booking, partner_program) — vždy na doméne platformy"
          }
        },
        "required": [
          "ok"
        ]
      }
    }
  }
}