{
  "openapi": "3.1.0",
  "info": {
    "title": "JTCabs quote request",
    "version": "1.0.0",
    "description": "Submit a Coimbatore round-trip EV quote request for a customer. Quote only. The fare is metered from actual km and time. Toll, permit and parking at actual. Nothing to pay now. Round-trip outstation only. GET /api/booking does not create a lead. GET /api/booking-request does, after the customer agrees. HEAD and prefetch do not."
  },
  "servers": [
    {
      "url": "https://jtcabs.com"
    }
  ],
  "paths": {
    "/api/booking": {
      "post": {
        "operationId": "submitBooking",
        "summary": "Submit a round-trip quote request (legacy JSON)",
        "description": "Stores the enquiry and alerts dispatch. This is the on-site and legacy JSON path. name, phone, dateText, and locationText are required. Returns success true when the row is stored, even if the Telegram alert still failed. This is a reservation request, not a confirmed trip. Nothing to pay now. The team calls or WhatsApps to plan the details. Put the pickup time in dateText, for example 7 Nov 2026, 5:00 AM pickup.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": ["name", "phone", "dateText", "locationText"],
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 2,
                    "maxLength": 80,
                    "description": "The customer's name."
                  },
                  "phone": {
                    "type": "string",
                    "description": "The customer's 10-digit Indian mobile. Digits only, or with +91."
                  },
                  "email": {
                    "type": "string",
                    "description": "Optional. Send an empty string when unknown."
                  },
                  "dateText": {
                    "type": "string",
                    "description": "Travel date plus pickup time. Example: 7 Nov 2026, 5:00 AM pickup. For a later return: 7 Nov 2026 (Return: 8 Nov 2026), 5:00 AM pickup."
                  },
                  "locationText": {
                    "type": "string",
                    "description": "Trip line. Start with Coimbatore and the destination, then the pickup area. Example: Coimbatore to Palani, pickup Peelamedu, round trip, same-day return."
                  }
                }
              },
              "example": {
                "name": "Customer name",
                "phone": "9876543210",
                "email": "",
                "dateText": "7 Nov 2026, 5:00 AM pickup",
                "locationText": "Coimbatore to Palani. Pickup: Peelamedu. Round trip. Same-day return."
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The quote request was stored.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": ["success"],
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [true]
                    },
                    "leadId": {
                      "type": "string",
                      "description": "Receipt id for this quote request, for example JT-AB12CD34."
                    },
                    "telegramSent": {
                      "type": "boolean",
                      "description": "True when the Telegram desk alert was accepted."
                    },
                    "duplicate": {
                      "type": "boolean",
                      "description": "True when this matched a quote request already stored in the last few minutes. It was not sent again."
                    },
                    "whatsappUrl": {
                      "type": "string",
                      "description": "Present when the desk alert did not go through. Prefilled wa.me link so the customer can still reach the team."
                    }
                  }
                },
                "example": {
                  "success": true,
                  "leadId": "JT-AB12CD34",
                  "telegramSent": true,
                  "duplicate": false
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid fields.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "The quote request was not stored.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/quote": {
      "get": {
        "operationId": "getQuote",
        "summary": "Read a round-trip estimate",
        "description": "Read-only estimate using the same formula as the fare calculator. Distance is the published round trip (each-way kilometres times two). Do not send km. Hills are Ooty, Kodaikanal, Munnar, and Valparai. Each day is one 12-hour block. This does not send a request and it does not create a lead.",
        "security": [],
        "parameters": [
          {
            "name": "destination",
            "in": "query",
            "required": true,
            "schema": { "type": "string" },
            "description": "Route slug, English name, or Tamil name. Case-insensitive for English."
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "schema": { "type": "integer", "minimum": 1, "maximum": 15, "default": 1 },
            "description": "How many 12-hour blocks. Default 1."
          }
        ],
        "responses": {
          "200": {
            "description": "An estimate. Toll, permit, and parking are at actual cost and are not in estimatedTotal.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/QuoteEstimate" },
                "example": {
                  "destination": "Ooty",
                  "roundTripKm": 172,
                  "days": 1,
                  "hills": true,
                  "estimatedTotal": 4091,
                  "currency": "INR",
                  "note": "Estimate only. Your final fare is worked out at the end of the trip, based on the actual kilometres travelled and time taken.",
                  "requestUrl": "https://jtcabs.com/agents/request?destination=Ooty",
                  "apiForRequest": "/api/booking-request"
                }
              }
            }
          },
          "404": {
            "description": "Unknown destination. No price is returned.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/UnknownDestination" }
              }
            }
          }
        }
      }
    },
    "/api/booking-request": {
      "get": {
        "operationId": "requestQuoteGet",
        "summary": "Send a round-trip quote request by fetching a link",
        "description": "For an assistant that can fetch a URL and cannot POST. Only ask the customer for their phone number and destination, then submit. Do not ask for anything else; the team collects the rest on the call. Write links with plain & separators, not &amp;. Fetch this URL with the phone and destination or trip filled in. Only after the body says Quote request received, tell the customer the team will contact them soon. Never show a booked or confirmed card. Never fetch it without the customer's explicit go-ahead. Get prices only from GET /api/quote. HEAD, and prefetch (Sec-Purpose, Purpose, Next-Router-Prefetch, X-Moz), return 204 and send nothing. The same phone and destination within 30 minutes returns the same leadId and does not alert again. Shortest example: https://jtcabs.com/api/booking-request?phone=9XXXXXXXXX&trip=Coimbatore%20to%20Palani",
        "security": [],
        "parameters": [
          { "name": "phone", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Required. The customer's 10-digit Indian mobile. Digits only, or with +91." },
          { "name": "destination", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Required unless trip is set. A place outside Coimbatore. Round trip only." },
          { "name": "trip", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Free text such as Coimbatore to Palani tomorrow 6 AM. The raw text is stored." },
          { "name": "name", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 60 }, "description": "Optional. The team collects the name on the call when it is missing." },
          { "name": "pickup", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional. Defaults to Coimbatore." },
          { "name": "date", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional. Travel date, for example 7 Nov 2026 or 2026-11-07." },
          { "name": "time", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional. Pickup time, for example 5:00 AM." },
          { "name": "return", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional. same day, or a later return date. Every trip is a round trip." },
          { "name": "notes", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional note for the team." },
          { "name": "dateText", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Legacy travel line. Accepted together with locationText." },
          { "name": "locationText", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Legacy trip line. Accepted together with dateText." },
          { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": ["json", "text", "html"] }, "description": "json returns JSON. Otherwise the body is plain text, or a tiny HTML page when the browser asks for HTML." }
        ],
        "responses": {
          "200": {
            "description": "The quote request was stored. Tell the customer the team will contact them soon.",
            "content": {
              "text/plain": {
                "schema": { "type": "string" },
                "example": "Quote request received. The JTCabs team will call or WhatsApp you to plan the details. Nothing to pay now. The fare stays an estimate until the trip ends."
              },
              "text/html": {
                "schema": { "type": "string" }
              },
              "application/json": {
                "schema": { "$ref": "#/components/schemas/GetRequestReceived" },
                "example": {
                  "status": "request_received",
                  "leadId": "JT-AB12CD34",
                  "message": "Quote request received. The JTCabs team will call or WhatsApp you to plan the details. Nothing to pay now. The fare stays an estimate until the trip ends.",
                  "telegram": "delivered",
                  "duplicate": false
                }
              }
            }
          },
          "204": {
            "description": "HEAD or prefetch. Nothing was sent."
          },
          "400": {
            "description": "Missing or invalid fields. Nothing was sent. The body lists the fields and an example URL.",
            "content": {
              "text/plain": { "schema": { "type": "string" } },
              "application/json": { "schema": { "$ref": "#/components/schemas/GetRequestError" } }
            }
          },
          "429": {
            "description": "Too many requests. Nothing was sent."
          }
        }
      },
      "post": {
        "operationId": "requestQuote",
        "summary": "Plan My Trip",
        "description": "Stores the enquiry and alerts dispatch. Same pipeline as POST /api/booking. This is a quote request. Nothing to pay now. The team calls or WhatsApps to plan the details. Accepts JSON or application/x-www-form-urlencoded with name, phone, pickup, destination, date, time, and return. Legacy dateText and locationText are also accepted.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/BookingRequest" },
              "example": {
                "name": "Customer name",
                "phone": "9876543210",
                "pickup": "Peelamedu",
                "destination": "Palani",
                "date": "9 Nov 2026",
                "time": "5:00 AM",
                "return": "same day"
              }
            },
            "application/x-www-form-urlencoded": {
              "schema": { "$ref": "#/components/schemas/BookingRequest" }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The quote request was stored.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/RequestReceived" },
                "example": {
                  "status": "request_received",
                  "leadId": "JT-AB12CD34",
                  "receiptUrl": "https://jtcabs.com/agents/request/sent?id=signed",
                  "telegram": "delivered",
                  "message": "Quote request received. The JTCabs team will call or WhatsApp you to plan the details. Nothing to pay now. The fare stays an estimate until the trip ends."
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid fields.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          },
          "502": {
            "description": "The quote request was not stored.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "QuoteEstimate": {
        "type": "object",
        "additionalProperties": false,
        "required": ["destination", "roundTripKm", "days", "hills", "lineItems", "estimatedTotal", "currency", "note", "requestUrl", "apiForRequest"],
        "properties": {
          "destination": { "type": "string" },
          "roundTripKm": { "type": "integer" },
          "days": { "type": "integer" },
          "hills": { "type": "boolean" },
          "lineItems": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["line", "amount"],
              "properties": {
                "line": { "type": "string" },
                "amount": { "type": ["integer", "null"] }
              }
            }
          },
          "estimatedTotal": { "type": "integer" },
          "currency": { "type": "string", "enum": ["INR"] },
          "note": { "type": "string" },
          "requestUrl": { "type": "string" },
          "apiForRequest": { "type": "string", "enum": ["/api/booking-request"] }
        }
      },
      "UnknownDestination": {
        "type": "object",
        "additionalProperties": false,
        "required": ["error", "destinations", "advice"],
        "properties": {
          "error": { "type": "string" },
          "destinations": { "type": "array", "items": { "type": "object" } },
          "advice": { "type": "string" }
        }
      },
      "BookingRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": ["phone"],
        "properties": {
          "name": { "type": "string", "description": "Optional." },
          "phone": { "type": "string", "description": "Required. 10-digit Indian mobile." },
          "email": { "type": "string" },
          "pickup": { "type": "string", "description": "Optional. Defaults to Coimbatore." },
          "destination": { "type": "string", "description": "Required unless trip is set." },
          "trip": { "type": "string", "description": "Free text such as Coimbatore to Palani tomorrow 6 AM." },
          "date": { "type": "string", "description": "Optional." },
          "time": { "type": "string", "description": "Optional." },
          "return": { "type": "string", "description": "Optional. same day, or a later return date." },
          "notes": { "type": "string", "description": "Optional." },
          "dateText": { "type": "string", "description": "Legacy. Travel date plus pickup time." },
          "locationText": { "type": "string", "description": "Legacy trip line." }
        }
      },
      "GetRequestReceived": {
        "type": "object",
        "additionalProperties": false,
        "required": ["status", "leadId", "message", "telegram", "duplicate"],
        "properties": {
          "status": { "type": "string", "enum": ["request_received"] },
          "leadId": { "type": "string" },
          "message": { "type": "string" },
          "telegram": { "type": "string", "enum": ["delivered", "failed"] },
          "duplicate": { "type": "boolean" },
          "whatsappFallback": { "type": "string", "description": "Present when telegram is failed." }
        }
      },
      "GetRequestError": {
        "type": "object",
        "additionalProperties": false,
        "required": ["success", "error", "fields", "example"],
        "properties": {
          "success": { "type": "boolean", "enum": [false] },
          "error": { "type": "string" },
          "fields": { "type": "array", "items": { "type": "string" } },
          "example": { "type": "string" }
        }
      },
      "RequestReceived": {
        "type": "object",
        "additionalProperties": false,
        "required": ["status", "leadId", "receiptUrl", "telegram", "message"],
        "properties": {
          "status": { "type": "string", "enum": ["request_received"] },
          "leadId": { "type": "string" },
          "receiptUrl": { "type": "string" },
          "telegram": { "type": "string", "enum": ["delivered", "failed"] },
          "whatsappFallback": { "type": "string", "description": "Present when telegram is failed." },
          "message": { "type": "string" }
        }
      },
      "Error": {
        "type": "object",
        "required": ["success", "error"],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [false]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
