QR-Invoice Service

Swiss QR-Bill PDF Generation Service für Schweizer Zahlscheine nach SIX-Spezifikation.

Projektübersicht

Ein Node.js/TypeScript HTTP-Service, der JSON-Daten über einen Webhook empfängt und eine PDF mit Swiss QR-Zahlteil generiert.

Tech Stack

Runtime: Node.js 18+
Sprache: TypeScript
HTTP Framework: Fastify 4
PDF-Generierung: swissqrbill + pdfkit
Validierung: Zod

Projektstruktur

src/
├── index.ts              # Entry Point, startet Server
├── app.ts                # Fastify App Konfiguration
├── config/index.ts       # Umgebungsvariablen (PORT, HOST, LOG_LEVEL)
├── types/                # TypeScript Interfaces
├── schemas/              # Zod Validierungsschemas
├── services/             # Business Logic (QR-Bill Generierung)
├── routes/               # API Endpoints
└── errors/               # Error Handler

Wichtige Befehle

npm run dev       # Entwicklungsserver mit Hot-Reload (tsx watch)
npm run build     # TypeScript kompilieren nach dist/
npm run start     # Produktionsserver starten
npm run typecheck # TypeScript Typprüfung

API Endpoints

Method	Path	Beschreibung
POST	`/api/v1/invoice/qr-bill`	Generiert QR-Bill PDF
GET	`/health`	Health Check
GET	`/health/ready`	Readiness Probe

Request Format (POST /api/v1/invoice/qr-bill)

{
  "creditor": {
    "iban": "CH4431999123000889012",
    "address": {
      "name": "Firma AG",
      "street": "Strasse",
      "buildingNumber": "123",
      "postalCode": "8000",
      "city": "Zürich",
      "country": "CH"
    }
  },
  "amount": 1949.75,
  "currency": "CHF",
  "reference": {
    "type": "QRR",
    "value": "210000000003139471430009017"
  },
  "debtor": {
    "address": { ... }
  },
  "additionalInformation": {
    "message": "Rechnung Nr. 123"
  },
  "options": {
    "language": "de",
    "separate": true
  }
}

Validierungsregeln (SIX-Spezifikation)

QRR (QR-Referenz): 27 Ziffern, Modulo 10 rekursiv, erfordert QR-IBAN (IID 30000-31999)
SCOR (Creditor Reference): ISO 11649, erfordert normale IBAN
NON (Ohne Referenz): Erfordert normale IBAN
Strukturierte Adressen: Pflicht seit November 2025
Betrag: 0.01 - 999'999'999.99, max. 2 Dezimalstellen
Währung: CHF oder EUR

Umgebungsvariablen

Variable	Default	Beschreibung
PORT	3000	Server Port
HOST	0.0.0.0	Server Host
LOG_LEVEL	info	Pino Log Level

Testen

# Server starten
npm run dev

# Test-Request senden
curl -X POST http://localhost:3000/api/v1/invoice/qr-bill \
  -H "Content-Type: application/json" \
  -d @test-request.json \
  -o output.pdf

Wichtige Dateien

src/schemas/qr-invoice.schema.ts - Zod Schema mit Cross-Validation für IBAN/Referenz
src/services/qr-bill.service.ts - PDF-Generierung mit swissqrbill
src/routes/invoice.routes.ts - API Endpoint Implementation
test-request.json - Beispiel-Request für Tests

Repository

Gitea: https://git.tradeo.de/mehmed/QR-Invoice.git

Deploy auf neuem Server

git clone https://git.tradeo.de/mehmed/QR-Invoice.git
cd QR-Invoice
docker compose up -d

Service läuft dann auf Port 3050.

Hinweis Docker Health Check: 127.0.0.1 statt localhost verwenden — Alpine Linux löst localhost als IPv6 ([::1]) auf, die App hört aber nur auf IPv4.

3.7 KiB Raw Permalink Blame History