================================================================================ BHARAT SEVA - CUSTOMER BOOKING V2 FLOW GUIDE ================================================================================ This document describes the exact sequence of API calls required to test the V2 Booking / RFQ (Request For Quotation) flow on Postman. -------------------------------------------------------------------------------- PREREQUISITES: - All requests require the following header unless specified: Accept: application/json - Authenticated endpoints require: Authorization: Bearer -------------------------------------------------------------------------------- STEP 1: USER AUTHENTICATION ---------------------------------------- Purpose: Authenticate the customer and retrieve the JWT Bearer Token. Method: POST URL: {{base_url}}/api/v1/auth/login Headers: Content-Type: application/json Body (JSON): { "phone": "9876543210", "password": "password123" } Response (Success): - Extract the "access_token" value. - Save this as a Bearer Token for subsequent authenticated requests. STEP 2: DISCOVER NEARBY VENDORS (OPTIONAL) ---------------------------------------- Purpose: Find category groups and nearby available vendors before booking. Request A: Get Category Groups Method: GET URL: {{base_url}}/api/v2/customer/category-groups Request B: Find Nearby Vendors Method: POST URL: {{base_url}}/api/v2/customer/nearby/{group?} Headers: Content-Type: application/json Body (JSON): { "latitude": 19.0835, "longitude": 72.9960, "category_id": 1 // Optional: Pass the selected category ID in the body } * Note on "{group?}": - Can be: "service_provider", "shop_owner", or "street_hawker". - If omitted (e.g. /api/v2/customer/nearby), it defaults to "service_provider". Response (Success): - Returns a list of nearby vendors belonging to the chosen group and category. Under V2 design, if the group is anything other than "service_provider", booking is not allowed; only profile/contact actions should be shown. STEP 3: CREATE A BOOKING REQUEST (DIRECT OR BROADCAST) ---------------------------------------- Purpose: Create a booking lead. Returns a unique "lead_id" to follow up. Method: POST URL: {{base_url}}/api/v2/customer/book Headers: Content-Type: application/json Authorization: Bearer Body (JSON): { "category_id": 1, "description": "Leakage repair in kitchen sink", "latitude": 19.0835, "longitude": 72.9960, "full_address": "Sector 15, Vashi, Navi Mumbai", "landmark": "Near Railway Station", "save_address": true, "vendor_id": null } * Note on "vendor_id": - Set "vendor_id" to a number (e.g. 4) for a DIRECT booking request (Flow A). - Set "vendor_id" to null (or omit it) to BROADCAST the request (Flow B). Response (Success): Extract "lead_id" (e.g. 15) from the response data. STEP 4: GET ACCEPTED VENDORS (BROADCAST MODE ONLY) ---------------------------------------- Purpose: See which nearby vendors clicked "Accept" on the broadcasted lead. Method: GET URL: {{base_url}}/api/v2/customer/bookings/{{lead_id}}/accepted-vendors Headers: Authorization: Bearer Response (Success): - Returns list of accepted vendors, including their ratings, distance, and minimum visit charges. - Choose the vendor you want to proceed with. Let's say you choose vendor ID 1. STEP 5: CHOOSE A VENDOR (BROADCAST MODE ONLY) ---------------------------------------- Purpose: Assign the booking to one specific vendor who accepted. Method: POST URL: {{base_url}}/api/v2/customer/bookings/{{lead_id}}/choose-vendor Headers: Content-Type: application/json Authorization: Bearer Body (JSON): { "vendor_id": 1 } Response (Success): - Marks the chosen vendor as accepted and rejects all other candidate bidders. - The chosen vendor is notified. STEP 6: VIEW VENDOR'S QUOTATION ---------------------------------------- Purpose: Once the assigned/chosen vendor inspects the site, they will submit a quotation (price + description). Use this endpoint to view it. Method: GET URL: {{base_url}}/api/v2/customer/bookings/{{lead_id}}/quotation Headers: Authorization: Bearer Response (Success): - Returns details of the quotation (price, scheduled time, description). STEP 7: RESPOND TO QUOTATION (ACCEPT OR DECLINE) ---------------------------------------- Purpose: Accept or decline the vendor's price quotation. Method: POST URL: {{base_url}}/api/v2/customer/bookings/{{lead_id}}/quotation/respond Headers: Content-Type: application/json Authorization: Bearer Body (JSON): { "response": "accept" } * Note: The "response" field values can be: - "accept": Accepts the quote. Generates a 4-digit start OTP ("start_otp") for the vendor to verify and begin the work. - "decline": Rejects the quote. The lead automatically reopens and is rebroadcast to nearby vendors. Response (Success when response is "accept"): - Returns "start_otp" (e.g. 5432). Give this OTP to the vendor to begin. STEP 8: CANCELLATION (OPTIONAL / ALTERNATIVE PATH) ---------------------------------------- Purpose: Cancel the booking at any point prior to work starting. Method: POST URL: {{base_url}}/api/v2/customer/bookings/{{lead_id}}/cancel Headers: Authorization: Bearer ================================================================================