API Docs

API: Create Seat Request

Request

Create a seat request to temporarily block a seat with a POST request:

POST /seat-requests

Request Body (New Issue):


{
  "seat_inventory_id": 123,
  "trip_id": 1,
  "notes": "Window seat preferred"
}

Request Body (Add to Existing Issue):


{
  "seat_inventory_id": 124,
  "trip_id": 1,
  "issue_id": "SR-20250821-143052-A1B2C3",
  "notes": "Adjacent to A1"
}

Sample Response (201 Created):


{
    "status": "success",
    "code": 201,
    "message": "Seat blocked successfully for 5 minutes",
    "data": {
        "seat_request_id": 123,
        "issue_id": "IE-20250115-143052-ABC123",
        "seat_inventory_id": 456,
        "status": "pending",
        "blocked_until": "2025-01-15T14:35:52",
        "blocked_for_minutes": 5,
        "remaining_time": {
            "minutes": 5,
            "seconds": 300,
            "expires_at": "2025-01-15T14:35:52"
        },
        "seat_info": {
            "seat": {
                "seat_number": "A1",
                "row_position": 1,
                "col_position": 1,
                "seat_type": "Business Class",
                "fare_amount": 1200
            },
            "trip": {
                "trip_date": "2025-01-20",
                "coach_no": "DH-AC-001",
                "coach_type": 1,
                "coach_type_name": "AC"
            },
            "route": {
                "start_district": "Dhaka",
                "end_district": "Chittagong",
                "route_display": "Dhaka → Chittagong",
                "distance": 250.5,
                "duration": "06:30:00"
            },
            "current_status": {
                "booking_status": 3,
                "status_name": "Blocked"
            }
        },
        "user_id": 25,
        "created_at": "2025-01-15T14:30:52.000Z",
        "issue_summary": {
            "issue_id": "IE-20250115-143052-ABC123",
            "total_seats_in_issue": 1,
            "seats": [
                {
                    "seat_request_id": 123,
                    "seat_inventory_id": 456,
                    "seat_id": 101,
                    "status": "pending",
                    "seat_number": "A1",
                    "row_position": 1,
                    "col_position": 1,
                    "seat_type": "Business Class",
                    "fare_amount": 1200
                }
            ]
        }
    }
}

Request Parameters:

seat_inventory_id - Required, the seat inventory ID to block
issue_id - Optional, existing issue ID to add this seat to
notes - Optional, user notes for this seat request

Response Fields:

seat_request_id - Unique ID for this seat request
issue_id - Issue ID grouping related seat requests
status - Current status (pending, expired, cancelled, booked)
blocked_until - UTC timestamp when block expires
remaining_time - Countdown information
seat_info - Complete seat, trip, and route details
issue_summary - All seats in the current issue

Behavior:

New Issue: If no issue_id provided, creates a new issue
Add to Issue: If issue_id provided, adds seat to existing issue
Synchronized Expiry: All seats in an issue expire at the same time
5-Minute Block: Seats are blocked for exactly 5 minutes

Error Responses:

400 Bad Request - Seat Already Blocked


{
  "status": "error",
  "code": 400,
  "message": "Seat is already blocked by another user",
  "data": {
    "seat_inventory_id": 123,
    "blocked_until": "2025-08-21T14:35:52.000000Z",
    "blocked_by_user": 41
  }
}

404 Not Found - Seat Not Available


{
  "status": "error",
  "code": 404,
  "message": "Seat inventory not found or not available",
  "data": {
    "seat_inventory_id": 123,
    "reason": "already_booked"
  }
}

400 Bad Request - Invalid Issue ID


{
  "status": "error",
  "code": 400,
  "message": "Issue ID not found or not owned by current user",
  "data": {
    "issue_id": "SR-20250821-143052-A1B2C3"
  }
}

JavaScript Example:


// Request first seat (creates new issue)
const response1 = await fetch('/api/seat-requests', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your_token',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    seat_inventory_id: 123,
    notes: 'Window seat preferred'
  })
});

const data1 = await response1.json();
const issueId = data1.data.issue_id;

// Request second seat (add to existing issue)
const response2 = await fetch('/api/seat-requests', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your_token',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    seat_inventory_id: 124,
    issue_id: issueId,
    notes: 'Adjacent seat'
  })
});

const data2 = await response2.json();
console.log('Total seats in issue:', data2.data.issue_summary.total_seats_in_issue);

Use Cases:

Single Seat Booking: User selects one seat and proceeds to payment
Family Booking: Book multiple adjacent seats for family members
Group Booking: Reserve multiple seats before confirming the group
Seat Selection: Allow users to "try" different seats before deciding

Notes:

Each user can only block a limited number of seats simultaneously
Blocked seats are automatically released after 5 minutes
Users cannot block seats that are already booked or blocked by others
The same user can have multiple issues active at the same time