{
    "schema_version": "1.0",
    "protocol": "agentic-commerce",
    "name": "Veruno Agentic Commerce API",
    "description": "API pro AI agenty umožňující procházení produktů, analýzu původu materiálů, ověřování certifikátů a realizaci nákupů.",
    "provider": {
        "name": "Veruno",
        "url": "https://veruno.cz",
        "contact": "veruno@veruno.cz"
    },
    "api": {
        "base_url": "https://veruno.cz/api/v1",
        "version": "2.6",
        "type": "REST",
        "format": "JSON"
    },
    "openapi_specs": {
        "description": "OpenAPI 3.1 schémata jednotlivých schopností — agent si je stáhne a volá přímo (např. import do ChatGPT Custom GPT Action). POST operace mají x-openai-isConsequential:false.",
        "rental_cars": "https://veruno.cz/openapi/rental.json",
        "rental_accommodation": "https://veruno.cz/openapi/ubytovani.json",
        "store": "https://veruno.cz/openapi/store.json"
    },
    "mcp": {
        "description": "Remote MCP server (Model Context Protocol) — připoj se a máš nástroje bez importu OpenAPI. Transport Streamable HTTP.",
        "endpoint": "https://mcp.veruno.cz/mcp",
        "transport": "streamable-http",
        "auth": "none (v1 veřejné nástroje)"
    },
    "endpoints": {
        "capabilities": "https://veruno.cz/api/v1/capabilities",
        "health": "https://veruno.cz/api/v1/health",
        "tenants": "https://veruno.cz/api/v1/tenants"
    },
    "authentication": {
        "required": false,
        "methods": [
            "bearer"
        ],
        "note": "Public endpoints (catalog, discovery, shipping_quote, payment_methods, public storefront checkout) require no auth. Admin/private endpoints (create_checkout_session via API, confirm_payment, change_order_status) require Bearer token. For agents without token use create_order_public via /store/{tenant}/."
    },
    "rate_limits": {
        "requests_per_minute": 100,
        "window_seconds": 60
    },
    "features": [
        "product_catalog",
        "provenance_tracking",
        "material_hierarchy",
        "document_certificates",
        "author_profiles",
        "coin_verification",
        "configurable_products",
        "ai_signals",
        "checkout",
        "shipping_quote",
        "payment_card",
        "payment_bank_transfer",
        "payment_cod",
        "stock_management",
        "rental_catalog",
        "rental_booking"
    ],
    "supported_operations": [
        {
            "name": "browse_products",
            "description": "Procházení katalogu produktů s filtrováním a řazením",
            "endpoint": "/{tenant}/products"
        },
        {
            "name": "get_product_detail",
            "description": "Detail produktu včetně atributů, médií a ceny",
            "endpoint": "/{tenant}/products/{sku}"
        },
        {
            "name": "get_provenance",
            "description": "Původ materiálů produktu s hierarchií a timeline",
            "endpoint": "/{tenant}/products/{sku}?include=provenance"
        },
        {
            "name": "browse_sources",
            "description": "Procházení zdrojů/materiálů",
            "endpoint": "/{tenant}/sources"
        },
        {
            "name": "verify_authenticity",
            "description": "Ověření autenticity produktu pomocí mince",
            "endpoint": "/{tenant}/verify?code={code}&hash={hash}"
        },
        {
            "name": "get_documents",
            "description": "Certifikáty a dokumenty produktů",
            "endpoint": "/{tenant}/documents"
        },
        {
            "name": "get_authors",
            "description": "Profily autorů/tvůrců",
            "endpoint": "/{tenant}/authors"
        },
        {
            "name": "get_profile",
            "description": "Tenant profil s capabilities a dostupnými endpointy — discovery endpoint pro AI agenty",
            "endpoint": "/{tenant}/profile"
        },
        {
            "name": "get_store_products",
            "description": "Produkty v nabídce (veřejné, bez auth) — pouze skladem, s cenou, show_in_store",
            "endpoint": "/{tenant}/stock/store"
        },
        {
            "name": "create_checkout_session",
            "description": "Vytvoření checkout session s produkty, dopravou a platební metodou",
            "endpoint": "/{tenant}/checkout/sessions",
            "method": "POST",
            "auth": "Bearer token"
        },
        {
            "name": "confirm_checkout",
            "description": "Potvrzení checkout session → vytvoření objednávky",
            "endpoint": "/{tenant}/checkout/sessions/{id}/confirm",
            "method": "POST",
            "auth": "Bearer token"
        },
        {
            "name": "shipping_quote",
            "description": "Kalkulace dopravy dle země, váhy a hodnoty objednávky",
            "endpoint": "/{tenant}/shipping/quote",
            "method": "POST"
        },
        {
            "name": "shipping_methods",
            "description": "Seznam dostupných metod dopravy s cenami",
            "endpoint": "/{tenant}/shipping/methods"
        },
        {
            "name": "confirm_payment",
            "description": "Potvrzení platby objednávky (manuální nebo webhook)",
            "endpoint": "/{tenant}/orders/{id}/confirm-payment",
            "method": "POST",
            "auth": "Bearer token"
        },
        {
            "name": "change_order_status",
            "description": "Změna statusu objednávky (triggery: stock, notifikace)",
            "endpoint": "/{tenant}/orders/{id}/status",
            "method": "PUT",
            "auth": "Bearer token"
        },
        {
            "name": "get_storefront",
            "description": "Veřejná storefront stránka s produkty, formulářem a checkout flow. URL je absolutní — NE pod /api/v1/ — používej přímo hodnotu v endpoint.",
            "endpoint": "https://veruno.cz/store/{tenant}/",
            "absolute_url": "https://veruno.cz/store/{tenant}/",
            "method": "GET",
            "auth": "none"
        },
        {
            "name": "create_order_public",
            "description": "Veřejné vytvoření objednávky bez Bearer tokenu — alternativa k create_checkout_session. Jednokrokové: POST přímo na storefront URL s _action=submit_order. Validuje shipping zónu (NO_SHIPPING_ZONE), metodu, platbu, sklad atomicky. Pro one-shot public orders preferuj tuto cestu; pro multi-step authenticated flows použij create_checkout_session + confirm_checkout.",
            "endpoint": "https://veruno.cz/store/{tenant}/",
            "absolute_url": "https://veruno.cz/store/{tenant}/",
            "method": "POST",
            "auth": "none",
            "content_type": "application/json",
            "payload": {
                "_action": "submit_order",
                "items": [
                    {
                        "sku": "SKU_CODE",
                        "qty": 1
                    }
                ],
                "billing": {
                    "first_name": "...",
                    "last_name": "...",
                    "email": "...",
                    "phone": "...",
                    "street": "...",
                    "city": "...",
                    "postal_code": "...",
                    "country": "DE"
                },
                "shipping_same_as_billing": true,
                "shipping_method_id": 11,
                "payment_method_code": "bank_transfer"
            },
            "errors": {
                "NO_SHIPPING_ZONE": "Země nemá nakonfigurovanou shipping zónu — zkus jinou zemi nebo GET /shipping/zones",
                "SHIPPING_METHOD_REQUIRED": "Chybí shipping_method_id — response obsahuje available_methods",
                "SHIPPING_METHOD_INVALID": "Zvolené method_id není pro zemi dostupné — response obsahuje available_methods"
            }
        },
        {
            "name": "get_shipping_zones",
            "description": "Kompletní mapa zóna → země → metody pro tenanta. Šetří agentům roundtripy oproti opakovanému shipping_quote per země.",
            "endpoint": "/{tenant}/shipping/zones",
            "method": "GET",
            "auth": "none"
        },
        {
            "name": "rental_catalog",
            "description": "Katalog pronájmu (auta, ubytování, technika) vč. dostupných kusů v termínu.",
            "endpoint": "/{tenant}/rental/catalog?loc=&from=&to=",
            "method": "GET",
            "auth": "none"
        },
        {
            "name": "rental_quote",
            "description": "Výpočet ceny + dostupnosti pronájmu pro termín (bez zápisu).",
            "endpoint": "/{tenant}/rental/quote",
            "method": "POST",
            "auth": "none",
            "content_type": "application/json",
            "payload": {
                "items": [
                    {
                        "item_id": 1,
                        "quantity": 1
                    }
                ],
                "from": "YYYY-MM-DD",
                "to": "YYYY-MM-DD",
                "coupon": "..."
            }
        },
        {
            "name": "rental_book_public",
            "description": "Veřejné vytvoření rezervace pronájmu bez Bearer tokenu (pro AI agenty). Vytvoří rezervaci „čeká na platbu\" a vrátí payment_url; platbu dokončí ČLOVĚK přes payment_url (agent nikdy nezadává platební údaje). Dostupnost se re-checkuje pod zámkem, nezaplacené se auto-cancelují.",
            "endpoint": "/{tenant}/rental/book-public",
            "method": "POST",
            "auth": "none",
            "content_type": "application/json",
            "payload": {
                "items": [
                    {
                        "item_id": 1,
                        "quantity": 1
                    }
                ],
                "from": "YYYY-MM-DD",
                "to": "YYYY-MM-DD",
                "customer_first": "...",
                "customer_last": "...",
                "customer_email": "...",
                "customer_phone": "...",
                "coupon": "...",
                "note": "...",
                "consent_terms": true,
                "consent_gdpr": true
            },
            "returns": [
                "booking_code",
                "access_token",
                "payment_url",
                "total_price",
                "deposit_amount",
                "currency",
                "status"
            ]
        },
        {
            "name": "rental_booking_status",
            "description": "Stav rezervace pronájmu dle kódu (?t=access_token = detail zákazníka).",
            "endpoint": "/{tenant}/rental/bookings/{code}?t={access_token}",
            "method": "GET",
            "auth": "none"
        }
    ],
    "commerce_flow": {
        "description": "Dvě cesty pro AI agenty — A) public bez auth (jednokrokové přes storefront), B) private API s Bearer tokenem (dvoukrokové přes /checkout/sessions)",
        "path_a_public": [
            "1. GET /{tenant}/profile → storefront.url (absolutní /store/{tenant}/)",
            "2. GET /{tenant}/stock/store → produkty v nabídce",
            "3. GET /{tenant}/shipping/zones → mapa zóna→země→metody (jednorázově, cacheable)",
            "4. POST {storefront.url} s _action=submit_order → objednávka vytvořena v jednom kroku (auth: none)"
        ],
        "path_b_bearer": [
            "1. GET /{tenant}/profile → capabilities + _links (discovery)",
            "2. GET /{tenant}/stock/store → produkty v nabídce (veřejné)",
            "3. POST /{tenant}/shipping/quote → kalkulace dopravy dle země + váhy",
            "4. POST /{tenant}/checkout/sessions → checkout session (Bearer, 30 min expiry)",
            "5. POST /{tenant}/checkout/sessions/{id}/confirm → vytvoření objednávky (Bearer)",
            "6. Platba: Stripe redirect (card) / bankovní převod (5 dnů) / dobírka (COD)",
            "7. POST /{tenant}/orders/{id}/confirm-payment → potvrzení platby (Bearer)"
        ],
        "payment_methods": [
            "card (Stripe)",
            "bank_transfer",
            "cod"
        ],
        "order_statuses": [
            "awaiting_payment",
            "paid",
            "processing",
            "shipped",
            "delivered",
            "cancelled",
            "expired"
        ]
    },
    "rental_flow": {
        "description": "Pronájem (auta, ubytování, technika) pro AI agenty — veřejně bez auth. Rezervace vzniká ve stavu čeká na platbu, platbu dokončí člověk přes payment_url.",
        "steps": [
            "1. GET /{tenant}/rental/catalog?from=&to= → položky + dostupné kusy v termínu",
            "2. POST /{tenant}/rental/quote → ceny + dostupnost (bez zápisu)",
            "3. POST /{tenant}/rental/book-public → rezervace „čeká na platbu\" + payment_url (auth: none)",
            "4. Platbu dokončí zákazník přes payment_url (agent nikdy nezadává platební údaje)",
            "5. GET /{tenant}/rental/bookings/{code}?t=access_token → stav rezervace"
        ],
        "payment": "card (Comgate) → payment_url; nezaplacené rezervace se auto-cancelují"
    },
    "data_model": {
        "product": {
            "identifiers": [
                "id",
                "uid",
                "sku",
                "slug"
            ],
            "key_fields": [
                "name",
                "category",
                "offer",
                "attributes",
                "signals"
            ]
        },
        "source": {
            "identifiers": [
                "id",
                "uid",
                "code"
            ],
            "key_fields": [
                "name",
                "type",
                "origin",
                "lifecycle_status"
            ]
        }
    },
    "localization": {
        "default_language": "cs",
        "supported_languages": [
            "cs",
            "en"
        ]
    },
    "_links": {
        "agent_hub": "https://veruno.cz/agents",
        "llms_txt": "https://veruno.cz/llms.txt",
        "documentation": "https://veruno.cz/docs",
        "audit": "https://veruno.cz/audit",
        "terms": "https://veruno.cz/terms/veruno",
        "privacy": "https://veruno.cz/privacy/veruno"
    }
}