{ "openapi": "3.0.3", "info": { "title": "PhoenixCart Agent Shopping API", "version": "1.0.0", "description": "Rozhraní pro autonomní nákupní agenty: vyhledávání produktů, správa košíku přihlášeného zákazníka a dokončení nákupu v mezích výdajového mandátu." }, "servers": [ { "url": "/" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/agent/search.php": { "get": { "summary": "Vyhledat produkty", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "category", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "min_price", "in": "query", "schema": { "type": "number", "minimum": 0 } }, { "name": "max_price", "in": "query", "schema": { "type": "number", "minimum": 0 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } } ], "responses": { "200": { "description": "Seznam produktů" }, "405": { "description": "Metoda není podporována (viz hlavička Allow).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Neplatný požadavek (chybějící nebo nesmyslný parametr).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Chybí, vypršel nebo byl zneplatněn token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Token nemá potřebný scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Vyčerpaný limit požadavků za minutu.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/product.php": { "get": { "summary": "Detail produktu", "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Detail produktu včetně všech jeho vydání.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } }, "405": { "description": "Metoda není podporována (viz hlavička Allow).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Produkt nenalezen nebo není dostupný.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Neplatný požadavek (chybějící nebo nesmyslný parametr).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Chybí, vypršel nebo byl zneplatněn token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Token nemá potřebný scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Vyčerpaný limit požadavků za minutu.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/cart.php": { "get": { "summary": "Zobrazit obsah košíku přihlášeného zákazníka", "responses": { "200": { "description": "Obsah košíku" }, "405": { "description": "Metoda není podporována (viz hlavička Allow).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Neplatný požadavek (chybějící nebo nesmyslný parametr).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Chybí, vypršel nebo byl zneplatněn token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Token nemá potřebný scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Vyčerpaný limit požadavků za minutu.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Upravit košík (přidat / změnit množství / odebrat)", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "op", "products_id" ], "properties": { "op": { "type": "string", "enum": [ "add", "update", "remove" ] }, "products_id": { "type": "integer", "minimum": 1 }, "qty": { "type": "integer", "minimum": 0 }, "attributes": { "type": "object", "description": "Varianty jako {option_id: value_id}, obojí celá kladná čísla.", "additionalProperties": { "type": "integer", "minimum": 1 } } } } } } }, "responses": { "200": { "description": "Aktualizovaný košík" }, "405": { "description": "Metoda není podporována (viz hlavička Allow).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Produkt nelze přidat (neplatné id nebo varianta).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Neplatný požadavek (chybějící nebo nesmyslný parametr).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Chybí, vypršel nebo byl zneplatněn token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Token nemá potřebný scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Vyčerpaný limit požadavků za minutu.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/checkout.php": { "post": { "summary": "Náhled nebo dokončení objednávky", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "op" ], "properties": { "op": { "type": "string", "enum": [ "preview", "place" ] }, "address_book_id": { "type": "integer" }, "shipping_module": { "type": "string" }, "payment_token_id": { "type": "integer" }, "comments": { "type": "string" } } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Povinné pro op=place." } ], "responses": { "200": { "description": "Náhled objednávky, potvrzená objednávka, nebo stav 'pending_approval'." }, "405": { "description": "Metoda není podporována (viz hlavička Allow).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Neplatný požadavek (chybějící nebo nesmyslný parametr).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Chybí, vypršel nebo byl zneplatněn token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Token nemá potřebný scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Vyčerpaný limit požadavků za minutu.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Platba byla zamítnuta nebo nedokončena.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Položka už není skladem.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Košík, adresa, doprava nebo platba nedává smysl.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Platební modul není dostupný.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API token vytvořený zákazníkem v account_agent_tokens.php." } }, "schemas": { "Error": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } }, "Edition": { "type": "object", "description": "Jedno vydání knihy. Kniha je dílo a drží všechna svá vydání pohromadě; kupuje se vždy konkrétní vydání (add_to_cart_url).", "properties": { "id": { "type": "integer", "description": "products_attributes_id, do košíku jako pa" }, "kind": { "type": "string", "enum": [ "new", "ebook", "bazaar" ], "description": "nový tisk, e-kniha, bazarový kus" }, "name": { "type": "string", "description": "označení varianty, např. Tištěná" }, "publisher": { "type": "string", "nullable": true }, "year": { "type": "integer", "nullable": true }, "edition": { "type": "string", "nullable": true, "description": "např. třetí vydání" }, "isbn": { "type": "string", "nullable": true, "description": "ISBN tohoto vydání, ne díla" }, "binding": { "type": "string", "nullable": true, "enum": [ "hard", "soft", null ] }, "pages": { "type": "integer", "nullable": true }, "languages": { "type": "array", "items": { "type": "string" }, "description": "ISO 639-1; dvě u dvojjazyčného tisku, primární první" }, "translator": { "type": "string", "nullable": true, "description": "jméno příjmením napřed, jak ho drží rejstřík" }, "people": { "type": "object", "description": "další role tohoto vydání, jména příjmením napřed", "properties": { "foreword": { "type": "array", "items": { "type": "string" } }, "afterword": { "type": "array", "items": { "type": "string" } }, "illustrator": { "type": "array", "items": { "type": "string" } } } }, "note": { "type": "string", "nullable": true, "description": "co je zvláštního na tomhle vydání" }, "price": { "type": "number" }, "price_formatted": { "type": "string" }, "in_stock": { "type": "boolean", "description": "e-kniha je skladem vždy" }, "quantity_available": { "type": "integer" }, "image": { "type": "string", "nullable": true, "description": "obálka tohoto vydání" }, "url": { "type": "string", "description": "stránka knihy s kotvou na tohle vydání" }, "add_to_cart_url": { "type": "string" } } }, "Product": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "model": { "type": "string", "nullable": true }, "description": { "type": "string" }, "price": { "type": "number", "description": "nejnižší cena; konkrétní ceny jsou na vydáních" }, "price_formatted": { "type": "string" }, "currency": { "type": "string" }, "in_stock": { "type": "boolean" }, "quantity_available": { "type": "integer" }, "weight": { "type": "number" }, "manufacturer": { "type": "string", "nullable": true, "description": "nakladatel výchozího vydání" }, "images": { "type": "array", "items": { "type": "string" } }, "editions": { "type": "array", "items": { "$ref": "#/components/schemas/Edition" } }, "url": { "type": "string" } } } } } }