{
  "openapi": "3.0.3",
  "info": {
    "title": "RM NCC - Rome Private Transfers API",
    "description": "Book private NCC transfers in Rome and across Italy. Search destinations, get quotes, create provisional bookings via AI agents. Privacy: https://rmncc.com/legal/privacy/",
    "version": "1.0.0",
    "contact": {
      "email": "info@rmncc.com",
      "name": "RM NCC"
    }
  },
  "servers": [
    { "url": "https://rmncc.com", "description": "Production" }
  ],
  "tags": [
    { "name": "AI", "description": "AI agent endpoints" },
    { "name": "Booking", "description": "Booking creation" },
    { "name": "Pricing", "description": "Pricing and destinations" }
  ],
  "paths": {
    "/booking/api/prices.php": {
      "get": {
        "operationId": "getPrices",
        "summary": "Get all pricing information",
        "description": "Returns fixed prices for Rome local routes and per-km rates for all Italian city destinations. Includes extras pricing (child seats, night surcharge, round trip).",
        "responses": {
          "200": {
            "description": "Pricing data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "service": { "type": "string" },
                    "currency": { "type": "string" },
                    "fixed_prices": { "type": "object", "properties": { "routes": { "type": "array" } } },
                    "distance_pricing": { "type": "object", "properties": { "rates": { "type": "object" }, "cities": { "type": "array" } } },
                    "extras": { "type": "object" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/booking/api/manage.php": {
      "post": {
        "operationId": "manageBooking",
        "summary": "Modify or cancel a booking",
        "description": "Modify or cancel an existing booking. Only cash bookings can be modified/cancelled via API. Online payments (Revolut, Stripe, PayPal) require contacting support.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["booking_id", "action", "email"],
                "properties": {
                  "booking_id": { "type": "integer", "description": "Booking ID number", "example": 111143 },
                  "action": { "type": "string", "enum": ["cancel", "modify"], "description": "cancel or modify", "example": "cancel" },
                  "email": { "type": "string", "format": "email", "description": "Email used in the booking" },
                  "date": { "type": "string", "description": "New date (for modify)", "example": "21/05/2026" },
                  "time": { "type": "string", "description": "New time (for modify)", "example": "10:00" },
                  "from": { "type": "string", "description": "New pickup (for modify)" },
                  "to": { "type": "string", "description": "New destination (for modify)" },
                  "passengers": { "type": "integer", "description": "New passenger count (for modify)" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Action completed" },
          "403": { "description": "Online payment - must contact support" },
          "404": { "description": "Booking not found" }
        }
      }
    },
    "/booking/api/destinations.php": {
      "get": {
        "operationId": "getDestinations",
        "summary": "List all available destinations",
        "description": "Returns local pickup points and all 64 Italian city destinations available for transfers.",
        "responses": {
          "200": {
            "description": "Destinations list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "local": {
                      "type": "array",
                      "items": { "type": "string" },
                      "description": "Local pickup/dropoff points in Rome"
                    },
                    "cities": {
                      "type": "array",
                      "items": { "type": "string" },
                      "description": "Italian city destinations"
      }
    },
    "/booking/api/ai/autonomous.php": {
      "post": {
        "operationId": "createAutonomousBooking",
        "summary": "Autonomous AI booking — single call",
        "description": "Create a complete booking in one API call. Designed for AI agents. Accepts all passenger data, validates, calculates price, inserts into DB, and sends confirmation email. Returns booking details including ID, key, and confirmation URL.",
        "tags": ["AI", "Booking"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["date", "time", "from", "to", "passengers", "first_name", "last_name", "email", "phone", "payment_method"],
                "properties": {
                  "date": { "type": "string", "description": "DD/MM/YYYY", "example": "20/07/2026" },
                  "time": { "type": "string", "description": "HH:MM (24h)", "example": "09:00" },
                  "from": { "type": "string", "description": "Pickup location (English name)", "example": "Rome" },
                  "to": { "type": "string", "description": "Destination (English name)", "example": "Fiumicino Airport (FCO)" },
                  "passengers": { "type": "integer", "example": 2 },
                  "vehicle": { "type": "string", "enum": ["sedan", "van"], "default": "sedan" },
                  "round_trip": { "type": "integer", "description": "1=yes, 0=no", "example": 0 },
                  "small_luggage": { "type": "integer", "default": 0 },
                  "medium_luggage": { "type": "integer", "default": 0 },
                  "large_luggage": { "type": "integer", "default": 0 },
                  "child_seat": { "type": "integer", "default": 0, "description": "15 EUR each" },
                  "booster_seat": { "type": "integer", "default": 0, "description": "10 EUR each" },
                  "first_name": { "type": "string", "example": "Mario" },
                  "last_name": { "type": "string", "example": "Rossi" },
                  "email": { "type": "string", "format": "email", "example": "mario@example.com" },
                  "phone": { "type": "string", "description": "International format", "example": "+44123456789" },
                  "payment_method": { "type": "string", "enum": ["cash", "revolut"], "description": "cash or revolut", "example": "cash" },
                  "pickup_address": { "type": "string", "description": "Full street address for pickup" },
                  "dropoff_address": { "type": "string" },
                  "fts_number": { "type": "string", "description": "Flight/train/ship number if from airport/station/port" },
                  "notes": { "type": "string", "description": "Notes for the chauffeur" }
                }
              },
              "example": {
                "date": "20/07/2026",
                "time": "09:00",
                "from": "Rome",
                "to": "Fiumicino Airport (FCO)",
                "passengers": 2,
                "vehicle": "sedan",
                "round_trip": 0,
                "small_luggage": 1,
                "medium_luggage": 1,
                "large_luggage": 0,
                "first_name": "Mario",
                "last_name": "Rossi",
                "email": "mario@example.com",
                "phone": "+44123456789",
                "payment_method": "cash"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Booking created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "booking_id": { "type": "integer" },
                    "booking_key": { "type": "string" },
                    "route": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" } } },
                    "date": { "type": "string" },
                    "time": { "type": "string" },
                    "passengers": { "type": "integer" },
                    "price": { "type": "number" },
                    "total_price": { "type": "number" },
                    "currency": { "type": "string" },
                    "payment_method": { "type": "string" },
                    "confirmation_url": { "type": "string" },
                    "checkin_url": { "type": "string", "nullable": true },
                    "email_sent": { "type": "boolean" }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "errors": { "type": "array", "items": { "type": "string" } }
                  }
                }
              }
            }
          }
        }
      }
    }
                }
              }
            }
          }
        }
      }
    },
    "/booking/php-trip.php": {
      "post": {
        "operationId": "getQuote",
        "summary": "Get a price quote for a transfer",
        "description": "Calculate the price for a private NCC transfer between two locations. Supports both fixed-rate (local) and distance-based pricing.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["date", "time", "from", "to", "passengers"],
                "properties": {
                  "date": { "type": "string", "description": "Date in DD/MM/YYYY format", "example": "20/05/2026" },
                  "time": { "type": "string", "description": "Time in HH:MM 24h format", "example": "09:00" },
                  "from": { "type": "string", "description": "Pickup location", "example": "Rome" },
                  "to": { "type": "string", "description": "Destination", "example": "Fiumicino Airport (FCO)" },
                  "passengers": { "type": "integer", "description": "Number of passengers (1-50)", "example": 2 },
                  "small_luggage": { "type": "integer", "description": "Small bags (backpack size)", "example": 1 },
                  "medium_luggage": { "type": "integer", "description": "Medium bags (cabin trolley)", "example": 1 },
                  "large_luggage": { "type": "integer", "description": "Large suitcases", "example": 0 },
                  "round_trip": { "type": "integer", "description": "1 for round trip, 0 for one-way", "example": 0 },
                  "action": { "type": "string", "description": "flat or distance", "example": "flat" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Price quote",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "rate": { "type": "string" },
                    "route": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" } } },
                    "price_sedan": { "type": "number" },
                    "price_van": { "type": "number" },
                    "currency": { "type": "string" },
                    "next_step": { "type": "string", "description": "URL to continue booking" }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "string" } } } } } }
          }
        }
      }
    },
    "/booking/api/ai/chat.php": {
      "post": {
        "operationId": "chatBooking",
        "summary": "AI-powered booking assistant",
        "description": "Conversational booking endpoint powered by DeepSeek AI. Send a message and the assistant will guide through the booking process step by step.",
        "tags": ["AI", "Booking"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["message"],
                "properties": {
                  "message": { "type": "string", "description": "User message", "example": "I want to book a transfer from Rome to FCO" },
                  "history": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "role": { "type": "string", "enum": ["user", "assistant"] },
                        "content": { "type": "string" }
                      }
                    },
                    "description": "Conversation history for context"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "AI response with optional booking data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "reply": { "type": "string", "description": "AI text response" },
                    "element": { "type": "string", "description": "Form element to display" },
                    "booking": { "type": "object", "description": "Extracted booking data when ready" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/booking/api/ai/autonomous.php": {
      "post": {
        "operationId": "createProvisionalBooking",
        "summary": "Autonomous AI booking - single call",
        "description": "Create a complete private transfer booking in one API call. Designed for AI agents. Validates, calculates price, creates booking, sends confirmation email. payment_method defaults to 'pending'. Privacy: https://rmncc.com/legal/privacy/",
        "tags": ["AI", "Booking"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["date", "time", "from", "to", "passengers", "first_name", "last_name", "email", "phone"],
                "properties": {
                  "date": { "type": "string", "description": "DD/MM/YYYY", "example": "20/07/2026" },
                  "time": { "type": "string", "description": "HH:MM (24h)", "example": "09:00" },
                  "from": { "type": "string", "description": "Pickup location", "example": "Rome" },
                  "to": { "type": "string", "description": "Destination", "example": "Fiumicino Airport (FCO)" },
                  "passengers": { "type": "integer", "example": 2 },
                  "vehicle": { "type": "string", "enum": ["sedan", "van"], "default": "sedan" },
                  "round_trip": { "type": "integer", "description": "1=yes, 0=no", "example": 0 },
                  "small_luggage": { "type": "integer", "default": 0 },
                  "medium_luggage": { "type": "integer", "default": 0 },
                  "large_luggage": { "type": "integer", "default": 0 },
                  "first_name": { "type": "string", "example": "Mario" },
                  "last_name": { "type": "string", "example": "Rossi" },
                  "email": { "type": "string", "format": "email", "example": "mario@example.com" },
                  "phone": { "type": "string", "description": "International format", "example": "+44123456789" },
                  "payment_method": { "type": "string", "enum": ["cash", "revolut", "pending"], "default": "pending", "description": "cash, revolut, or pending" },
                  "agree_terms": { "type": "boolean", "description": "User must accept terms", "example": true },
                  "pickup_address": { "type": "string" },
                  "dropoff_address": { "type": "string" },
                  "notes": { "type": "string" }
                }
              },
              "example": {
                "date": "20/07/2026",
                "time": "09:00",
                "from": "Rome",
                "to": "Fiumicino Airport (FCO)",
                "passengers": 2,
                "vehicle": "sedan",
                "first_name": "Mario",
                "last_name": "Rossi",
                "email": "mario@example.com",
                "phone": "+44123456789",
                "payment_method": "pending"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Booking created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "booking_id": { "type": "integer" },
                    "booking_key": { "type": "string" },
                    "route": { "type": "object" },
                    "price": { "type": "number" },
                    "total_price": { "type": "number" },
                    "currency": { "type": "string" },
                    "payment_method": { "type": "string" },
                    "confirmation_url": { "type": "string" },
                    "email_sent": { "type": "boolean" }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "string" } } } } } }
          }
        }
      }
    },
    "/booking/api/ai/": {
      "post": {
        "operationId": "createBooking",
        "summary": "Create a new booking",
        "description": "Create a complete private transfer booking with passenger details. A confirmation email will be sent to the customer. Requires user consent via agree_terms.",
        "tags": ["Booking"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["date", "time", "from", "to", "passengers", "email", "agree_terms"],
                "properties": {
                  "date": { "type": "string", "example": "20/05/2026" },
                  "time": { "type": "string", "example": "09:00" },
                  "from": { "type": "string", "example": "Rome" },
                  "to": { "type": "string", "example": "Fiumicino Airport (FCO)" },
                  "passengers": { "type": "integer", "example": 2 },
                  "vehicle": { "type": "string", "enum": ["sedan", "van"], "example": "sedan" },
                  "small_luggage": { "type": "integer", "example": 1 },
                  "medium_luggage": { "type": "integer", "example": 1 },
                  "large_luggage": { "type": "integer", "example": 0 },
                  "round_trip": { "type": "integer", "example": 0 },
                  "first_name": { "type": "string", "example": "Mario" },
                  "last_name": { "type": "string", "example": "Rossi" },
                  "email": { "type": "string", "format": "email" },
                  "phone": { "type": "string", "example": "+39 123 456 7890" },
                  "payment_method": { "type": "string", "enum": ["cash"], "example": "cash" },
                  "agree_terms": { "type": "boolean", "example": true }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Booking created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "booking_id": { "type": "integer" },
                    "route": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" } } },
                    "price": { "type": "number" },
                    "total": { "type": "number" },
                    "currency": { "type": "string" },
                    "confirmation_url": { "type": "string" },
                    "email_sent": { "type": "boolean" },
                    "message": { "type": "string" }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "string" } } } } }
          }
        }
      }
    }
  }
}