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:

{
  "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:

{
  "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:

{
  "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):

  {
    "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):

  {
    "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:

{
  "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:

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=""
• 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