.. _returnsscanning-label:

POST /v3/returns/tasks/shipments 
--------------------------------------------------------------------------------

**Description** - 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 information if more shipments are there to be scanned (hasMore Parameter), along with the encoded URL of the next shipment to be scanned (nextUrl Parameter). After all shipments have been scanned, the hasMore Parameter becomes false and nextUrl becomes null, indicating scanning completion.

**Purpose:** Poll for scanned shipments for a specific FE. Supports pagination for retrieving historical data. It should be called every 30 seconds.

.. note::
   **How Pagination Works:**
   
   - **First Request**: POST to get the initial scanned shipments
   - **Subsequent Requests**: GET using nextUrl from previous response
   - The nextUrl is base64 encoded and contains all query parameters
   - Use the hasMore flag to determine if more data might be available

Request and Response Parameters
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. container:: toggle

    .. container:: header

        **☰ SHOW | HIDE**

    **First Request URL:** ``https://api.flipkart.net/sellers/v3/returns/tasks/shipments``

    **Subsequent Requests URL:** ``https://api.flipkart.net/sellers/v3/returns/tasks/shipments/{encoded_url}``

    **Request Header Parameters (Both Requests)**

    +------------------+------------+------------+----------------------------------------+
    |Parameter         |Type        |Requirement | Description                            |
    +==================+============+============+========================================+
    |``Content-Type``  |String      |Mandatory   |Must be ``application/json``            |
    +------------------+------------+------------+----------------------------------------+
    |``Authorization`` |String      |Mandatory   |Bearer token for authentication         |
    +------------------+------------+------------+----------------------------------------+

    **Request Body Parameters (First Request - POST)**

    +----------------------+-------------+--------------+--------------------------------------+
    |Parameter             |Type         |Requirement   | Description                          |
    +======================+=============+==============+======================================+
    |``taskId``            |String       |Mandatory     |Task identifier                       |
    +----------------------+-------------+--------------+--------------------------------------+
    |``feId``              |String       |Mandatory     |Field Executive identifier            |
    +----------------------+-------------+--------------+--------------------------------------+
    |``pageSize``          |Integer      |Optional      |Number of shipments per page (default:|
    |                      |             |              |25)                                   |
    +----------------------+-------------+--------------+--------------------------------------+

    **Sample First Request (POST)**

    .. code-block:: json

        {
          "taskId": "123",
          "feId": "fe12303",
          "pageSize": 25
        }

    **Sample Subsequent Request (GET)**

    Use the nextUrl from the previous response. The URL is base64 encoded and contains all query parameters.

    .. code-block:: text

        GET https://api.flipkart.net/sellers/v3/returns/tasks/shipments/ewogICAgInRhc2tJZCI6ICIxMjMiLAogICAgImZlSWQiOiAiMTIzODkwIiwgIAogICAgImV0YWciOiAiRk1QMTA0NSIsIAogICAgInBhZ2VTaXplIjogMjAgCiAgfQ==

    **Response Body Parameters (Success - 200 OK)**

    +---------------------------------------------+--------+---------------------------------------------+
    | Parameter/Attribute                         | Type   | Description                                 |
    +=============================================+========+=============================================+
    | ``hasMore``                                | Boolean| Indicates if more shipments are available  |
    +---------------------------------------------+--------+---------------------------------------------+
    | ``nextUrl``                                | String | Base64 encoded URL for next page           |
    +---------------------------------------------+--------+---------------------------------------------+
    | ``scannedShipments``                        | Array  | List of scanned shipments                  |
    +---------------------------------------------+--------+---------------------------------------------+
    | ``scannedShipments[].trackingId``           | String | Shipment tracking ID                       |
    +---------------------------------------------+--------+---------------------------------------------+
    | ``scannedShipments[].shipmentId``           | String | Shipment identifier                        |
    +---------------------------------------------+--------+---------------------------------------------+
    | ``scannedShipments[].status``               | String | Shipment status: ``ACCEPTED`` or           |
    |                                             |        | ``REJECTED``                               |
    +---------------------------------------------+--------+---------------------------------------------+
    | ``scannedShipments[].reason``               | String | Reason for rejection (null if accepted)    |
    +---------------------------------------------+--------+---------------------------------------------+
    | ``scannedShipments[].flyerDetails``         | Object | Flyer verification details                  |
    +---------------------------------------------+--------+---------------------------------------------+
    | ``scannedShipments[].flyerDetails.``        | String | Actual flyer ID                            |
    | ``actualFlyerId``                           |        |                                            |
    +---------------------------------------------+--------+---------------------------------------------+
    | ``scannedShipments[].flyerDetails.``        | String | Captured flyer ID                          |
    | ``capturedFlyerId``                         |        |                                            |
    +---------------------------------------------+--------+---------------------------------------------+
    | ``scannedShipments[].flyerDetails.status``  | String | Flyer verification status (e.g.,           |
    |                                             |        | ``FlyerMatch``)                            |
    +---------------------------------------------+--------+---------------------------------------------+
    | ``scannedShipments[].obdDetails``           | Object | OBD (Open Box Delivery) details            |
    +---------------------------------------------+--------+---------------------------------------------+
    | ``scannedShipments[].obdDetails.eligible``  | Boolean| OBD eligibility status                     |
    +---------------------------------------------+--------+---------------------------------------------+
    | ``scannedShipments[].obdDetails.remark``    | String | OBD remark (e.g., ``NoIssues``)            |
    +---------------------------------------------+--------+---------------------------------------------+
    | ``scannedShipments[].obdDetails.``          | Array  | List of image URLs                         |
    | ``imageLinks``                              |        |                                            |
    +---------------------------------------------+--------+---------------------------------------------+
    | ``scannedShipments[].scannedAt``            | Long   | Scan timestamp (Unix timestamp in          |
    |                                             |        | milliseconds)                              |
    +---------------------------------------------+--------+---------------------------------------------+

    **Sample Response (Success - 200 OK)**

    .. code-block:: json

        {
          "hasMore": true,
          "nextUrl": "/sellers/v3/returns/tasks/shipments/ewogICAgInRhc2tJZCI6ICIxMjMiLAogICAgImZlSWQiOiAiMTIzODkwIiwgIAogICAgImV0YWciOiAiRk1QMTA0NSIsIAogICAgInBhZ2VTaXplIjogMjAgCiAgfQ==",
          "scannedShipments": [
            {
              "trackingId": "FMP01",
              "shipmentId": "SH123",
              "status": "ACCEPTED",
              "reason": null,
              "flyerDetails": {
                "actualFlyerId": "TEST_FLYER",
                "capturedFlyerId": "TEST_FLYER",
                "status": "FlyerMatch"
              },
              "obdDetails": {
                "eligible": true,
                "remark": "NoIssues",
                "imageLinks": ["url1", "url2"]
              },
              "scannedAt": 1732000000
            }
          ]
        }

    **Sample Response (No Shipments - 200 OK)**

    .. code-block:: json

        {
          "scannedShipments": []
        }

    **Possible Error Response Codes**

    =======================================        =========================
    Error Codes                                    Reason for Error
    =======================================        =========================
    ``TASK_CLOSED``                                Task is closed
    ``TRIPSHEET_TASK_NOT_FOUND``                   No RETURN task found for seller
    ``INVALID_TASK_TYPE_ERROR``                    Task type is not RETURN
    ``UNAUTHORIZED_ERROR``                         Authentication failed
    ``INTERNAL_SERVER_ERROR``                      Internal server error
    ``BAD_GATEWAY_ERROR``                          Bad gateway error
    ``SERVICE_UNAVAILABLE_ERROR``                  Service unavailable
    ``GATEWAY_TIMEOUT_ERROR``                      Gateway timeout
    =======================================        =========================

|

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

|