AppStd/DocumentService
8
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Update API specification based on Marvin/Marlon feedback

Browse Source 
CONTROLLER_ENDPOINTS.md changes:

  - Binary stream output for all operations (NO outputPath, NO base64)

  - PDF Operations: merge, stamp, annotate → return application/pdf stream

  - PDF Conversion: to-pdfa, from-pdfa → return application/pdf stream

  - Attachment Extraction: extract → return application/zip stream

  - Add Attachment endpoint (Phase 2): embed files in PDF/PDF/A-3

  - Swiss QR Code endpoint documented (already implemented)

  - PdfRenderController REMOVED (moved to .NET client library)

AGENTS.md changes:

  - Current Status: SwissQrCodeController ✅ DONE (2 tests)

  - Current Status: PdfValidationController ✅ Partial (4 tests)

  - Phase reorganization:

    - Phase 1: validate, validate-pdfa, check, extract (SwissQR), extract (attachments), merge

    - Phase 2: stamp, annotate, add-attachment

    - Phase 3: to-pdfa, from-pdfa

  - Removed PdfRenderController from all phases

Design decisions (team consensus):

  - Server endpoints stay granular (validate, check, extract separate)

  - Combined operations (validateANDextract) → .NET client library

  - Binary streams avoid filesystem dependencies

  - No base64 overhead (~33%), client library handles conversions

Result: Clean API spec, memory-based operations, client convenience layer
This commit is contained in:
tekh
2026-07-08 15:46:10 +02:00
parent 45bc90b8b8
commit dc0af68d26
2 changed files with 142 additions and 127 deletions
Download Patch File Download Diff File Expand all files Collapse all files

238
CONTROLLER_ENDPOINTS.md
View File

@@ -90,34 +90,37 @@ This specification defines the controller structure and REST API endpoints for t
### Endpoint: Attachment Extraction
**Route:** `POST /api/pdf/attachments/extract`
**Function:** Extracts all embedded files from the PDF and saves them to the specified path
**Function:** Extracts all embedded files from the PDF and returns them as a ZIP archive
**Input:**
```json
{
"file": "PDF (multipart/form-data)",
"outputPath": string
}
```
- PDF file (multipart/form-data)
**Output:**
```json
{
"success": bool,
"extractedFiles": [
{
"fileName": string,
"savedPath": string,
"size": long
}
]
}
```
- 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
@@ -125,22 +128,13 @@ This specification defines the controller structure and REST API endpoints for t
**Function:** Merges multiple PDFs into a single file
**Input:**
```json
{
"sourceFiles": string[],
"outputPath": string
}
```
- Multiple PDF files (multipart/form-data)
- Field name: "files" (array of IFormFile)
**Output:**
```json
{
"success": bool,
"outputPath": string,
"pageCount": int,
"fileSize": long
}
```
- Binary stream (application/pdf)
- Content-Disposition: attachment; filename="merged.pdf"
- Merged PDF document
**Usage:** signFLOW (Envelope Generator), ErgebnisberichtCreator, ResultHandler (windream)
@@ -151,26 +145,22 @@ This specification defines the controller structure and REST API endpoints for t
**Function:** Adds stamps to PDF pages (APPROVED, CONFIDENTIAL, etc.)
**Input:**
```json
{
"file": "PDF (multipart/form-data)",
"stamp": {
- PDF file (multipart/form-data)
- Stamp configuration (JSON):
```json
{
"text": string,
"position": string,
"pages": string,
"color": string,
"opacity": float
}
}
```
```
**Output:**
```json
{
"success": bool,
"outputPath": string
}
```
- Binary stream (application/pdf)
- Content-Disposition: attachment; filename="stamped.pdf"
- PDF with applied stamps
**Usage:** ErgebnisberichtCreator
@@ -181,63 +171,75 @@ This specification defines the controller structure and REST API endpoints for t
**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
}
]
}
```
- PDF file (multipart/form-data)
- Annotations (JSON):
```json
{
"annotations": [
{
"type": string,
"page": int,
"position": object,
"text": string
}
]
}
```
**Output:**
```json
{
"success": bool,
"outputPath": string
}
```
- Binary stream (application/pdf)
- Content-Disposition: attachment; filename="annotated.pdf"
- PDF with applied annotations
**Usage:** signFLOW (Envelope Generator)
---
## PdfRenderController
## SwissQrCodeController
### Endpoint: PDF Preview
**Route:** `POST /api/pdf/render/preview`
**Function:** Renders PDF pages as PNG/JPEG for preview
### Endpoint: Swiss QR Code Extraction
**Route:** `POST /api/swissqrcode/extract`
**Function:** Extracts and parses Swiss QR Bill (Swiss QR Code) from PDF
**Input:**
```json
{
"file": "PDF (multipart/form-data)",
"page": int,
"format": string,
"dpi": int
}
```
- PDF file (multipart/form-data)
**Output:**
```json
{
"images": [
{
"page": int,
"base64": string,
"width": int,
"height": int
}
]
"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:** taskFLOW, fileFLOW, easyFLOW, orgFLOW - PDF preview
**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.
---
@@ -248,21 +250,13 @@ This specification defines the controller structure and REST API endpoints for t
**Function:** Converts a standard PDF to PDF/A
**Input:**
```json
{
"file": "PDF (multipart/form-data)",
"pdfaLevel": string
}
```
- PDF file (multipart/form-data)
- PDF/A level (query parameter): "PDF/A-1b", "PDF/A-2b", "PDF/A-3b"
**Output:**
```json
{
"success": bool,
"outputPath": string,
"pdfaVersion": string
}
```
- Binary stream (application/pdf)
- Content-Disposition: attachment; filename="converted-pdfa.pdf"
- PDF/A compliant document
**Usage:** taskFLOW (optional conversion)
@@ -273,19 +267,12 @@ This specification defines the controller structure and REST API endpoints for t
**Function:** Converts PDF/A to a standard PDF
**Input:**
```json
{
"file": "PDF (multipart/form-data)"
}
```
- PDF/A file (multipart/form-data)
**Output:**
```json
{
"success": bool,
"outputPath": string
}
```
- Binary stream (application/pdf)
- Content-Disposition: attachment; filename="converted-pdf.pdf"
- Standard PDF document
**Usage:** taskFLOW (optional conversion)
@@ -312,9 +299,21 @@ if (result.IsValid) { ... }
```
### Response Format
- Default: JSON
- 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 response
- 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`)
@@ -330,16 +329,21 @@ if (result.IsValid) { ... }
## Prioritization
### Phase 1 (Priority)
1. PdfValidationController - both endpoints
2. PdfAttachmentController - both endpoints
3. PdfOperationsController - Merge endpoint
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
4. PdfOperationsController - Stamp & Annotate
5. PdfRenderController - Preview
6. PdfOperationsController - stamp & annotate endpoints
7. PdfAttachmentController - add attachment endpoint
### Phase 3
6. PdfConversionController - both endpoints
8. PdfConversionController - both endpoints (to-pdfa, from-pdfa)
### Removed
- PdfRenderController - moved to .NET client library (WinForms/WPF DevExpress controls)
---