# Manual Booking API Documentation

## Overview
These APIs allow manual booking creation by first fetching customers with their vehicles, optionally creating new customers with vehicles, and then creating bookings.

**Base URL:** `/connector/api`
**Authentication:** Required (Bearer Token)

---

## 1. Get Customers with Vehicles

Retrieve all customers along with their associated vehicles.

### Endpoint
```
GET /connector/api/manual-booking/customers
```

### Query Parameters
| Parameter | Type   | Required | Description |
|-----------|--------|----------|-------------|
| search    | string | No       | Search by customer name or mobile number |

### Response
```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Ahmed Mohamed",
      "mobile": "0123456789",
      "vehicles": [
        {
          "device_id": 59,
          "plate_number": "ABC 123",
          "chassis_number": "VIN123456",
          "manufacturing_year": "2024",
          "color": "Red",
          "car_type": "ملاكي",
          "model_name": "Corolla",
          "brand_name": "Toyota"
        }
      ]
    }
  ]
}
```

### Example Request
```bash
curl -X GET "https://your-domain.com/connector/api/manual-booking/customers?search=Ahmed" \
  -H "Authorization: Bearer {token}"
```

---

## 2. Add Customer with Vehicle

Create a new customer along with their vehicle information.

### Endpoint
```
POST /connector/api/manual-booking/customer
```

### Request Body
| Parameter           | Type    | Required | Description |
|---------------------|---------|----------|-------------|
| name                | string  | Yes      | Customer name |
| mobile              | string  | Yes      | Customer mobile number |
| email               | string  | No       | Customer email |
| plate_number        | string  | Yes      | Vehicle plate number |
| chassis_number      | string  | No       | Vehicle VIN/chassis number |
| manufacturing_year  | string  | Yes      | Vehicle manufacturing year |
| color               | string  | No       | Vehicle color |
| car_type            | string  | No       | Vehicle type (e.g., "ملاكي") |
| brand_id            | integer | Yes      | Brand ID (from categories table) |
| model_id            | integer | Yes      | Model ID (from repair_device_models table) |

### Response
```json
{
  "success": true,
  "message": "Customer and vehicle created successfully",
  "data": {
    "contact_id": 123,
    "device_id": 456,
    "name": "Ahmed Mohamed",
    "mobile": "0123456789",
    "plate_number": "ABC 123"
  }
}
```

### Example Request
```bash
curl -X POST "https://your-domain.com/connector/api/manual-booking/customer" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ahmed Mohamed",
    "mobile": "0123456789",
    "email": "ahmed@example.com",
    "plate_number": "ABC 123",
    "chassis_number": "VIN123456",
    "manufacturing_year": "2024",
    "color": "Red",
    "car_type": "ملاكي",
    "brand_id": 1,
    "model_id": 10
  }'
```

---

## 3. Create Manual Booking

Create a booking using customer and vehicle data. Automatically handles car service vs non-car service locations.

### Endpoint
```
POST /connector/api/manual-booking/create
```

### Request Body
| Parameter          | Type    | Required | Description |
|--------------------|---------|----------|-------------|
| contact_id         | integer | Yes      | Customer ID |
| device_id          | integer | Yes      | Vehicle/Device ID |
| location_id        | integer | Yes      | Branch/Location ID |
| service_id         | integer | Yes      | Service ID |
| booking_start      | string  | Yes      | Booking start date/time (ISO format) |
| booking_note       | string  | No       | Booking notes (max 1000 chars) |
| send_notification  | boolean | No       | Send SMS notification to customer |

### Behavior
- **Car Service Locations** (`is_car_service = true`): Uses the provided `device_id`
- **Non-Car Service Locations** (`is_car_service = false`): Automatically uses `device_id = 999` (Other device)

### Response
```json
{
  "success": true,
  "message": "Booking created successfully",
  "data": {
    "booking_id": 789,
    "booking_name": "Ahmed Mohamed - Corolla - 2026-07-07 14:00:00",
    "contact_name": "Ahmed Mohamed",
    "device_id": 456,
    "booking_start": "2026-07-07T14:00:00",
    "location_id": 2,
    "service_id": 6,
    "is_car_service": true
  }
}
```

### Example Request
```bash
curl -X POST "https://your-domain.com/connector/api/manual-booking/create" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": 123,
    "device_id": 456,
    "location_id": 2,
    "service_id": 6,
    "booking_start": "2026-07-07T14:00:00",
    "booking_note": "Customer requested morning slot",
    "send_notification": true
  }'
```

---

## Complete Workflow Example

### Step 1: Fetch Customers
```bash
GET /connector/api/manual-booking/customers
```

### Step 2: If customer doesn't exist, create one
```bash
POST /connector/api/manual-booking/customer
{
  "name": "New Customer",
  "mobile": "0123456789",
  "plate_number": "XYZ 789",
  "manufacturing_year": "2024",
  "brand_id": 1,
  "model_id": 10
}
```

### Step 3: Create booking
```bash
POST /connector/api/manual-booking/create
{
  "contact_id": 123,
  "device_id": 456,
  "location_id": 2,
  "service_id": 6,
  "booking_start": "2026-07-07T14:00:00"
}
```

---

## Error Responses

### 404 Not Found
```json
{
  "error": "Location not found"
}
```

### 422 Validation Error
```json
{
  "success": false,
  "message": "The given data was invalid.",
  "errors": {
    "contact_id": ["The contact id field is required."]
  }
}
```

### 500 Server Error
```json
{
  "success": false,
  "message": "Failed to create customer and vehicle",
  "error": "Database error..."
}
```

---

## Notes

1. **Authentication**: All endpoints require a valid Bearer token in the Authorization header.
2. **Device ID 999**: This is a special "Other" device used for non-car service bookings (barber, simulation, etc.).
3. **is_car_service**: Determined from the `website_settings` table based on location_id or business_id.
4. **SMS Notification**: If `send_notification` is true, an SMS will be sent to the customer's mobile number in Arabic.
