feat: Add raw parameter to SwissQrCodeController endpoints

- Add 'raw' query parameter to both ExtractFromFile and ExtractFromBase64 methods
- Returns raw QR text lines when raw=true, parsed Bill object when raw=false (default)
- Remove obsolete 'references' parameter (not part of QR extraction logic)
- Add XML documentation for raw parameter
- Update ExceptionHandlingMiddleware to handle BadRequestException

DocumentOperator.API/Controllers/SwissQrCodeController.cs

@@ -17,9 +17,9 @@ public class SwissQrCodeController(IMediator Mediator) : ControllerBase
     /// Extracts Swiss QR Code from the last page of a PDF document (multipart/form-data)
     /// </summary>
     /// <param name="file">PDF file containing Swiss QR Code</param>
-    /// <param name="references">Optional references (comma-separated)</param>
+    /// <param name="raw">If true, returns raw QR code text lines as string array; if false, returns parsed Bill object (default: false)</param>
     /// <param name="cancellationToken">Cancellation token</param>
-    /// <returns>Swiss QR Code data (IBAN, amount, creditor, debtor, reference, etc.)</returns>
+    /// <returns>Swiss QR Code data (IBAN, amount, creditor, debtor, reference, etc.) or raw text lines based on 'raw' parameter</returns>
     /// <response code="200">Swiss QR Code extracted successfully</response>
     /// <response code="400">Invalid PDF or file format</response>
     /// <response code="404">No Swiss QR Code found on the last page</response>
@@ -32,46 +32,39 @@ public class SwissQrCodeController(IMediator Mediator) : ControllerBase
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status500InternalServerError)]
     public async Task<IActionResult> ExtractFromFile(
         IFormFile file,
-        [FromForm] string? references,
-        CancellationToken cancellationToken)
+        [FromQuery] bool raw = false,
+        CancellationToken cancellationToken = default)
     {
-        if (file == null || file.Length == 0)
-        {
+        if (file.Length == 0)
             return BadRequest(new ProblemDetails
             {
                 Title = "Invalid file",
                 Detail = "File is required and cannot be empty",
                 Status = StatusCodes.Status400BadRequest
             });
-        }
 
         // Convert IFormFile to byte array
         using var memoryStream = new MemoryStream();
         await file.CopyToAsync(memoryStream, cancellationToken);
         byte[] pdfBytes = memoryStream.ToArray();
 
-        // Parse references (comma-separated or empty)
-        var referencesList = string.IsNullOrWhiteSpace(references)
-            ? new List<string>()
-            : references.Split(',', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries).ToList();
-
         // Direct pass-through to MediatR
         var query = new ExtractSwissQrCodeQuery 
         { 
-            PdfBytes = pdfBytes,
-            References = referencesList
+            PdfBytes = pdfBytes
         };
         var result = await Mediator.Send(query, cancellationToken);
 
-        return Ok(result);
+        return Ok(raw ? result.RawLines : result.Bill);
     }
 
     /// <summary>
     /// Extracts Swiss QR Code from the last page of a PDF document (Base64 JSON)
     /// </summary>
     /// <param name="query">References array + PDF as Base64 string</param>
+    /// <param name="raw">If true, returns raw QR code text lines as string array; if false, returns parsed Bill object (default: false)</param>
     /// <param name="cancellationToken">Cancellation token</param>
-    /// <returns>Swiss QR Code data (IBAN, amount, creditor, debtor, reference, etc.)</returns>
+    /// <returns>Swiss QR Code data (IBAN, amount, creditor, debtor, reference, etc.) or raw text lines based on 'raw' parameter</returns>
     /// <response code="200">Swiss QR Code extracted successfully</response>
     /// <response code="400">Invalid PDF or Base64 format</response>
     /// <response code="404">No Swiss QR Code found on the last page</response>
@@ -84,11 +77,12 @@ public class SwissQrCodeController(IMediator Mediator) : ControllerBase
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status500InternalServerError)]
     public async Task<IActionResult> ExtractFromBase64(
         [FromBody] ExtractSwissQrCodeQuery query,
-        CancellationToken cancellationToken)
+        [FromQuery] bool raw = false,
+        CancellationToken cancellationToken = default)
     {
         // Direct pass-through to MediatR
         var result = await Mediator.Send(query, cancellationToken);
 
-        return Ok(result);
+        return Ok(raw ? result.RawLines : result.Bill);
     }
 }