{
  "openapi": "3.1.0",
  "info": {
    "title": "Plantapont publikus API",
    "description": "Csak-olvasható, nyilvános termék- és üzletadat a Plantapont csomagolásmentes webshopból, AI-ügynökök és integrációk számára. Nem tartalmaz rendelési, ügyfél- vagy adminisztrációs adatot. A fizetés jelenleg emberi checkouton keresztül történik.",
    "version": "1.0.0",
    "contact": {
      "name": "Plantapont",
      "url": "https://plantapont.hu"
    },
    "license": {
      "name": "Nyilvános adat, csak-olvasható használat"
    }
  },
  "servers": [
    {
      "url": "https://plantapont.hu",
      "description": "Éles környezet"
    }
  ],
  "externalDocs": {
    "description": "Fejlesztői / gépi interfész áttekintés",
    "url": "https://plantapont.hu/api_info.php"
  },
  "paths": {
    "/api.php": {
      "get": {
        "operationId": "getResource",
        "summary": "Termékek, egy termék vagy üzletek lekérése",
        "description": "A `resource` paraméter dönti el, mit ad vissza: `products` (lista), `product` (egy termék, `id` kötelező), `stores` (üzletek).",
        "parameters": [
          {
            "name": "resource",
            "in": "query",
            "required": true,
            "description": "A lekérdezett erőforrás típusa.",
            "schema": {
              "type": "string",
              "enum": ["products", "product", "stores"]
            }
          },
          {
            "name": "id",
            "in": "query",
            "required": false,
            "description": "Termékazonosító. Csak `resource=product` esetén kötelező.",
            "schema": { "type": "integer", "minimum": 1 }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Találatok száma (csak `resource=products`). 1–500, alap: 100.",
            "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Lapozási eltolás (csak `resource=products`).",
            "schema": { "type": "integer", "minimum": 0, "default": 0 }
          }
        ],
        "responses": {
          "200": {
            "description": "Sikeres válasz.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    { "$ref": "#/components/schemas/ProductListResponse" },
                    { "$ref": "#/components/schemas/ProductResponse" },
                    { "$ref": "#/components/schemas/StoreListResponse" }
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Nem található termék.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" },
                "example": { "error": "not_found" }
              }
            }
          },
          "503": {
            "description": "Az adatbázis átmenetileg nem elérhető.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" },
                "example": { "error": "temporarily_unavailable" }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "postQuote",
        "summary": "Állapotmentes árajánlat (kosár-validáció)",
        "description": "Tájékoztató árajánlatot ad megadott tételekre a nyilvános alapárak alapján. NEM tárol és NEM kezel fizetést. A `resource=quote` query paraméter kötelező. Kimért (grammos/milliliteres) árunál a mennyiség és az egységár a mértékegységre vonatkozik.",
        "parameters": [
          {
            "name": "resource",
            "in": "query",
            "required": true,
            "schema": { "type": "string", "enum": ["quote"] }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/QuoteRequest" },
              "example": { "items": [ { "id": 1, "quantity": 2 } ] }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Árajánlat.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/QuoteResponse" }
              }
            }
          },
          "400": {
            "description": "Hibás kérés (hiányzó vagy rossz `items`).",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" },
                "example": { "error": "invalid_request", "expected": { "items": [ { "id": 1, "quantity": 2 } ] } }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Product": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "sku": { "type": "string" },
          "name": { "type": "string" },
          "url": { "type": "string", "format": "uri" },
          "description": { "type": "string" },
          "image": { "type": "string", "format": "uri" },
          "price": { "type": "number", "description": "Nyilvános alapár. Kimért árunál egységár (lásd unit / price_per_unit)." },
          "currency": { "type": "string", "example": "HUF" },
          "availability": { "type": "string", "enum": ["in_stock", "out_of_stock"] },
          "condition": { "type": "string", "example": "new" },
          "brand": { "type": "string", "example": "Plantapont" },
          "category": { "type": "string", "description": "Kategória-útvonal, pl. 'Konyhai alapanyagok > Tészták, rizs'." },
          "unit": { "type": "string", "description": "Mértékegység (g, ml, db, ...).", "example": "g" },
          "price_per_unit": { "type": "string", "description": "Ember-olvasható egységár.", "example": "2.72 HUF/g" },
          "reference_price": {
            "type": "object",
            "description": "Kimért árunál a szokásos referenciaár (Ft/kg, Ft/liter).",
            "properties": {
              "value": { "type": "number", "example": 2720 },
              "unit": { "type": "string", "example": "kg" },
              "currency": { "type": "string", "example": "HUF" }
            }
          },
          "sale_price": { "type": "number", "description": "Akciós ár, ha van." },
          "gtin": { "type": "string", "description": "Vonalkód, ha van." },
          "mpn": { "type": "string", "description": "Gyártói cikkszám, ha van." }
        },
        "required": ["id", "name", "url", "price", "currency", "availability"]
      },
      "Store": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "name": { "type": "string" },
          "city": { "type": "string" },
          "address": { "type": "string" },
          "phone": { "type": "string" },
          "email": { "type": "string" },
          "url": { "type": "string", "format": "uri" }
        }
      },
      "ProductListResponse": {
        "type": "object",
        "properties": {
          "currency": { "type": "string" },
          "limit": { "type": "integer" },
          "offset": { "type": "integer" },
          "count": { "type": "integer" },
          "products": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }
        }
      },
      "ProductResponse": {
        "type": "object",
        "properties": {
          "product": { "$ref": "#/components/schemas/Product" }
        }
      },
      "StoreListResponse": {
        "type": "object",
        "properties": {
          "count": { "type": "integer" },
          "stores": { "type": "array", "items": { "$ref": "#/components/schemas/Store" } }
        }
      },
      "QuoteRequest": {
        "type": "object",
        "required": ["items"],
        "properties": {
          "items": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "object",
              "required": ["id"],
              "properties": {
                "id": { "type": "integer", "minimum": 1 },
                "quantity": { "type": "integer", "minimum": 1, "default": 1, "description": "Kimért árunál a mértékegységben (pl. gramm)." }
              }
            }
          }
        }
      },
      "QuoteResponse": {
        "type": "object",
        "properties": {
          "currency": { "type": "string" },
          "items": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": { "type": "integer" },
                "sku": { "type": "string" },
                "name": { "type": "string" },
                "quantity": { "type": "integer" },
                "unit_price": { "type": "number" },
                "line_total": { "type": "number" },
                "currency": { "type": "string" },
                "availability": { "type": "string" },
                "status": { "type": "string", "enum": ["ok", "unavailable"] },
                "unit": { "type": "string" },
                "price_per_unit": { "type": "string" },
                "reference_price": { "type": "object" },
                "measured_note": { "type": "string" }
              }
            }
          },
          "subtotal": { "type": "number" },
          "total": { "type": "number" },
          "fulfillment": {
            "type": "object",
            "properties": {
              "type": { "type": "string", "example": "store_pickup" },
              "price": { "type": "number" },
              "currency": { "type": "string" },
              "description": { "type": "string" }
            }
          },
          "checkout": {
            "type": "object",
            "properties": {
              "status": { "type": "string", "example": "human_checkout_only" },
              "message": { "type": "string" },
              "url": { "type": "string", "format": "uri" }
            }
          },
          "note": { "type": "string" }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": { "type": "string" }
        }
      }
    }
  }
}