Description

Add support to query occurrences through the Mandae V1 API, enabling the retrieval of a list of occurrences related to a specific tracking number or OS (service order). This feature is crucial for tracking the shipment status and understanding any issues or delays.

Feature Objective

• Implement a method to query the Mandae V1 API for occurrences related to a given tracking number or service order (OS).
• The method should return a list of occurrences associated with the specified tracking number or OS, providing detailed information about each occurrence.

Tasks:

1. API Integration:

   • Use the Mandae V1 API endpoint to fetch occurrences based on a tracking number or OS.
   • Handle API request and response, including error handling for scenarios such as invalid tracking numbers, no occurrences found, and server errors.

2. Query Parameters:

   • Accept either a tracking number or service order (OS) as input.
   • Validate the input format to ensure correctness before querying the API.

3. Response Handling:

   • Parse the API response to extract and return relevant occurrence data such as status, timestamps, location, and description of each occurrence.
   • Ensure the response is formatted in a way that can be easily consumed by other services or UI components.

4. Error Handling:

   • Implement proper error handling to manage cases where the API request fails (e.g., network issues, invalid inputs, unauthorized requests).
   • Return meaningful error messages to the caller in the event of failure.

Example API Call:

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

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

    var occurrences = await response.Content.ReadAsAsync<List<Occurrence>>();
    return occurrences;
}

Expected Outcome:

• Success: A list of occurrences is returned, containing details such as status updates, locations, and timestamps related to the specified tracking number or OS.
• Failure: Clear error messages indicating the cause of failure (e.g., invalid tracking number, no occurrences found, server issues).

Tech Notes:

• Ensure the method is asynchronous to handle large responses efficiently.
• API credentials and authentication should be handled securely.
• Unit tests and integration tests should be written to cover both successful and error scenarios.

Resources:

• Mandae V1 API Documentation: Mandae API Docs.