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

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

**Output:**
```json
{
  "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:**
```json
{
  "sourceFiles": string[],
  "outputPath": string
}
```

**Output:**
```json
{
  "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:**
```json
{
  "file": "PDF (multipart/form-data)",
  "stamp": {
    "text": string,
    "position": string,
    "pages": string,
    "color": string,
    "opacity": float
  }
}
```

**Output:**
```json
{
  "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:**
```json
{
  "file": "PDF (multipart/form-data)",
  "annotations": [
    {
      "type": string,
      "page": int,
      "position": object,
      "text": string
    }
  ]
}
```

**Output:**
```json
{
  "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:**
```json
{
  "file": "PDF (multipart/form-data)",
  "page": int,
  "format": string,
  "dpi": int
}
```

**Output:**
```json
{
  "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:**
```json
{
  "file": "PDF (multipart/form-data)",
  "pdfaLevel": string
}
```

**Output:**
```json
{
  "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:**
```json
{
  "file": "PDF (multipart/form-data)"
}
```

**Output:**
```json
{
  "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:**
```csharp
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