{
  "openapi": "3.1.0",
  "info": {
    "title": "Bangkok Blazers booking API",
    "version": "1.0.0",
    "description": "Scooter rental in Bangkok. Read fleet and prices, check availability, get a quote and create a booking. A booking is confirmed when the customer pays the online prepayment at payment_url (card or PromptPay). Prices in THB, dates are Bangkok local dates (YYYY-MM-DD)."
  },
  "servers": [{ "url": "https://www.bangkokblazers.com/api" }],
  "paths": {
    "/config": {
      "get": {
        "operationId": "getConfig",
        "summary": "Fleet, prices and booking settings",
        "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Config" } } } } }
      }
    },
    "/availability": {
      "get": {
        "operationId": "getAvailability",
        "summary": "Free units per scooter and day",
        "parameters": [
          { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } },
          { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }
        ],
        "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {
          "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" },
          "free": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "integer" } }, "description": "scooter_id -> date -> free units" } } } } } } }
      }
    },
    "/quote": {
      "get": {
        "operationId": "getQuote",
        "summary": "Price and availability for one scooter and date range",
        "parameters": [
          { "name": "scooter_id", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "start_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } },
          { "name": "end_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } },
          { "name": "delivery", "in": "query", "schema": { "type": "integer", "enum": [0, 1, 2] }, "description": "0 shop pickup, 1 free delivery zone, 2 outside zone" },
          { "name": "protection", "in": "query", "schema": { "type": "integer", "enum": [0, 1] } }
        ],
        "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" } } } }, "400": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/bookings": {
      "post": {
        "operationId": "createBooking",
        "summary": "Book a scooter",
        "description": "Only call after the customer confirmed scooter, dates and price, holds a valid motorcycle licence and accepts the rental terms. Returns payment_url; the scooter is held for 30 minutes until paid.",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingRequest" } } } },
        "responses": {
          "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingCreated" } } } },
          "400": { "$ref": "#/components/responses/Error" },
          "409": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/bookings/status": {
      "get": {
        "operationId": "getBookingStatus",
        "summary": "Status of a booking",
        "parameters": [
          { "name": "ref", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "t", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Booking token from createBooking" }
        ],
        "responses": { "200": { "description": "OK" }, "404": { "$ref": "#/components/responses/Error" } }
      }
    }
  },
  "components": {
    "responses": { "Error": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } },
    "schemas": {
      "Scooter": { "type": "object", "properties": {
        "id": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string" }, "cc": { "type": "integer" },
        "features": { "type": "array", "items": { "type": "string" } }, "price_day": { "type": "integer" }, "price_week": { "type": "integer" },
        "price_month": { "type": "integer", "description": "Price for 28 days" }, "security_deposit": { "type": "integer" }, "units": { "type": "integer" } } },
      "Config": { "type": "object", "properties": { "scooters": { "type": "array", "items": { "$ref": "#/components/schemas/Scooter" } }, "settings": { "type": "object" }, "today": { "type": "string" } } },
      "Quote": { "type": "object", "properties": {
        "scooter_id": { "type": "string" }, "available": { "type": "boolean" }, "units_free": { "type": "integer" }, "days": { "type": "integer" },
        "rental": { "type": "integer" }, "delivery_fee": { "type": "integer" }, "protection_fee": { "type": "integer" }, "total": { "type": "integer" },
        "pay_now_online": { "type": "integer" }, "pay_at_pickup": { "type": "integer" }, "security_deposit_at_pickup": { "type": "integer" }, "currency": { "type": "string" } } },
      "BookingRequest": { "type": "object", "required": ["scooter_id", "start_date", "end_date", "name", "email", "phone", "licence_ok", "accept_terms"], "properties": {
        "scooter_id": { "type": "string" }, "start_date": { "type": "string", "format": "date" }, "end_date": { "type": "string", "format": "date" },
        "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string", "pattern": "^\\+[1-9][0-9]{7,14}$", "description": "WhatsApp number with + and country code" }, "whatsapp_ok": { "type": "boolean" }, "lang": { "type": "string", "enum": ["en", "de", "th", "fr", "es", "ru", "zh", "ko", "ja"] },
        "delivery": { "type": "integer", "enum": [0, 1, 2] }, "hotel": { "type": "string" }, "protection": { "type": "boolean" }, "notes": { "type": "string" },
        "licence_ok": { "type": "boolean", "const": true }, "accept_terms": { "type": "boolean", "const": true } } },
      "BookingCreated": { "type": "object", "properties": {
        "ref": { "type": "string" }, "token": { "type": "string" }, "status": { "type": "string", "enum": ["pending", "confirmed"] },
        "payment_url": { "type": ["string", "null"] }, "status_url": { "type": "string" }, "hold_expires_at": { "type": ["string", "null"] },
        "total": { "type": "integer" }, "pay_now": { "type": "integer" }, "pay_at_pickup": { "type": "integer" }, "security_deposit": { "type": "integer" }, "currency": { "type": "string" } } }
    }
  }
}
