# WhatsApp Bot Backend API Documentation

## Overview

This Node.js Express backend provides comprehensive APIs for managing WhatsApp bot interactions with property management features. The system supports both **existing tenants** and **new leads** with complete data models for properties and tenant management.

## Base URL
```
http://localhost:3001
```

## Live Deployment URLs
- **Production (Vercel)**: `https://quickstay-database-apis.vercel.app`
- **Secondary (Bolt)**: `https://node-js-express-back-dfu9.bolt.host`

## Authentication & User Flow

### User Verification
**Endpoint:** `GET /verify-user/:phoneNumber`

**Purpose:** Check if a phone number exists in the system as a tenant or lead

**Parameters:**
- `phoneNumber` (path): 10-digit phone number or +91 followed by 10 digits

**Response:**
```json
// Existing Tenant
{
  "success": true,
  "data": {
    "status": "tenant",
    "tenantId": "02C0AzygCQ2RqnovIfFC",
    "propertyId": "prop_001",
    "operatorId": "op_001",
    "name": "Jatin",
    "phoneNumber": "7589017493",
    "fullPhoneNumber": "+917589017493",
    "gender": "Male",
    "roomNo": "101",
    "tenantStatus": "Active",
    "address": "",
    "bankName": "",
    "ifscCode": "",
    "typeOfSharing": ""
  },
  "message": "User found as existing tenant"
}

// New Lead
{
  "success": true,
  "data": {
    "status": "lead"
  },
  "message": "User is a new lead"
}
```

---

## Tenant APIs (Existing Users)

### Payment Management

#### Get All Payments
**Endpoint:** `GET /tenants/:tenantId/payments`

**Purpose:** Retrieve all payment records for a tenant

**Query Parameters:**
- `limit` (optional): Number of recent payments to retrieve (default: 10, max: 50)

**Examples:**
```
GET /tenants/tenant123/payments           # Get last 10 payments (default)
GET /tenants/tenant123/payments?limit=15  # Get last 15 payments
GET /tenants/tenant123/payments?limit=5   # Get last 5 payments
```

**Response:**
```json
{
  "success": true,
  "data": [
    {
      "id": "txn123",
      "userName": "John Doe",
      "propertyCode": "PG001",
      "typeOfTransactions": [
        {
          "type": "rent",
          "totalAmount": 15000,
          "paidAmount": 15000,
          "status": "Paid"
        }
      ],
      "dueDate": "2024-01-01T00:00:00Z",
      "paidDate": "2024-01-01T10:30:00Z",
      "status": "Completed",
      "paymentMode": "Online"
    }
  ],
  "message": "Found 15 payment records (last 15)"
}
```

#### Get Transaction Receipt
**Endpoint:** `GET /tenants/:tenantId/receipt/:transactionId`

**Purpose:** Get detailed receipt for a specific transaction

**Response:**
```json
{
  "success": true,
  "data": {
    "id": "txn123",
    "userName": "John Doe",
    "propertyName": "Green Valley PG",
    "typeOfTransactions": [
      {
        "type": "rent",
        "totalAmount": 15000,
        "paidAmount": 15000,
        "status": "Paid"
      }
    ],
    "paidDate": "2024-01-01T10:30:00Z",
    "paymentMode": "Online",
    "receivedBy": "Owner"
  },
  "message": "Transaction receipt retrieved successfully"
}
```

### Complaint Management

#### Create Complaint
**Endpoint:** `POST /tenants/:tenantId/complaints`

**Purpose:** Allow tenants to raise complaints

**Request Body:**
```json
{
  "complaintType": "maintenance",
  "complaintSubtype": "ac_repair",
  "description": "AC not working properly, making noise",
  "priority": 2
}
```

**Response:**
```json
{
  "success": true,
  "data": {
    "complaintId": "comp123",
    "status": "raised",
    "complaintType": "maintenance",
    "timestamp": "2024-01-15T10:00:00Z"
  },
  "message": "Complaint submitted successfully"
}
```

#### Get All Complaints
**Endpoint:** `GET /tenants/:tenantId/complaints`

**Purpose:** Get all complaints raised by the tenant

**Query Parameters:**
- `limit` (optional): Number of recent complaints to retrieve (default: 10, max: 50)

**Examples:**
```
GET /tenants/tenant123/complaints           # Get last 10 complaints (default)
GET /tenants/tenant123/complaints?limit=15  # Get last 15 complaints
GET /tenants/tenant123/complaints?limit=20  # Get last 20 complaints
```

**Response:**
```json
{
  "success": true,
  "data": [
    {
      "complaintId": "comp123",
      "complaintType": "maintenance",
      "complaintSubtype": "ac_repair",
      "status": "in-progress",
      "timestamp": "2024-01-15T10:00:00Z"
    }
  ],
  "message": "Found 10 complaints (last 10)"
}
```

#### Check Complaint Status
**Endpoint:** `GET /tenants/:tenantId/complaints/:complaintId/status`

**Purpose:** Check detailed status of a specific complaint

**Response:**
```json
{
  "success": true,
  "data": {
    "complaintId": "comp123",
    "status": "in-progress",
    "complaintType": "maintenance",
    "complaintSubtype": "ac_repair",
    "description": "AC not working properly",
    "steps": [
      {
        "name": "Complaint Raised",
        "description": "AC repair request submitted",
        "dateTime": "2024-01-15T10:00:00Z",
        "status": "completed",
        "priority": 2
      },
      {
        "name": "Technician Assigned",
        "description": "John assigned to fix AC",
        "dateTime": "2024-01-15T14:00:00Z",
        "status": "in-progress",
        "priority": 2
      }
    ],
    "createdAt": "2024-01-15T10:00:00Z",
    "lastUpdated": "2024-01-15T14:00:00Z"
  },
  "message": "Complaint status retrieved successfully"
}
```

#### Add Complaint Update (Step)
**Endpoint:** `POST /ai/complaint/:complaintId/step`

**Purpose:** Add a text or photo update to an existing complaint

**Request Body:**
```json
{
  "tenantId": "tenant123",
  "stepName": "Tenant provided photo",
  "description": "Photo of AC problem",
  "photoUrl": "https://example.com/photo.jpg"
}
```

**Response:**
```json
{
  "success": true,
  "data": {
    "complaintId": "comp123",
    "stepAdded": true,
    "stepName": "Tenant provided photo"
  },
  "message": "Update added to complaint successfully"
}
```

#### Mark Complaint as Resolved
**Endpoint:** `POST /ai/complaint/:complaintId/resolve`

**Purpose:** Mark a complaint as resolved by the tenant

**Request Body:**
```json
{
  "tenantId": "tenant123"
}
```

**Response:**
```json
{
  "success": true,
  "data": {
    "complaintId": "comp123",
    "status": "Resolved",
    "resolvedAt": "2024-01-16T10:00:00Z"
  },
  "message": "Complaint marked as resolved"
}
```

### Notice Management

#### Submit Notice
**Endpoint:** `POST /tenants/:tenantId/notices`

**Purpose:** Submit tenant notices (move-out, general, maintenance)

**Request Body:**
```json
{
  "type": "move-out",
  "noticeReason": "Job relocation",
  "moveOutDate": "2024-03-01T00:00:00Z",
  "bankDetails": {
    "accountNumber": "1234567890",
    "ifscCode": "HDFC0001234",
    "accountHolderName": "John Doe"
  }
}
```

**Response:**
```json
{
  "success": true,
  "data": {
    "noticeId": "notice123",
    "status": "submitted",
    "type": "move-out",
    "timestamp": "2024-01-15T10:00:00Z"
  },
  "message": "Notice submitted successfully"
}
```

#### Get All Notices
**Endpoint:** `GET /tenants/:tenantId/notices`

**Purpose:** Get all notices submitted by the tenant

**Response:**
```json
{
  "success": true,
  "data": [
    {
      "noticeId": "notice123",
      "type": "move-out",
      "status": "approved",
      "timestamp": "2024-01-15T10:00:00Z",
      "moveOutDate": "2024-03-01T00:00:00Z"
    }
  ],
  "message": "Found 1 notices"
}
```

#### Check Notice Status
**Endpoint:** `GET /tenants/:tenantId/notices/:noticeId/status`

**Purpose:** Check detailed status of a specific notice

**Response:**
```json
{
  "success": true,
  "data": {
    "noticeId": "notice123",
    "status": "approved",
    "noticeReason": "Job relocation",
    "moveInDate": "2023-06-01T00:00:00Z",
    "moveOutDate": "2024-03-01T00:00:00Z",
    "responseDate": "2024-01-16T09:00:00Z",
    "createdAt": "2024-01-15T10:00:00Z",
    "bankDetails": {
      "accountNumber": "1234567890",
      "ifscCode": "HDFC0001234",
      "accountHolderName": "John Doe"
    },
    "ratings": {
      "property": 4,
      "service": 5
    }
  },
  "message": "Notice status retrieved successfully"
}
```

### Information APIs

#### Get Tenant Information
**Endpoint:** `GET /tenants/:tenantId/info`

**Purpose:** Get complete tenant information with all details

**Response:**
```json
{
  "success": true,
  "data": {
    "id": "tenant123",
    "operatorId": "QSGM7393939",
    "tenantFullName": "John Doe",
    "tenantPhoneNo": "9876543210",
    "tenantGender": "Male",
    "occupation": "Software Engineer",
    "propertyDetails": {
      "propertyId": "prop123",
      "propertyCode": "PG001",
      "propertyName": "Green Valley PG",
      "propertyImage": "https://...",
      "propertyAddress": "123 Main St, Gurgaon",
      "propertyLocationUrl": "https://maps.google.com/...",
      "propertyOwnerNumber": "9876543210",
      "brandName": "QuickStay"
    },
    "agreementDetails": {
      "rentalType": "Monthly",
      "monthlyRent": 15000,
      "securityDeposit": 15000,
      "maintenance": 2000,
      "agreementStartDate": "2024-01-01T00:00:00Z",
      "agreementDuration": "11 Months",
      "lockInPeriod": "6 Months",
      "noticePeriod": "1 Month",
      "gracePeriodInDays": 5
    },
    "hasPaidToken": true,
    "amountToken": 5000,
    "onlyCashPayment": false,
    "room": {
      "id": "room001",
      "totalBed": 1,
      "type": "Private",
      "typeNo": 1,
      "unitTypes": ["1RK"],
      "amount": 15000,
      "features": ["AC", "Attached Bathroom"],
      "isShow": true
    },
    "typeOfSharing": "Single",
    "moveOutDate": null,
    "email": "john@example.com",
    "birthdate": "1995-01-01T00:00:00Z",
    "roomNo": "101",
    "fullAddress": "123 Home St, Delhi",
    "city": "Delhi",
    "state": "Delhi",
    "professionalDetails": {
      "profession": "Software Engineer",
      "designation": "Senior Developer",
      "officeName": "Tech Corp",
      "city": "Gurgaon",
      "state": "Haryana"
    },
    "emergencyDetails": {
      "contactPerson": "Jane Doe",
      "relationship": "Sister",
      "mobileNo": "9876543211",
      "address": "456 Emergency St",
      "city": "Delhi",
      "state": "Delhi"
    },
    "tenantBankDetails": {
      "id": "bank001",
      "bankName": "HDFC Bank",
      "accountNumber": "1234567890",
      "accountHolderName": "John Doe",
      "ifscCode": "HDFC0001234",
      "address": "Bank Address"
    },
    "tenantDocuments": {
      "aadharXmlBase64Url": "",
      "agreementPdfUrl": "https://...",
      "passportPhoto": "https://...",
      "aadharFrontSideUrl": "https://...",
      "aadharBacksideUrl": "https://...",
      "pancardUrl": "https://..."
    },
    "tenantStatus": "Active",
    "pendingCharges": [
      {
        "id": "charge001",
        "type": "Electricity",
        "amount": 500,
        "description": "Monthly electricity bill",
        "isPaid": false,
        "timestamp": "2024-01-15T00:00:00Z"
      }
    ],
    "couponDetail": {
      "name": "Welcome Discount",
      "description": "First month discount",
      "couponCode": "WELCOME10",
      "discountInPercentage": true,
      "discount": 10
    },
    "referralDetails": {
      "referralCode": "REF123",
      "discount": 1000
    },
    "fcmToken": "fcm_token_here",
    "prepaidElectricMeter": false,
    "quickCash": 0,
    "quickCashDetails": [],
    "otherChargesList": [],
    "referralTransaction": [],
    "timestamp": "2024-01-01T00:00:00Z",
    "bookingId": "BOOK123",
    "onNoticePeriod": false,
    "isOnboardingComplete": true,
    "roommates": [
      {
        "name": "Mike Smith",
        "phoneNumber": "9876543212",
        "email": "mike@example.com",
        "gender": "Male",
        "aadhaarCardFrontUrl": "https://...",
        "aadhaarCardBackUrl": "https://...",
        "isVerified": true,
        "timestamp": "2024-01-01T00:00:00Z",
        "id": "roommate001",
        "moveOutDate": null,
        "isAppAccess": false,
        "dateOfBirth": "1996-01-01T00:00:00Z",
        "status": "Active"
      }
    ]
  },
  "message": "Tenant information retrieved successfully"
}
```

#### Get Property Details (Tenant View)
**Endpoint:** `GET /tenants/:tenantId/property/:propertyId/details`

**Purpose:** Get detailed property information for current tenant

**Response:**
```json
{
  "success": true,
  "data": {
    "propertyId": "prop123",
    "propertyCode": "PG001",
    "propertyName": "Green Valley PG",
    "propertyDescription": "Modern PG with all amenities",
    "propertyFullAddress": "123 Main St, Sector 14, Gurgaon",
    "propertyCity": "Gurgaon",
    "propertyState": "Haryana",
    "propertyPincode": "122002",
    "totalBeds": 50,
    "vacantBeds": 5,
    "propertyImages": [
      {
        "imageUrl": "https://...",
        "imageType": "cover",
        "isCover": true
      }
    ],
    "propertyAmenities": ["WiFi", "AC", "Laundry"],
    "propertyFacilities": ["Gym", "Common Area"],
    "primeFacilities": ["24/7 Security"],
    "roomOptions": [
      {
        "id": "room001",
        "totalBed": 1,
        "type": "Private",
        "typeNo": 1,
        "unitTypes": ["1RK"],
        "amount": 15000,
        "features": ["AC", "Attached Bathroom"],
        "isShow": true
      }
    ],
    "securityDeposit": "1 Month",
    "agreementDuration": "11 Month",
    "lockInPeriod": "6 Month",
    "noticePeriod": "1 Month",
    "whoCanStay": ["Male", "Female"],
    "bestSuitedFor": ["Working Professional", "Students"],
    "houseRules": ["No smoking", "No pets"],
    "token": 5000,
    "propertyLocationUrl": "https://maps.google.com/...",
    "ownerMobileNumber": "9876543210",
    "totalFloor": 3,
    "startFromGround": 1,
    "operatorId": "QSGM7393939"
  },
  "message": "Property details retrieved successfully"
}
```

---

## Data Models

### Complete Property Model Fields:

**Basic Information:**
- `propertyId`, `propertyCode`, `propertyName`, `propertyDescription`
- `propertyFullAddress`, `propertyCity`, `propertyState`, `propertyPincode`
- `propertyStreetSocietyName`, `propertyHounseNo`, `propertyLocality`
- `operatorId`, `propertyStatus`, `isActive`, `views`, `timestamp`

**Media & Features:**
- `propertyImages` (PropertyImageModel array with imageUrl, imageType, isCover)
- `servicesFeature`, `roomAmenities`, `propertyAmenities`
- `propertyFacilities`, `primeFacilities`, `houseRules`

**Capacity & Structure:**
- `totalBeds`, `vacantBeds`, `totalRooms`, `totalFloor`, `startFromGround`
- `furnishedStatus`, `unitTypes`, `whoCanStay`, `bestSuitedFor`

**Room Options:**
- `roomOptions` (RoomOption array with id, totalBed, type, typeNo, unitTypes, amount, features, isShow)

**Terms & Pricing:**
- `securityDeposit`, `agreementDuration`, `lockInPeriod`, `noticePeriod`
- `rentMonthlyCycle`, `gracePeriod`, `token`
- `isLateFine`, `lateFineAmount`, `anyExtraCharges`
- `otherChargesList` (OtherCharges array)

**Contact & Location:**
- `propertyLocationUrl`, `landmarks`, `ownerMobileNumber`
- `representative` (Representative object with name, phoneNo, email, etc.)

**Additional Features:**
- `wifiList`, `addOnModules`, `propertyVerification`
- `createdAt`, `updatedAt`

### Complete Tenant Model Fields:

**Basic Information:**
- `id`, `operatorId`, `tenantFullName`, `tenantPhoneNo`, `tenantGender`
- `occupation`, `email`, `birthdate`, `roomNo`, `fullAddress`, `city`, `state`
- `tenantStatus`, `bookingId`, `timestamp`

**Property & Agreement:**
- `propertyDetails` (PropertyDetails object)
- `agreementDetails` (AgreementModel object)
- `room` (RoomOption object)
- `typeOfSharing`, `moveOutDate`

**Financial Information:**
- `hasPaidToken`, `amountToken`, `onlyCashPayment`
- `pendingCharges` (PendingCharges array)
- `couponDetail`, `referralDetails`, `referralTransaction`
- `quickCash`, `quickCashDetails`, `otherChargesList`

**Personal Details:**
- `professionalDetails` (ProfessionalDetails object)
- `emergencyDetails` (EmergencyDetails object)
- `tenantBankDetails` (TenantBankDetails object)
- `tenantDocuments` (TenantDocument object)

**Status & Settings:**
- `onNoticePeriod`, `isOnboardingComplete`, `fcmToken`
- `prepaidElectricMeter`

**Roommates:**
- `roommates` (Roommate array with complete details)

---

## Updated API Endpoints Summary

### Property APIs:
- `GET /properties` - Get all properties with complete model
- `GET /properties/operator/:operatorId` - **NEW**: Get properties by operator
- `GET /properties/search` - Search properties with advanced filters
- `GET /properties/:propertyId` - Get complete property details

### Tenant APIs:
- `GET /tenants/:tenantId/info` - Get complete tenant information
- `GET /tenants/:tenantId/property/:propertyId/details` - Get property details for tenant
- `GET /tenants/:tenantId/payments` - Get payment history
- `GET /tenants/:tenantId/receipt/:transactionId` - Get transaction receipt
- `POST /tenants/:tenantId/complaints` - Create complaint
- `GET /tenants/:tenantId/complaints` - Get all complaints
- `GET /tenants/:tenantId/complaints/:complaintId/status` - Get complaint status
- `POST /tenants/:tenantId/notices` - Submit notice
- `GET /tenants/:tenantId/notices` - Get all notices
- `GET /tenants/:tenantId/notices/:noticeId/status` - Get notice status

### User Management:
- `GET /verify-user/:phoneNumber` - User verification

### Utility:
- `GET /health` - Health check

---

## Usage Examples

### Get Properties by Operator:
```bash
curl "https://quickstay-database-apis.vercel.app/properties/operator/QSGM7393939"
```

### Get Complete Tenant Info:
```bash
curl "https://quickstay-database-apis.vercel.app/tenants/tenant123/info"
```

### Search Properties with Filters:
```bash
curl "https://quickstay-database-apis.vercel.app/properties/search?city=Gurgaon&minRent=10000&maxRent=20000"
```

## Mock Data for Testing:

### Operator IDs:
- `QSGM7393939` (Sample operator)
- `OP001`, `OP002` (Additional test operators)

### Tenant IDs:
- `02C0AzygCQ2RqnovIfFC` (Jatin's actual Firebase document ID)
- `tenant123`, `tenant456` (Test tenant IDs)

### Property IDs:
- `prop123`, `prop456` (Test property IDs)

This comprehensive API documentation covers all endpoints with complete data models for both properties and tenants, including the new operator-based property filtering endpoint.
    },
    "property": {
      "propertyName": "Green Valley PG",
      "propertyCode": "PG001",
      "propertyFullAddress": "123 Main St, Gurgaon"
    }
  },
  "message": "Tenant information retrieved successfully"
}
```

#### Get Property Details (Tenant View)
**Endpoint:** `GET /tenants/:tenantId/property/:propertyId/details`

**Purpose:** Get detailed property information for current tenant

**Response:**
```json
{
  "success": true,
  "data": {
    "propertyId": "prop123",
    "propertyName": "Green Valley PG",
    "propertyDescription": "Modern PG with all amenities",
    "propertyFullAddress": "123 Main St, Sector 14, Gurgaon",
    "propertyAmenities": ["WiFi", "AC", "Laundry"],
    "propertyFacilities": ["Gym", "Common Area"],
    "roomOptions": [
      {
        "id": "room001",
        "floorNo": 1,
        "roomKey": "101",
        "type": "Private",
        "totalBed": 1,
        "amount": 15000,
        "features": ["AC", "Attached Bathroom"],
        "available": true
      }
    ],
    "securityDeposit": "1 Month",
    "propertyLocationUrl": "https://maps.google.com/...",
    "ownerMobileNumber": "9876543210"
  },
  "message": "Property details retrieved successfully"
}
```

---

## Lead APIs (New Users)

### Property Discovery

#### Get All Properties
**Endpoint:** `GET /properties`

**Purpose:** Get all available properties with pagination

**Query Parameters:**
- `page` (optional): Page number (default: 1)
- `limit` (optional): Items per page (default: 10, max: 50)
- `city` (optional): Filter by city
- `state` (optional): Filter by state
- `operatorId` (optional): Filter by operator

**Example:** `GET /properties?page=1&limit=10`

**Response:**
```json
{
  "success": true,
  "data": {
    "properties": [
      {
        "propertyId": "prop123",
        "propertyCode": "PG001",
        "propertyName": "Green Valley PG",
        "propertyDescription": "Modern PG with all amenities",
        "propertyFullAddress": "123 Main St, Sector 14, Gurgaon",
        "propertyCity": "Gurgaon",
        "propertyState": "Haryana",
        "propertyPincode": "122002",
        "propertyStreetSocietyName": "Green Valley Society",
        "propertyHounseNo": "123",
        "propertyLocality": "Sector 14",
        "operatorId": "QSGM7393939",
        "propertyStatus": "Approved",
        "isActive": true,
        "views": 150,
        "timestamp": "2024-01-15T10:00:00Z",
        "propertyLocationUrl": "https://maps.google.com/...",
        "landmarks": ["Metro Station", "Mall"],
        "vacantBeds": 5,
        "totalBeds": 50,
        "totalRooms": 20,
        "totalFloor": 3,
        "startFromGround": 1,
        "propertyImages": [
          {
            "imageUrl": "https://...",
            "imageType": "cover",
            "isCover": true
          }
        ],
        "servicesFeature": ["WiFi", "Laundry"],
        "roomAmenities": ["AC", "Bed"],
        "propertyAmenities": ["WiFi", "AC", "Laundry", "Parking"],
        "propertyFacilities": ["Gym", "Common Area", "Kitchen"],
        "primeFacilities": ["24/7 Security", "Power Backup"],
        "houseRules": ["No smoking", "No pets", "No loud music after 10 PM"],
        "furnishedStatus": ["Fully Furnished"],
        "unitTypes": ["1RK", "1BHK"],
        "whoCanStay": ["Male", "Female"],
        "bestSuitedFor": ["Working Professional", "Students"],
        "roomOptions": [
          {
            "id": "room001",
            "totalBed": 1,
            "type": "Private",
            "typeNo": 1,
            "unitTypes": ["1RK"],
            "amount": 15000,
            "features": ["AC", "Attached Bathroom"],
            "isShow": true
          }
        ],
        "securityDeposit": "1 Month",
        "agreementDuration": "11 Month",
        "lockInPeriod": "6 Month",
        "noticePeriod": "1 Month",
        "rentMonthlyCycle": "01-01",
        "gracePeriod": "5 days",
        "isLateFine": true,
        "lateFineAmount": 100,
        "anyExtraCharges": true,
        "otherChargesList": [
          {
            "id": "charge001",
            "typeOfCharge": "Agreement",
            "chargesAmount": 1000,
            "repetition": "One Time"
          }
        ],
        "token": 5000,
        "wifiList": [],
        "addOnModules": {},
        "representative": {
          "name": "John Doe",
          "phoneNo": "9876543210",
          "email": "john@example.com",
          "isWhatsappNumberSame": true,
          "whatsappPhoneNumber": "9876543210"
        },
        "ownerMobileNumber": "9876543210",
        "propertyVerification": null,
        "createdAt": "2024-01-01T00:00:00Z",
        "updatedAt": "2024-01-15T00:00:00Z"
      }
    ],
    "totalCount": 50,
    "currentPage": 1,
    "totalPages": 5,
    "hasMore": true
  },
  "message": "Properties retrieved successfully"
}
```

#### Get Properties by Operator
**Endpoint:** `GET /properties/operator/:operatorId`

**Purpose:** Get all properties for a specific operator

**Parameters:**
- `operatorId` (path): Operator ID (e.g., "QSGM7393939")

**Query Parameters:**
- `page` (optional): Page number (default: 1)
- `limit` (optional): Items per page (default: 10)

**Example:** `GET /properties/operator/QSGM7393939?page=1&limit=10`

**Response:**
```json
{
  "success": true,
  "data": {
    "properties": [
      {
        "propertyId": "prop123",
        "operatorId": "QSGM7393939",
        "propertyName": "Green Valley PG",
        "propertyStatus": "Approved",
        // ... all property fields as above
      }
    ],
    "totalCount": 15,
    "currentPage": 1,
    "totalPages": 2,
    "hasMore": true,
    "operatorId": "QSGM7393939"
  },
  "message": "Found 15 properties for operator QSGM7393939"
}
```

#### Search Properties by Location
**Endpoint:** `GET /properties/search`

**Purpose:** Search properties by location criteria

**Query Parameters:**
- `city`: Filter by city (e.g., "Gurgaon")
- `state`: Filter by state (e.g., "Haryana")
- `locality`: Filter by locality/area
- `pincode`: Filter by 6-digit pincode
- `minRent`: Minimum rent amount
- `maxRent`: Maximum rent amount
- `operatorId`: Filter by operator ID
- `page` & `limit`: Pagination support

**Examples:**
```
GET /properties/search?city=Gurgaon&state=Haryana&page=1&limit=10
GET /properties/search?pincode=122002
GET /properties/search?locality=Sector 14
GET /properties/search?minRent=10000&maxRent=20000
GET /properties/search?operatorId=QSGM7393939
```

**Response:** Same format as "Get All Properties"

#### Get Specific Property Details
**Endpoint:** `GET /properties/:propertyId`

**Purpose:** Get detailed information about a specific property

**Response:**
```json
{
  "success": true,
  "data": {
    "propertyId": "prop123",
    "propertyName": "Green Valley PG",
    "propertyCode": "PG001",
    "propertyDescription": "Modern PG with excellent amenities and facilities",
    "propertyFullAddress": "123 Main St, Sector 14, Gurgaon",
    "propertyCity": "Gurgaon",
    "propertyState": "Haryana",
    "propertyPincode": "122002",
    "propertyStreetSocietyName": "Green Valley Society",
    "propertyHounseNo": "123",
    "propertyLocality": "Sector 14",
    "operatorId": "QSGM7393939",
    "propertyStatus": "Approved",
    "isActive": true,
    "views": 150,
    "timestamp": "2024-01-15T10:00:00Z",
    "propertyLocationUrl": "https://maps.google.com/...",
    "landmarks": ["Metro Station", "Mall"],
    "totalBeds": 50,
    "vacantBeds": 5,
    "totalRooms": 20,
    "totalFloor": 3,
    "startFromGround": 1,
    "propertyImages": [
      {
        "imageUrl": "https://example.com/image1.jpg",
        "imageType": "cover",
        "isCover": true
      },
      {
        "imageUrl": "https://example.com/image2.jpg",
        "imageType": "room",
        "isCover": false
      }
    ],
    "servicesFeature": ["WiFi", "Laundry", "Housekeeping"],
    "roomAmenities": ["AC", "Bed", "Wardrobe"],
    "propertyAmenities": ["WiFi", "AC", "Laundry", "Parking"],
    "propertyFacilities": ["Gym", "Common Area", "Kitchen"],
    "primeFacilities": ["24/7 Security", "Power Backup"],
    "houseRules": ["No smoking", "No pets", "No loud music after 10 PM"],
    "furnishedStatus": ["Fully Furnished"],
    "unitTypes": ["1RK", "1BHK"],
    "whoCanStay": ["Male", "Female"],
    "bestSuitedFor": ["Working Professional", "Students"],
    "roomOptions": [
      {
        "id": "room001",
        "totalBed": 1,
        "type": "Private",
        "typeNo": 1,
        "unitTypes": ["1RK"],
        "amount": 15000,
        "features": ["AC", "Attached Bathroom"],
        "isShow": true
      }
    ],
    "floorDetails": [
      {
        "floorNo": 1,
        "totalRooms": 10,
        "availableRooms": 3,
        "rooms": [
          {
            "id": "room001",
            "type": "Private",
            "totalBed": 1,
            "amount": 15000,
            "isShow": true
          }
        ]
      }
    ],
    "securityDeposit": "1 Month",
    "agreementDuration": "11 Month",
    "lockInPeriod": "6 Month",
    "noticePeriod": "1 Month",
    "rentMonthlyCycle": "01-01",
    "gracePeriod": "5 days",
    "isLateFine": true,
    "lateFineAmount": 100,
    "anyExtraCharges": true,
    "otherChargesList": [
      {
        "id": "charge001",
        "typeOfCharge": "Agreement",
        "chargesAmount": 1000,
        "repetition": "One Time"
      }
    ],
    "token": 5000,
    "wifiList": [],
    "addOnModules": {},
    "representative": {
      "name": "John Doe",
      "phoneNo": "9876543210",
      "email": "john@example.com",
      "isWhatsappNumberSame": true,
      "whatsappPhoneNumber": "9876543210"
    },
    "ownerMobileNumber": "9876543210",
    "propertyVerification": null,
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-15T00:00:00Z"
  },
  "message": "Property details retrieved successfully"
}
```

---

## Utility APIs

### Health Check
**Endpoint:** `GET /health`

**Purpose:** Check if the API server is running

**Response:**
```json
{
  "success": true,
  "message": "WhatsApp Bot API is running",
  "timestamp": "2024-01-15T10:00:00Z"
}
```

### Notifications
**Endpoint:** `POST /notify`

**Purpose:** Send real-time notifications (internal use)

**Request Body:**
```json
{
  "type": "complaint",
  "operatorId": "op789",
  "message": "New complaint raised by John Doe",
  "data": {
    "complaintId": "comp123",
    "tenantId": "tenant123"
  }
}
```

---

## Error Handling

All APIs return consistent error responses:

```json
{
  "success": false,
  "message": "Error description"
}
```

### Common HTTP Status Codes:
- `200` - Success
- `201` - Created (for POST requests)
- `400` - Bad Request (validation errors)
- `404` - Not Found
- `500` - Internal Server Error

### Validation Errors:
```json
{
  "success": false,
  "message": "Validation failed",
  "errors": [
    {
      "field": "phoneNumber",
      "message": "Phone number must be 10 digits"
    }
  ]
}
```

---

## Data Models

### TenantsModel Fields:
- `tenantFullName`, `tenantPhoneNo`, `tenantGender`
- `propertyDetails`, `agreementDetails`
- `roomNo`, `tenantStatus`, `bookingId`

### TransactionModel Fields:
- `userName`, `mobileNo`, `propertyCode`
- `typeOfTransactions`, `dueDate`, `paidDate`
- `status`, `paymentMode`, `brandName`

### ComplaintModel Fields:
- `complaintType`, `complaintSubtype`, `description`
- `tenantsName`, `phone`, `roomNo`, `status`
- `steps` (array of ComplaintStepModel)
- `photoUrls` (array of photo URLs for complaint documentation)

### ComplaintStepModel Fields:
- `name` - Step name or title
- `description` - Step details
- `dateTime` - Timestamp when step was added
- `status` - Step status (e.g., "completed", "in-progress")
- `priority` - Priority level
- `photoUrl` - Optional photo URL for this step

### NoticeModel Fields:
- `tenantId`, `tenantName`, `tenantMobile`
- `noticeReason`, `moveInDate`, `moveOutDate`
- `status`, `responseDate`, `bankDetails`

### PropertyModel Fields:
- `propertyName`, `propertyCode`, `propertyFullAddress`
- `propertyAmenities`, `propertyFacilities`, `roomOptions`
- `securityDeposit`, `whoCanStay`, `bestSuitedFor`

### RoomOption Fields:
- `id`, `floorNo`, `type`, `totalBed`
- `amount`, `features`, `unitTypes`
- `available` (calculated field)

---

## Usage Examples

### For WhatsApp Bot Integration:

1. **User sends phone number** → Call `/verify-user/:phoneNumber`
2. **If tenant** → Use tenant APIs for complaints, notices, payments
3. **If lead** → Use property APIs for browsing and details
4. **Create complaint** → POST to `/tenants/:tenantId/complaints`
5. **Check status** → GET `/tenants/:tenantId/complaints/:complaintId/status`

### For Mobile App Integration:

1. **Property listing** → GET `/properties` with pagination
2. **Location search** → GET `/properties/search?city=Gurgaon`
3. **Property details** → GET `/properties/:propertyId`
4. **Tenant dashboard** → GET `/tenants/:tenantId/info`

### Mock Phone Numbers:
- **Existing Tenants**: `7589017493` (Jatin), `9876543210` (Test User)
- **New Leads**: Any other 10-digit number

### Mock IDs:
- **Tenant ID**: `02C0AzygCQ2RqnovIfFC` (Jatin's actual Firebase document ID)
- **Property ID**: `prop_001`

This API documentation provides complete coverage of all endpoints and their usage patterns for both WhatsApp bot and mobile app integrations.