Add ZUGFeRD detection and extraction functionality

Introduced `ZugferdController` to handle ZUGFeRD-related operations, including detection and extraction of ZUGFeRD XML from PDFs via file upload or Base64-encoded payloads. Integrated `MediatR` for query/command handling.

Added `ZugferdSettings` for configurable file names and patterns, and updated `appsettings.json` and `Program.cs` to support this configuration.

Implemented `HasZugferdQuery` and `ExtractZugferdCommand` with their respective handlers and validators. Added DTOs (`ZugferdCheckResult`, `ZugferdExtractionResult`) for operation results.

Included `ZUGFeRD-Example.pdf` for testing and integrated `Serilog.Ui.Core.Extensions` for logging.

DocumentOperator.API/Controllers/ZugferdController.cs

@@ -0,0 +1,182 @@
+using DocumentOperator.Application.Common.DTOs;
+using DocumentOperator.Application.ExtractZugferd;
+using DocumentOperator.Application.HasZugferd.Queries;
+using DocumentOperator.Domain.Common.Exceptions;
+using MediatR;
+using Microsoft.AspNetCore.Http;
+using Microsoft.AspNetCore.Mvc;
+
+namespace DocumentOperator.API.Controllers;
+
+/// <summary>
+/// Controller for ZUGFeRD operations (detection, extraction)
+/// </summary>
+[ApiController]
+[Route("api/pdf/zugferd")]
+[Produces("application/json")]
+public class ZugferdController(IMediator mediator) : ControllerBase
+{
+    /// <summary>
+    /// Checks if a PDF contains ZUGFeRD XML attachment.
+    /// Supports multipart/form-data file upload.
+    /// </summary>
+    /// <param name="file">The PDF file to check for ZUGFeRD</param>
+    /// <param name="cancellationToken">Cancellation token</param>
+    /// <returns>ZUGFeRD check result with metadata</returns>
+    /// <response code="200">PDF successfully checked - returns ZUGFeRD status</response>
+    /// <response code="400">Invalid input (file missing, not a PDF, or corrupted)</response>
+    /// <response code="500">Internal server error during PDF processing</response>
+    [HttpPost("has-zugferd")]
+    [Consumes("multipart/form-data")]
+    [ProducesResponseType(typeof(ZugferdCheckResult), StatusCodes.Status200OK)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status400BadRequest)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status500InternalServerError)]
+    public async Task<IActionResult> HasZugferdFromFile(
+        IFormFile file,
+        CancellationToken cancellationToken)
+    {
+        // Use IFormFile stream directly (no intermediate byte[] conversion)
+        using var pdfStream = file.OpenReadStream();
+
+        // Send query to MediatR (ValidationBehavior runs automatically)
+        var query = new HasZugferdQuery { PdfStream = pdfStream };
+        var result = await mediator.Send(query, cancellationToken);
+
+        return Ok(result);
+    }
+
+    /// <summary>
+    /// Checks if a PDF contains ZUGFeRD XML attachment.
+    /// Supports Base64-encoded PDF via JSON payload.
+    /// </summary>
+    /// <param name="request">Request containing Base64-encoded PDF</param>
+    /// <param name="cancellationToken">Cancellation token</param>
+    /// <returns>ZUGFeRD check result with metadata</returns>
+    /// <response code="200">PDF successfully checked - returns ZUGFeRD status</response>
+    /// <response code="400">Invalid input (Base64 format error, not a PDF, or corrupted)</response>
+    /// <response code="500">Internal server error during PDF processing</response>
+    [HttpPost("has-zugferd")]
+    [Consumes("application/json")]
+    [ProducesResponseType(typeof(ZugferdCheckResult), StatusCodes.Status200OK)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status400BadRequest)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status500InternalServerError)]
+    public async Task<IActionResult> HasZugferdFromBase64(
+        [FromBody] HasZugferdRequest request,
+        CancellationToken cancellationToken)
+    {
+        // Convert Base64 to stream (wrap in try-catch to throw BadRequestException)
+        byte[] pdfBytes;
+        try
+        {
+            pdfBytes = Convert.FromBase64String(request.Base64Pdf);
+        }
+        catch (FormatException ex)
+        {
+            throw new BadRequestException("Invalid Base64 format: " + ex.Message);
+        }
+        
+        using var pdfStream = new MemoryStream(pdfBytes);
+        
+        // Send query to MediatR (ValidationBehavior runs automatically)
+        var query = new HasZugferdQuery { PdfStream = pdfStream };
+        var result = await mediator.Send(query, cancellationToken);
+
+        return Ok(result);
+    }
+
+    /// <summary>
+    /// Extracts ZUGFeRD XML from a PDF document.
+    /// Supports multipart/form-data file upload.
+    /// </summary>
+    /// <param name="file">The PDF file to extract ZUGFeRD from</param>
+    /// <param name="cancellationToken">Cancellation token</param>
+    /// <returns>ZUGFeRD XML content and metadata</returns>
+    /// <response code="200">ZUGFeRD XML extracted successfully</response>
+    /// <response code="400">Invalid input (file missing, not a PDF, or corrupted)</response>
+    /// <response code="404">PDF contains no ZUGFeRD XML</response>
+    /// <response code="500">Internal server error during PDF processing</response>
+    [HttpPost("extract")]
+    [Consumes("multipart/form-data")]
+    [ProducesResponseType(typeof(ZugferdExtractionResult), StatusCodes.Status200OK)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status400BadRequest)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status500InternalServerError)]
+    public async Task<IActionResult> ExtractZugferdFromFile(
+        IFormFile file,
+        CancellationToken cancellationToken)
+    {
+        // Use IFormFile stream directly (no intermediate byte[] conversion)
+        using var pdfStream = file.OpenReadStream();
+
+        // Send command to MediatR
+        var command = new ExtractZugferdCommand { PdfStream = pdfStream };
+        var result = await mediator.Send(command, cancellationToken);
+
+        return Ok(result);
+    }
+
+    /// <summary>
+    /// Extracts ZUGFeRD XML from a PDF document.
+    /// Supports Base64-encoded PDF via JSON payload.
+    /// </summary>
+    /// <param name="request">Request containing Base64-encoded PDF</param>
+    /// <param name="cancellationToken">Cancellation token</param>
+    /// <returns>ZUGFeRD XML content and metadata</returns>
+    /// <response code="200">ZUGFeRD XML extracted successfully</response>
+    /// <response code="400">Invalid input (Base64 format error, not a PDF, or corrupted)</response>
+    /// <response code="404">PDF contains no ZUGFeRD XML</response>
+    /// <response code="500">Internal server error during PDF processing</response>
+    [HttpPost("extract")]
+    [Consumes("application/json")]
+    [ProducesResponseType(typeof(ZugferdExtractionResult), StatusCodes.Status200OK)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status400BadRequest)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status500InternalServerError)]
+    public async Task<IActionResult> ExtractZugferdFromBase64(
+        [FromBody] ExtractZugferdRequest request,
+        CancellationToken cancellationToken)
+    {
+        // Convert Base64 to stream (wrap in try-catch to throw BadRequestException)
+        byte[] pdfBytes;
+        try
+        {
+            pdfBytes = Convert.FromBase64String(request.Base64Pdf);
+        }
+        catch (FormatException ex)
+        {
+            throw new BadRequestException("Invalid Base64 format: " + ex.Message);
+        }
+        
+        using var pdfStream = new MemoryStream(pdfBytes);
+
+        // Send command to MediatR
+        var command = new ExtractZugferdCommand { PdfStream = pdfStream };
+        var result = await mediator.Send(command, cancellationToken);
+
+        return Ok(result);
+    }
+}
+
+/// <summary>
+/// Request DTO for Base64-encoded PDF ZUGFeRD check
+/// </summary>
+public record HasZugferdRequest
+{
+    /// <summary>
+    /// PDF document encoded as Base64 string
+    /// </summary>
+    /// <example>JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PC9UeXBlL0NhdGFsb2c...</example>
+    public string Base64Pdf { get; init; } = string.Empty;
+}
+
+/// <summary>
+/// Request DTO for Base64-encoded PDF ZUGFeRD extraction
+/// </summary>
+public record ExtractZugferdRequest
+{
+    /// <summary>
+    /// PDF document encoded as Base64 string
+    /// </summary>
+    /// <example>JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PC9UeXBlL0NhdGFsb2c...</example>
+    public required string Base64Pdf { get; init; }
+}

DocumentOperator.API/Program.cs

@@ -5,6 +5,7 @@ using Serilog.Ui.Web.Extensions;
 using Scalar.AspNetCore;
 using DocumentOperator.Infrastructure.Configuration;
 using DocumentOperator.Application;
+using DocumentOperator.Application.Common.Configuration;
 using DocumentOperator.Infrastructure;
 using DocumentOperator.API.Middleware;
 using DocumentOperator.API.Configuration;
@@ -32,6 +33,9 @@ try
     builder.Services.Configure<DocumentOperatorSettings>(
         builder.Configuration.GetSection(DocumentOperatorSettings.SectionName));
 
+    builder.Services.Configure<ZugferdSettings>(
+        builder.Configuration.GetSection("ZugferdSettings"));
+
     builder.Services.Configure<RedisSettings>(
         builder.Configuration.GetSection(RedisSettings.SectionName));
 

DocumentOperator.API/appsettings.json

@@ -61,6 +61,22 @@
     "EnableDetailedLogging": true
   },
 
+  "ZugferdSettings": {
+    "ZugferdFileNames": [
+      "factur-x.xml",
+      "zugferd-invoice.xml",
+      "ZUGFeRD-invoice.xml",
+      "xrechnung.xml",
+      "XRechnung.xml"
+    ],
+    "ZugferdFileNamePatterns": [
+      "factur",
+      "zugferd",
+      "xrechnung",
+      "peppol"
+    ]
+  },
+
   "RedisSettings": {
     "ConnectionString": "localhost:6379",
     "InstanceName": "DocumentOperator:",