{
  "openapi": "3.1.0",
  "info": {
    "title": "ZYS Toys South Africa - Autonomous AI Shopping API",
    "description": "API enabling AI agents (ChatGPT, Gemini, Claude, Grok, LangChain) to browse 319 child-safe toys, manage cart sessions directly in chat, calculate South African courier transit times, and execute secure 3D-Secure checkouts without leaving the chat.",
    "version": "1.0.0",
    "contact": {
      "name": "ZYS Toys Durban Central Hub",
      "url": "https://zys.co.za/",
      "email": "orders@zys.co.za"
    }
  },
  "servers": [
    {
      "url": "https://zys.co.za",
      "description": "Production Server"
    }
  ],
  "paths": {
    "/api/agent.php?action=search": {
      "get": {
        "operationId": "searchToys",
        "summary": "Search 319 authenticated child-safe toys by keyword, category, age, or budget in ZAR",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "description": "Keywords, e.g. 'magnetic tiles', 'puzzle', 'balance bike'",
            "schema": { "type": "string" }
          },
          {
            "name": "pillar",
            "in": "query",
            "description": "Product category pillar",
            "schema": { "type": "string", "enum": ["all", "baby", "play", "move", "replay"] }
          },
          {
            "name": "age",
            "in": "query",
            "description": "Target child age bracket in years",
            "schema": { "type": "string", "enum": ["all", "0-1", "1-2", "3-5", "6-8", "8+"] }
          },
          {
            "name": "max_price",
            "in": "query",
            "description": "Maximum price in ZAR (e.g. 250 for party gifts)",
            "schema": { "type": "number" }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Number of results to return",
            "schema": { "type": "integer", "default": 8 }
          }
        ],
        "responses": {
          "200": {
            "description": "List of matching toys with prices, stock status, and direct URLs"
          }
        }
      }
    },
    "/api/agent.php?action=toy_details": {
      "get": {
        "operationId": "getToyDetails",
        "summary": "Retrieve complete toy specifications, SABS child-safety compliance, and stock count",
        "parameters": [
          {
            "name": "product_id",
            "in": "query",
            "required": true,
            "description": "Product ID, e.g. 'ivops-1539'",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Comprehensive toy information"
          }
        }
      }
    },
    "/api/agent.php?action=cart_add": {
      "post": {
        "operationId": "addToCart",
        "summary": "Add a toy to the customer's chat shopping cart and calculate free delivery qualification",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "cart_id": { "type": "string", "description": "Existing cart ID. Leave empty on first call to generate a new cart." },
                  "product_id": { "type": "string", "description": "Toy product ID to add" },
                  "quantity": { "type": "integer", "default": 1 }
                },
                "required": ["product_id"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated cart status, subtotal, and remaining gap to FREE courier delivery"
          }
        }
      }
    },
    "/api/agent.php?action=cart_view": {
      "get": {
        "operationId": "viewCart",
        "summary": "View current items, quantities, subtotal, and free delivery status of a cart",
        "parameters": [
          {
            "name": "cart_id",
            "in": "query",
            "required": true,
            "description": "Cart ID returned by cart_add",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Current cart breakdown"
          }
        }
      }
    },
    "/api/agent.php?action=cart_remove": {
      "post": {
        "operationId": "removeFromCart",
        "summary": "Remove or decrease quantity of a toy in the chat cart",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "cart_id": { "type": "string" },
                  "product_id": { "type": "string" },
                  "quantity": { "type": "integer", "description": "Quantity to decrement. Omit to remove item completely." }
                },
                "required": ["cart_id", "product_id"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated cart summary"
          }
        }
      }
    },
    "/api/agent.php?action=delivery_quote": {
      "get": {
        "operationId": "getDeliveryQuote",
        "summary": "Get courier transit times (JHB 1-2d, CPT 2-3d) and on-demand Uber operating hours",
        "parameters": [
          {
            "name": "city",
            "in": "query",
            "description": "Destination city, e.g. Johannesburg, Cape Town, Durban",
            "schema": { "type": "string", "default": "Johannesburg" }
          },
          {
            "name": "province",
            "in": "query",
            "description": "Province name, e.g. Gauteng, Western Cape, KwaZulu-Natal",
            "schema": { "type": "string" }
          },
          {
            "name": "subtotal",
            "in": "query",
            "description": "Cart subtotal in ZAR (Free courier on orders > R650)",
            "schema": { "type": "number", "default": 0 }
          }
        ],
        "responses": {
          "200": {
            "description": "Courier and on-demand quotes"
          }
        }
      }
    },
    "/api/agent.php?action=checkout": {
      "post": {
        "operationId": "checkoutOrder",
        "summary": "Finalize customer order, dispatch warehouse Telegram alert, and generate 1-tap PayFast 3D Secure link",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "cart_id": { "type": "string", "description": "The cart ID holding customer items" },
                  "customer_name": { "type": "string", "description": "Full name" },
                  "customer_phone": { "type": "string", "description": "South African mobile number, e.g. 082 123 4567" },
                  "customer_email": { "type": "string", "description": "Customer email" },
                  "street_address": { "type": "string", "description": "Delivery address" },
                  "city": { "type": "string", "description": "Delivery city" },
                  "province": { "type": "string", "default": "KwaZulu-Natal" },
                  "delivery_type": { "type": "string", "enum": ["courier_std", "uber_ondemand", "pargo_pickup"], "default": "courier_std" },
                  "promo_code": { "type": "string", "description": "Discount code, e.g. TOYMAGIC" }
                },
                "required": ["cart_id", "customer_name", "customer_phone", "street_address", "city"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Order number, PayFast secure link, and WhatsApp 1-tap checkout link"
          }
        }
      }
    },
    "/api/agent.php?action=track": {
      "get": {
        "operationId": "trackOrder",
        "summary": "Track real-time order packing and courier transit status by order reference",
        "parameters": [
          {
            "name": "order_number",
            "in": "query",
            "required": true,
            "description": "Order reference, e.g. ZYS-261001-29CD7",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Order status, tracking timeline, and support contacts"
          }
        }
      }
    },
    "/api/agent.php?action=ivops_quick_add": {
      "post": {
        "operationId": "ivopsQuickAdd",
        "summary": "1-Shot Direct IVOPS Connector: Add any toy to cart directly using its IVOPS ID (e.g. #2774 or 2774)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "cart_id": { "type": "string", "description": "Optional existing cart ID" },
                  "ivops_id": { "type": "string", "description": "The IVOPS ID or hashtag ID, e.g. '#2774' or '2774'" },
                  "quantity": { "type": "integer", "default": 1 }
                },
                "required": ["ivops_id"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated cart details and free courier threshold"
          }
        }
      }
    },
    "/api/ivops_connector.php": {
      "get": {
        "operationId": "ivopsConnectorLookup",
        "summary": "Universal IVOPS Direct ID Connector - Lookup toy by ID (e.g. #2774)",
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "required": true,
            "description": "IVOPS ID, e.g. '2774' or '#2774'",
            "schema": { "type": "string" }
          },
          {
            "name": "action",
            "in": "query",
            "description": "'lookup' (default) or 'add_to_cart'",
            "schema": { "type": "string", "enum": ["lookup", "add_to_cart"] }
          }
        ],
        "responses": {
          "200": {
            "description": "Direct toy details, pricing, and live action URLs"
          }
        }
      }
    }
  }
}