Booking Base URL

http://localhost:8000/api/booking

All routes below are prefixed with this base URL.

Create Booking

POST /create (Protected - Customer JWT Required)

Description

Create a new scrap pickup booking. Maximum 3 active bookings allowed per customer.

Headers

Authorization: Bearer <customer_token> Content-Type: application/json

Request Body

{ "category": [ { "categoryId": "paper", "name": "Paper", "estimatedWeight": 13, "subcategories": [ { "subCategoryId": "newspaper", "name": "Newspaper" } ] } ], "scrapImages": [ { "imageUrl": "/upload/file/file1.jpg", "size": 204800, "type": "image/jpeg" } ], "pickupLocation": { "doorNo": "12A", "flat": "3rd Floor", "area": "MG Road", "city": "Bangalore", "state": "Karnataka", "pincode": "560001", "coordinates": { "lat": 12.9716, "lng": 77.5946 } }, "estimatedPrice": 195 }

Success Response (201)

{ "success": true, "message": "Booking created successfully", "data": { "_id": "bookingId", "status": "requested", "type": "online", "estimatedPrice": 195, "createdAt": "timestamp" } }

Error Responses

400 At least one category is required
400 Valid pickup location is required
400 Estimated price must be a number
400 Only 3 active pickup bookings are allowed
401 Unauthorized

Customer Active Bookings

GET /active-booking (Protected - Customer JWT Required)

Description

Returns current active bookings (max 3).

Headers

Authorization: Bearer <customer_token>

Success Response

{ "success": true, "bookings": [ { "_id": "bookingId", "status": "requested", "estimatedPrice": 195, "pickupLocation": {...}, "createdAt": "timestamp" } ] }

Empty Response

{ "success": true, "bookings": [], "message": "No active bookings found" }

Customer Booking History

GET /booking-history (Protected - Customer JWT Required)

Description

Returns completed bookings of the customer.

Headers

Authorization: Bearer <customer_token>

Success Response

{ "success": true, "bookings": [ { "_id": "bookingId", "status": "completed", "estimatedPrice": 220, "createdAt": "timestamp" } ] }

Vendor Active Bookings

GET /vendor-active-booking (Protected - Vendor JWT Required)

Description

Returns active bookings assigned to vendor.

Headers

Authorization: Bearer <vendor_token>

Success Response

{ "success": true, "bookings": [ { "_id": "bookingId", "status": "requested", "estimatedPrice": 195 } ] }

Vendor Booking History

GET /vendor-booking-history (Protected - Vendor JWT Required)

Description

Returns all bookings handled by vendor.

Headers

Authorization: Bearer <vendor_token>

Success Response

{ "success": true, "bookings": [ { "_id": "bookingId", "status": "completed", "estimatedPrice": 220 } ] }

Vendor Accept Booking

POST /vendor-accept-booking (Protected - Vendor JWT Required)

Description

Vendor accepts booking using first-come-first-serve logic. Vendor must have an active subscription.

Headers

Authorization: Bearer <vendor_token> Content-Type: application/json

Request Body

{ "bookingId": "664f0c2f8f7b1c0012abcd12" }

Success Response (200)

{ "success": true, "message": "Booking accepted successfully", "data": { "_id": "bookingId", "status": "accepted", "vendorAssignment": { "vendorId": { "_id": "vendorId", "email": "vendor@gmail.com", "phone": "9999999999", "ownername": "Rahul", "businessname": "ABC Scrap" }, "assignedAt": "timestamp" } } }

Error Responses

400 bookingId is required 400 Invalid bookingId 400 Booking already accepted by another vendor 404 No active subscription found 401 Unauthorized

Vendor Assign Booking To Employee

POST /vendor-assign-booking (Protected - Vendor JWT Required)

Description

Assign accepted booking to vendor employee.

Headers

Authorization: Bearer <vendor_token> Content-Type: application/json

Request Body

{ "bookingId": "664f0c2f8f7b1c0012abcd12", "employeeId": "664f0d5e8f7b1c0012abcd45" }

Success Response (200)

{ "success": true, "message": "Booking assigned to employee successfully", "data": { "_id": "bookingId", "status": "accepted", "vendorAssignment": { "vendorId": { "_id": "vendorId", "email": "vendor@gmail.com", "phone": "9999999999", "ownername": "Rahul", "businessname": "ABC Scrap" } }, "employeeAssignment": { "employeeId": { "_id": "employeeId", "emp_id": "EMP001", "fullname": "Aman Kumar", "email": "employee@gmail.com", "phone": "8888888888" }, "assignedAt": "timestamp" } } }

Error Responses

400 bookingId and employeeId are required
400 Invalid bookingId or employeeId
400 Vendor has not accepted this booking yet
404 Booking not found
404 Employee not found
401 Unauthorized

Employee Update Booking Status

POST /employee-update-booking-status (Protected - Employee JWT Required)

Description

Employee updates booking status such as onTheWay, arrived, completed or cancelled.

Headers

Authorization: Bearer <employee_token> Content-Type: application/json

Request Body

{ "bookingId": "664f0c2f8f7b1c0012abcd12", "status": "completed" }

Allowed Status Values

onTheWay
arrived
completed
cancelled

Success Response (200)

{ "success": true, "data": { "_id": "bookingId", "status": "completed" } }

Error Responses

400 All fields are required
400 Pickup not found
401 Unauthorized

Booking Detail

GET /booking-detail/:bookingId (Protected - Vendor JWT Required)

Description

Returns complete booking details including customer information.

Headers

Authorization: Bearer <vendor_token>

URL Params

bookingId = MongoDB booking _id

Example Request

GET /booking-detail/664f0c2f8f7b1c0012abcd12

Success Response (200)

{ "success": true, "data": { "_id": "bookingId", "customerId": { "_id": "customerId", "fullname": "Rahul Kumar", "phone": "9999999999", "profileImg": "/uploads/profile.jpg" }, "category": [ { "categoryId": "paper", "name": "Paper", "estimatedWeight": 13 } ], "pickupLocation": { "doorNo": "12A", "area": "MG Road", "city": "Bangalore", "state": "Karnataka", "pincode": "560001" }, "estimatedPrice": 195, "status": "requested", "createdAt": "timestamp" } }

Error Responses

400 Invalid bookingId 404 Booking not found 401 Unauthorized

Notes