From dc0af68d260e9f5889a82781f14b8281d0653480 Mon Sep 17 00:00:00 2001 From: TekH Date: Wed, 8 Jul 2026 15:46:10 +0200 Subject: [PATCH] docs: Update API specification based on Marvin/Marlon feedback MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- AGENTS.md | 31 ++++-- CONTROLLER_ENDPOINTS.md | 238 ++++++++++++++++++++-------------------- 2 files changed, 142 insertions(+), 127 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 3fc6e7b..f863516 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -177,7 +177,7 @@ All files for a feature live together. Do NOT create separate Commands/, Handler - ✅ All features currently work without authentication **When to implement:** -After completing all Phase 1-3 controllers (PdfValidation, PdfAttachment, PdfOperations, PdfRender, PdfConversion), then add multi-tenancy to ALL endpoints in one refactoring phase. +After completing all Phase 1-3 controllers (PdfValidation, PdfAttachment, SwissQrCode, PdfOperations, PdfConversion), then add multi-tenancy to ALL endpoints in one refactoring phase. --- @@ -245,30 +245,41 @@ Do NOT add `if (result.IsSuccess)` checks. Throw exceptions for errors. The midd 1. `PdfValidationController` – 2 endpoints - `POST /api/pdf/validation/validate` (Basic PDF validation) - `POST /api/pdf/validation/validate-pdfa` (PDF/A conformance) -2. `PdfAttachmentController` – 2 endpoints +2. `PdfAttachmentController` – check endpoint - `POST /api/pdf/attachments/check` (Attachment detection) - - `POST /api/pdf/attachments/extract` (Extract attachments) -3. `PdfOperationsController` – Merge endpoint +3. `SwissQrCodeController` – extract endpoint + - `POST /api/swissqrcode/extract` (Swiss QR Bill extraction) +4. `PdfAttachmentController` – extract endpoint + - `POST /api/pdf/attachments/extract` (Extract attachments as ZIP) +5. `PdfOperationsController` – merge endpoint - `POST /api/pdf/operations/merge` (Merge multiple PDFs) **Phase 2:** -4. `PdfOperationsController` – Stamp & Annotate -5. `PdfRenderController` – Preview +6. `PdfOperationsController` – stamp & annotate + - `POST /api/pdf/operations/stamp` (Add stamps) + - `POST /api/pdf/operations/annotate` (Add annotations) +7. `PdfAttachmentController` – add attachment + - `POST /api/pdf/attachments/add` (Embed attachments in PDF/A-3) **Phase 3:** -6. `PdfConversionController` – PDF ↔ PDF/A conversion +8. `PdfConversionController` – PDF ↔ PDF/A conversion + - `POST /api/pdf/conversion/to-pdfa` (Convert to PDF/A) + - `POST /api/pdf/conversion/from-pdfa` (Convert from PDF/A) + +**Removed:** +- `PdfRenderController` – Moved to .NET client library (WinForms/WPF DevExpress controls) ### Current Status | Controller | Status | Tests | |-----------|--------|-------| -| **PdfValidationController** | ⏳ Pending | 0 | +| **PdfValidationController** | ✅ Partial (validate done, validate-pdfa pending) | 4 | +| **SwissQrCodeController** | ✅ DONE | 2 | | **PdfAttachmentController** | ⏳ Pending | 0 | | **PdfOperationsController** | ⏳ Pending | 0 | -| **PdfRenderController** | ⏳ Pending | 0 | | **PdfConversionController** | ⏳ Pending | 0 | -**Legacy code exists** (`DocumentEndpoints.cs` with Minimal API + Base64 JSON), but **must be replaced** with Controllers + multipart/form-data. +**Note:** PdfRenderController removed - moved to .NET client library. --- diff --git a/CONTROLLER_ENDPOINTS.md b/CONTROLLER_ENDPOINTS.md index fc04be5..7a3dedd 100644 --- a/CONTROLLER_ENDPOINTS.md +++ b/CONTROLLER_ENDPOINTS.md @@ -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="" - 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) ---