DocumentService/CONTROLLER_ENDPOINTS.md

# DocumentOperator - Controller & Endpoint Specification

**Project:** DocumentService (DOC)  
**Ticket:** DOC-1 - GDPicture and Nutrient Replacing  
**Owner:** Hakan Tek  
**Date:** July 3, 2026

---

## Overview

This specification defines the controller structure and REST API endpoints for the DocumentOperator service.

---

## PdfValidationController

### Endpoint: PDF Validation
**Route:** `POST /api/pdf/validation/validate`  
**Function:** Checks whether the file is a valid PDF, whether it is corrupted, and returns basic information

**Input:**
- PDF file (multipart/form-data)

**Output:**
```json
{
  "isValid": bool,
  "pdfVersion": string,
  "pageCount": int,
  "fileSize": long,
  "encrypted": bool,
  "errors": string[]
}
```

**Usage:** All products - basic PDF input check

---

### Endpoint: PDF/A Validation
**Route:** `POST /api/pdf/validation/validate-pdfa`  
**Function:** PDF/A conformance check (embedded fonts, encryption, JavaScript, etc.)

**Input:**
- PDF file (multipart/form-data)

**Output:**
```json
{
  "isValid": bool,
  "pdfaVersion": string,
  "pageCount": int,
  "errors": string[],
  "warnings": string[]
}
```

**Usage:** taskFLOW, eParser - ensuring PDF/A conformance

---

## PdfAttachmentController

### Endpoint: Attachment Check
**Route:** `POST /api/pdf/attachments/check`  
**Function:** Detects whether embedded files (e.g. ZUGFeRD XML) are present in the PDF

**Input:**
- PDF file (multipart/form-data)

**Output:**
```json
{
  "hasAttachments": bool,
  "attachmentCount": int,
  "attachments": [
    {
      "fileName": string,
      "mimeType": string,
      "size": long
    }
  ]
}
```

**Usage:** eParser (ZUGFeRD), ErgebnisberichtCreator

---

### Endpoint: Attachment Extraction
**Route:** `POST /api/pdf/attachments/extract`  
**Function:** Extracts all embedded files from the PDF and returns them as a ZIP archive

**Input:**
- PDF file (multipart/form-data)

**Output:**
- Binary stream (application/zip)
- Content-Disposition: attachment; filename="attachments.zip"
- ZIP archive containing all extracted files

**Usage:** eParser (ZUGFeRD XML extraction)

---

### Endpoint: Add Attachment
**Route:** `POST /api/pdf/attachments/add`  
**Function:** Embeds one or more files as attachments in a PDF (supports PDF/A-3)

**Input:**
- PDF file (multipart/form-data)
- Attachment files (multipart/form-data, multiple)

**Output:**
- Binary stream (application/pdf)
- Content-Disposition: attachment; filename="with-attachments.pdf"
- PDF with embedded attachments

**Usage:** eParser (ZUGFeRD XML embedding), PDF/A-3 archiving

---

## PdfOperationsController

### Endpoint: PDF Merge
**Route:** `POST /api/pdf/operations/merge`  
**Function:** Merges multiple PDFs into a single file

**Input:**
- Multiple PDF files (multipart/form-data)
- Field name: "files" (array of IFormFile)

**Output:**
- Binary stream (application/pdf)
- Content-Disposition: attachment; filename="merged.pdf"
- Merged PDF document

**Usage:** signFLOW (Envelope Generator), ErgebnisberichtCreator, ResultHandler (windream)

---

### Endpoint: PDF Stamp
**Route:** `POST /api/pdf/operations/stamp`  
**Function:** Adds stamps to PDF pages (APPROVED, CONFIDENTIAL, etc.)

**Input:**
- PDF file (multipart/form-data)
- Stamp configuration (JSON):
  ```json
  {
    "text": string,
    "position": string,
    "pages": string,
    "color": string,
    "opacity": float
  }
  ```

**Output:**
- Binary stream (application/pdf)
- Content-Disposition: attachment; filename="stamped.pdf"
- PDF with applied stamps

**Usage:** ErgebnisberichtCreator

---

### Endpoint: PDF Annotate
**Route:** `POST /api/pdf/operations/annotate`  
**Function:** Adds comments, highlights, and markings to the PDF

**Input:**
- PDF file (multipart/form-data)
- Annotations (JSON):
  ```json
  {
    "annotations": [
      {
        "type": string,
        "page": int,
        "position": object,
        "text": string
      }
    ]
  }
  ```

**Output:**
- Binary stream (application/pdf)
- Content-Disposition: attachment; filename="annotated.pdf"
- PDF with applied annotations

**Usage:** signFLOW (Envelope Generator)

---

## SwissQrCodeController

### Endpoint: Swiss QR Code Extraction
**Route:** `POST /api/swissqrcode/extract`  
**Function:** Extracts and parses Swiss QR Bill (Swiss QR Code) from PDF

**Input:**
- PDF file (multipart/form-data)

**Output:**
```json
{
  "qrType": "SwissQrBill",
  "version": "0200",
  "creditorIban": "CH4431999123000889012",
  "creditorName": "Example AG",
  "creditorAddress": {
    "addressType": "Structured",
    "street": "Musterstrasse",
    "houseNumber": "1",
    "postalCode": "8000",
    "city": "Zürich",
    "country": "CH"
  },
  "amount": 1234.56,
  "currency": "CHF",
  "debtorName": "Max Mustermann",
  "debtorAddress": { ... },
  "referenceType": "QRR",
  "reference": "210000000003139471430009017",
  "unstructuredMessage": "Invoice #12345",
  "billInformation": "//S1/10/12345",
  "alternativeProcedures": ["UV1", "UV2"]
}
```

**Usage:** eParser (Swiss QR Bill processing), signFLOW (payment reference extraction)

**Note:** Supports only Structured Address (S-Type) as per Swiss QR Bill Standard 2.0. Combined Address (K-Type) deprecated November 21, 2025.

---

## PdfRenderController

**Status:** REMOVED - PDF preview functionality will be implemented in .NET client library using DevExpress WinForms/WPF controls. Server-side rendering is unnecessary CPU/memory overhead.

---

## PdfConversionController

### Endpoint: Convert PDF to PDF/A
**Route:** `POST /api/pdf/conversion/to-pdfa`  
**Function:** Converts a standard PDF to PDF/A

**Input:**
- PDF file (multipart/form-data)
- PDF/A level (query parameter): "PDF/A-1b", "PDF/A-2b", "PDF/A-3b"

**Output:**
- Binary stream (application/pdf)
- Content-Disposition: attachment; filename="converted-pdfa.pdf"
- PDF/A compliant document

**Usage:** taskFLOW (optional conversion)

---

### Endpoint: Convert PDF/A to PDF
**Route:** `POST /api/pdf/conversion/from-pdfa`  
**Function:** Converts PDF/A to a standard PDF

**Input:**
- PDF/A file (multipart/form-data)

**Output:**
- Binary stream (application/pdf)
- Content-Disposition: attachment; filename="converted-pdf.pdf"
- Standard PDF document

**Usage:** taskFLOW (optional conversion)

---

## Technical Specifications

### Framework Support
- ✓ .NET Core (3.1+, 6.0+, 8.0+)
- ✓ .NET Framework (4.7.2+, 4.8+)

### Client Usage
The service can be used on the client side **without manual HTTP response handling**:
- Provide REST client wrapper
- SDK for C# clients
- Automatic serialization/deserialization
- Abstracted error handling

**Example Client SDK:**
```csharp
var client = new DocumentOperatorClient("https://api.example.com");
var result = await client.Pdf.Validation.ValidateAsync(pdfFile);
if (result.IsValid) { ... }
```

### Response Format
- Default: JSON (for metadata endpoints like validation, check)
- Binary streams: application/pdf, application/zip (for operations, conversion, extraction)
- Content-Disposition header: attachment; filename="<output-filename>"
- Errors: HTTP Status Codes (400, 404, 500) + JSON error object
- Success: HTTP 200 + JSON/Binary response

**Binary Stream Endpoints:**
- PDF Operations: merge, stamp, annotate
- PDF Conversion: to-pdfa, from-pdfa
- Attachment Operations: extract (ZIP), add (PDF)

**JSON Response Endpoints:**
- PDF Validation: validate, validate-pdfa
- Attachment Check: check
- Swiss QR Code: extract

### Authentication
- API Key (Header: `X-API-Key`)
- Optional: OAuth2/JWT for advanced scenarios

### Swagger/OpenAPI
- Complete API documentation
- Interactive test UI
- Code generation for clients

---

## Prioritization

### Phase 1 (Priority)
1. PdfValidationController - both endpoints (validate, validate-pdfa)
2. PdfAttachmentController - check endpoint
3. SwissQrCodeController - extract endpoint (already implemented)
4. PdfAttachmentController - extract endpoint
5. PdfOperationsController - merge endpoint

### Phase 2
6. PdfOperationsController - stamp & annotate endpoints
7. PdfAttachmentController - add attachment endpoint

### Phase 3
8. PdfConversionController - both endpoints (to-pdfa, from-pdfa)

### Removed
- PdfRenderController - moved to .NET client library (WinForms/WPF DevExpress controls)

---

**Last Updated:** July 3, 2026  
**Author:** Hakan Tek  
**Status:** Draft - Awaiting Feedback