API Docs

API: Seat Request System Overview

Seat Request System

The Seat Request system allows users to temporarily block seats before booking. This prevents conflicts when multiple users try to book the same seat simultaneously.

How It Works

Seat Blocking
  • User requests a seat
  • Seat is blocked for 5 minutes
  • Other users cannot book blocked seats
  • User has time to complete booking
Multi-Seat Support
  • Multiple seats can be grouped in an "issue"
  • All seats in an issue have the same expiry time
  • Can add more seats to existing issue
  • Cancel individual seats or entire issue

Key Concepts

Issue ID

An Issue ID is a unique identifier that groups multiple seat requests together. Format: SR-YYYYMMDD-HHMMSS-RANDOM

Example: SR-20250821-143052-A1B2C3

Seat Request States

  • pending - Seat is blocked and waiting for booking
  • expired - 5-minute timer expired, seat released
  • cancelled - User cancelled the request
  • booked - Seat has been successfully booked

Timing

  • Block Duration: 5 minutes from request time
  • Auto-Release: Seats automatically released after expiry
  • Remaining Time: API provides countdown information

API Endpoints

Method Endpoint Description Documentation
POST /seat-requests Create a seat request (block seat) View
GET /seat-requests/{issue_id} Check status of all seats in an issue View
DELETE /seat-requests/{issue_id} Cancel entire issue (all seats) View

Workflows

Single Seat Booking

  1. User searches for trips
  2. User selects a seat
  3. POST to /seat-requests (creates new issue)
  4. Seat is blocked for 5 minutes
  5. User proceeds to booking process

Multi-Seat Booking

  1. User requests first seat (creates issue)
  2. User requests additional seats (adds to same issue)
  3. All seats have synchronized expiry time
  4. User can check status of all seats
  5. User proceeds to book all seats or cancels entire issue

Best Practices

  • Check Remaining Time: Always monitor the remaining time to avoid expiry
  • Handle Expiry: Implement proper handling when seats expire
  • Issue Management: Use the same issue_id for related seat requests
  • Error Handling: Handle seat already blocked scenarios gracefully
  • Cleanup: Cancel unused seat requests to free up seats for other users

Quick Navigation

Create Request
Check Status
Multi-Seat Guide
Cancel Requests