zugferd-service/.sisyphus/drafts/zugferd-service.md

Draft: ZUGFeRD-Service Implementation

Requirements (confirmed)

Core Functionality

• Purpose: Python REST API for ZUGFeRD/Factur-X invoice extraction and validation
• Framework: FastAPI (preferred by user)
• Runtime: Python 3.11+
• Deployment: Docker container on NixOS server + native Nix package

API Endpoints

1. GET /health - Health check endpoint
2. POST /extract - PDF extraction (accepts base64-encoded PDF)
3. POST /validate - Invoice validation (pflichtfelder, betraege, ustid, pdf_abgleich)

Key Dependencies

• factur-x>=2.5 - ZUGFeRD/Factur-X extraction
• pypdf>=4.0.0 - PDF text extraction
• fastapi>=0.109.0 - API framework
• uvicorn>=0.27.0 - ASGI server
• pydantic>=2.5.0 - Data models
• lxml>=5.0.0 - XML parsing
• python-multipart>=0.0.6 - File uploads

Project Structure (user-specified)

zugferd-service/
├── Dockerfile
├── requirements.txt
├── README.md
├── src/
│   ├── __init__.py
│   ├── main.py              # FastAPI App + Endpoints
│   ├── extractor.py         # ZUGFeRD/PDF Extraktion
│   ├── validator.py         # Validierungslogik
│   ├── pdf_parser.py        # PDF-Text-Parsing für Abgleich
│   ├── models.py            # Pydantic Models
│   └── utils.py             # Hilfsfunktionen
├── tests/
│   ├── __init__.py
│   ├── test_extractor.py
│   ├── test_validator.py
│   └── fixtures/
│       ├── sample_zugferd.pdf
│       └── sample_no_zugferd.pdf
└── docker-compose.yml

Research Findings

Nix Packaging (from librarian research)

• Use buildPythonApplication for standalone service
• pyproject = true with hatchling/setuptools
• pythonRelaxDeps = true for dependency flexibility
• mem0 example pattern: custom server script via postInstall
• Consider flake.nix for modern Nix workflow

factur-x Library (from librarian research)

• get_xml_from_pdf() - Core extraction function
• get_level() / get_flavor() - Profile detection
• Namespaces: rsm, ram, udt for UN/CEFACT CII format
• Profile levels: minimum, basicwl, basic, en16931, extended

UN/ECE Unit Codes

• C62 = Piece, KGM = Kilogram, H87 = Piece (alt)
• Need comprehensive mapping dictionary

Technical Decisions

Python Tooling

• PENDING: Use pyproject.toml (modern) or requirements.txt (legacy)?
• PENDING: Build system: setuptools, hatchling, or poetry-core?

Nix Approach

• PENDING: Flake-based or traditional Nix expressions?
• PENDING: Include NixOS service module?

Testing Strategy

• PENDING: TDD or tests-after?
• PENDING: Test framework: pytest (standard choice)

Scope Boundaries

INCLUDE

• All 3 API endpoints as specified
• All validation checks (pflichtfelder, betraege, ustid, pdf_abgleich)
• Docker multi-stage build
• Nix packaging
• Basic test suite
• README documentation

EXCLUDE

• Online USt-ID validation (only format check)
• Database/persistence (stateless service)
• Authentication/authorization
• Rate limiting
• Metrics/tracing

Open Questions (RESOLVED)

1. ✅ Python project structure: pyproject.toml with hatchling
2. ✅ Build system: hatchling (modern, Nix-friendly)
3. ✅ Nix approach: Flake-based
4. ✅ Testing: TDD (test-first) with pytest
5. ✅ Sample PDFs: Source from official ZUGFeRD repositories

Metis Gap Analysis (Reviewed)

Gaps Classified as MINOR (Auto-Resolved)

• UN/ECE unit codes: Start with common codes (C62, KGM, H87, MTR, LTR, etc.), expand as needed
• Tolerance: Hardcode 0.01 EUR as specified
• Validation scope: Check required fields exist for declared profile
• Error codes: Implement as specified in user's detailed spec

Gaps Classified as DEFAULTS APPLIED

• Authentication: OPEN (no auth mentioned in spec → stateless public API)
• ZUGFeRD profiles: ALL profiles supported (MINIMUM, BASIC, BASIC WL, EN16931, EXTENDED)
• Deployment: Container-based on NixOS (as per NixOS config section in spec)
• PDF text extraction: REQUIRED for pdf_abgleich check (explicitly in spec)
• File size limit: Handle as error for >10MB (spec mentions this edge case)

Guardrails (Must NOT Have)

• NO authentication middleware
• NO database/persistence
• NO caching layers
• NO rate limiting
• NO metrics endpoints (beyond /health)
• NO CLI interface
• NO web UI
• NO abstraction layers for "future extensibility"