Returns V3

📄️ Initial Page Load

The Initial Page Load API is specifically designed to execute only when the system detects shipments scheduled for delivery today. This API serves a foundational purpose by fetching essential core identifiers, such as feId and taskId, along with other necessary details. Crucially, the API also retrieves configuration data that is subsequently utilised in the workflow to determine if the Generate Start OTC button should be visible or hidden on the dashboard, based on the enabled configuration settings. This API only returns FEs that are currently on the Start OTC page, End OTC page, or Scanning. It does NOT return FEs that haven't arrived yet or have completed their task.

📄️ Start OTC Details

The Start OTC API serves the same purpose as the Generate Start OTC button on the FK Seller Hub. On hitting the API, the FEs who have reached the location, along with their Start OTCs, are returned in response. The API generates One-time codes for FEs who have reached the seller location and are on the Start OTC page. OTCs are generated ONLY for FEs who have reached the seller location and are on the Start OTC page. Each OTC has an expiry time and must be used before expiration. If no FEs are on the Start OTC page, otcDetails will be empty.

📄️ Shipment Scanning

After the Start OTC has been validated, the shipment scanning page is shown for the FE in the FK Seller Hub. As shipments get scanned, the count of shipments in Handover in progress keeps increasing. The response contains the information if more shipments are there to be scanned (has_more Parameter), along with the encoded URL of the next shipment to be scanned (next_url Parameter). The encoded URL of the next shipment forms the URL for the request for next Subsequent Requests API call. In the Shipments Scanning API, after all the shipments have been scanned, the has_more Parameter will become false, and the next_url Parameter will become null. This information can then be used to understand that the scanning of the shipments has been completed and to move to the end OTP generation API after the count of the shipments has been verified and they have been handed over. The API supports pagination for retrieving historical data. It should be called every 30 seconds. Subsequent Requests: GET using next_url from previous response. The next_url is base64 encoded and contains all query parameters. Use the has_more flag to determine if more data might be available. Endpoint: POST /v3/returns/tasks/shipments (First request). Endpoint: GET /sellers/v3/returns/tasks/shipments/{encoded_url} (Subsequent requests). Base URL: https://api.flipkart.net/sellers.

📄️ End OTC Details

When the Generate End OTC is clicked, the summary of the scanned shipments with statistics, as well as the End OTC, is shown. The same information can be fetched using the End OTC API as well. After the End OTC has been verified by the FE, the returnCompleted order event notification will get pushed by the Order Management Notification Service. All shipments must be synced before ending End OTC. Shipment scanning API (POST /v3/returns/tasks/shipments) must be called at least once before calling End OTC API. FE must be on the End OTC page (not actively scanning). FE cannot go back from End OTC to Scanning again.