{
  "openapi": "3.1.0",
  "info": {
    "title": "Jessico Foods & Beverages AI Agent API",
    "description": "Public machine-readable API for Jessico Foods & Beverages — Kerala's premier multi-brand FMCG food and beverage distributor. This API enables AI agents and commercial partners to query product catalogues, examine territory dealership vacancies, and submit wholesale trade enquiries or manufacturer proposals.",
    "version": "1.0.0",
    "contact": {
      "name": "Jessico Commercial Desk",
      "url": "https://jessicofoods.com/contact",
      "email": "jessicofoodsandbeverages@gmail.com"
    }
  },
  "servers": [
    {
      "url": "https://jessicofoods.com",
      "description": "Production Server"
    }
  ],
  "paths": {
    "/api/products": {
      "get": {
        "summary": "Query Product Catalogue",
        "description": "Search and filter the distributed FMCG food and beverage product lines.",
        "operationId": "getProducts",
        "parameters": [
          {
            "name": "categoryId",
            "in": "query",
            "description": "Category slug to filter by (e.g., snacks-biscuits, beverages, grocery-staples, sauces-condiments, confectionery)",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "query",
            "in": "query",
            "description": "Text search query matching product name, brand, or flavor",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "featured",
            "in": "query",
            "description": "Filter only featured products",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of products matching search criteria",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": { "type": "string" },
                          "name": { "type": "string" },
                          "slug": { "type": "string" },
                          "brandName": { "type": "string" },
                          "categoryId": { "type": "string" },
                          "categoryName": { "type": "string" },
                          "description": { "type": "string" },
                          "packSizes": {
                            "type": "array",
                            "items": { "type": "string" }
                          },
                          "badge": { "type": "string" },
                          "isPublished": { "type": "boolean" }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/opportunities": {
      "get": {
        "summary": "Query Distributor Dealership Vacancies",
        "description": "Retrieve active distributor and stockist territory openings across Kerala districts.",
        "operationId": "getOpportunities",
        "parameters": [
          {
            "name": "district",
            "in": "query",
            "description": "Kerala district name (e.g., Ernakulam, Kozhikode, Thrissur, Thiruvananthapuram, Kottayam, Palakkad)",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "query",
            "in": "query",
            "description": "Search query for territory title or category",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of active territory distributor opportunities",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": { "type": "string" },
                          "title": { "type": "string" },
                          "slug": { "type": "string" },
                          "district": { "type": "string" },
                          "territory": { "type": "string" },
                          "status": { "type": "string", "enum": ["open", "reviewing", "closed"] },
                          "investmentRange": { "type": "string" },
                          "description": { "type": "string" }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/requests": {
      "post": {
        "summary": "Submit Trade / Wholesale Request",
        "description": "Submit a wholesale bulk inquiry, rate sheet request, or sample request for retail stores, supermarkets, or institutional canteens.",
        "operationId": "submitRequest",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["requestType", "fullName", "email", "phone", "privacyAccepted"],
                "properties": {
                  "requestType": {
                    "type": "string",
                    "enum": ["wholesale_bulk", "rate_sheet", "sample_request", "general_enquiry"]
                  },
                  "fullName": { "type": "string" },
                  "businessName": { "type": "string" },
                  "businessType": { "type": "string" },
                  "email": { "type": "string", "format": "email" },
                  "phone": { "type": "string" },
                  "location": { "type": "string" },
                  "productOrCategoryOfInterest": { "type": "string" },
                  "message": { "type": "string" },
                  "privacyAccepted": { "type": "boolean" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Enquiry successfully recorded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "referenceNumber": { "type": "string" },
                    "message": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/proposals": {
      "post": {
        "summary": "Submit Commercial Partnership Proposal",
        "description": "Submit a supplier proposal (for food manufacturers) or distributor proposal (for regional stockists) to partner with Jessico Foods & Beverages.",
        "operationId": "submitProposal",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["proposalType", "companyName", "contactPerson", "email", "phone", "privacyAccepted"],
                "properties": {
                  "proposalType": {
                    "type": "string",
                    "enum": ["supplier", "distributor"]
                  },
                  "companyName": { "type": "string" },
                  "contactPerson": { "type": "string" },
                  "email": { "type": "string", "format": "email" },
                  "phone": { "type": "string" },
                  "territoryOrLocation": { "type": "string" },
                  "categoriesOfInterest": { "type": "string" },
                  "supplyOrExperience": { "type": "string" },
                  "annualTurnover": { "type": "string" },
                  "message": { "type": "string" },
                  "privacyAccepted": { "type": "boolean" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Proposal successfully recorded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "referenceNumber": { "type": "string" },
                    "message": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
