[FEATURE] Enable Querying Reverses via Mandae V1 API

[guibranco]

Description

Add support for querying reverses/return shipments through the Mandae V1 API. This feature should allow the system to retrieve a list of return shipments (reverses) associated with a given tracking number or service order (OS). It will enable better visibility of return shipments for orders that have reverse logistics requirements.

Feature Objective

• Implement a method that uses the Mandae V1 API to fetch reverses/returns related to a specific tracking number or service order (OS).
• The method should return a list of reverse shipments, providing detailed information about each return event.

Tasks:

1. API Integration:

   • Query the Mandae V1 API endpoint to fetch the list of reverses based on a tracking number or OS.
   • Handle request parameters and responses, including error handling for cases such as invalid tracking numbers, no reverses found, and server errors.

2. Input Parameters:

   • Accept either a tracking number or service order (OS) as input for querying reverses.
   • Ensure proper validation of the input before making the API request.

3. Response Handling:

   • Parse the API response to extract and return relevant data, including reverse shipment status, timestamps, reason for return, and locations.
   • Format the response to make it consumable by other services or UI components.

4. Error Handling:

   • Provide meaningful error messages in case of issues such as API request failures, unauthorized requests, or invalid input.
   • Handle cases where no reverse shipments are found for the provided tracking number or OS.

Example API Call:

public async Task<List<Reverse>> GetReversesAsync(string trackingNumber)
{
    var apiUrl = $"https://api.mandae.com/v1/reverses/{trackingNumber}";
    var response = await _httpClient.GetAsync(apiUrl);

    if (!response.IsSuccessStatusCode)
    {
        // Handle error response
        throw new HttpRequestException("Failed to fetch reverses");
    }

    var reverses = await response.Content.ReadAsAsync<List<Reverse>>();
    return reverses;
}

Expected Outcome:

• Success: The method returns a list of reverse shipments, containing details such as return status, timestamps, locations, and the reason for return.
• Failure: The system provides a clear error message, indicating why the request failed (e.g., invalid tracking number, no reverses found, API issues).

Tech Notes:

• The method should be asynchronous to handle large data responses efficiently.
• API authentication should be managed securely.
• Unit tests and integration tests should cover successful scenarios and common failure cases (e.g., invalid input, no data returned).

Resources:

• Mandae V1 API Documentation: Mandae API Docs.

[gitauto-ai]

@guibranco Pull request completed! Check it out here #198 🚀

Note: I automatically create a pull request for an unassigned and open issue in order from oldest to newest once a day at 00:00 UTC, as long as you have remaining automation usage. Should you have any questions or wish to change settings or limits, please feel free to contact [email protected] or invite us to Slack Connect.