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 saves them to the specified path

Input:

{
  "file": "PDF (multipart/form-data)",
  "outputPath": string
}

Output:

{
  "success": bool,
  "extractedFiles": [
    {
      "fileName": string,
      "savedPath": string,
      "size": long
    }
  ]
}

Usage: eParser (ZUGFeRD XML extraction)

---

PdfOperationsController

Endpoint: PDF Merge

Route: POST /api/pdf/operations/merge
Function: Merges multiple PDFs into a single file

Input:

{
  "sourceFiles": string[],
  "outputPath": string
}

Output:

{
  "success": bool,
  "outputPath": string,
  "pageCount": int,
  "fileSize": long
}

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:

{
  "file": "PDF (multipart/form-data)",
  "stamp": {
    "text": string,
    "position": string,
    "pages": string,
    "color": string,
    "opacity": float
  }
}

Output:

{
  "success": bool,
  "outputPath": string
}

Usage: ErgebnisberichtCreator

---

Endpoint: PDF Annotate

Route: POST /api/pdf/operations/annotate
Function: Adds comments, highlights, and markings to the PDF

Input:

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

Output:

{
  "success": bool,
  "outputPath": string
}

Usage: signFLOW (Envelope Generator)

---

PdfRenderController

Endpoint: PDF Preview

Route: POST /api/pdf/render/preview
Function: Renders PDF pages as PNG/JPEG for preview

Input:

{
  "file": "PDF (multipart/form-data)",
  "page": int,
  "format": string,
  "dpi": int
}

Output:

{
  "images": [
    {
      "page": int,
      "base64": string,
      "width": int,
      "height": int
    }
  ]
}

Usage: taskFLOW, fileFLOW, easyFLOW, orgFLOW - PDF preview

---

PdfConversionController

Endpoint: Convert PDF to PDF/A

Route: POST /api/pdf/conversion/to-pdfa
Function: Converts a standard PDF to PDF/A

Input:

{
  "file": "PDF (multipart/form-data)",
  "pdfaLevel": string
}

Output:

{
  "success": bool,
  "outputPath": string,
  "pdfaVersion": string
}

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:

{
  "file": "PDF (multipart/form-data)"
}

Output:

{
  "success": bool,
  "outputPath": string
}

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
• Errors: HTTP Status Codes (400, 404, 500) + JSON error object
• Success: HTTP 200 + JSON response

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
2. PdfAttachmentController - both endpoints
3. PdfOperationsController - Merge endpoint

Phase 2

4. PdfOperationsController - Stamp & Annotate
5. PdfRenderController - Preview

Phase 3

6. PdfConversionController - both endpoints

---

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