Skrift-Kofnigurator/skrift-configurator/BACKEND_INTEGRATION.md

Backend Integration - WordPress Plugin

Anleitung zur Integration des Node.js Backends mit dem WordPress Konfigurator-Plugin.

Überblick

Das WordPress Plugin kommuniziert mit dem Node.js Backend über eine REST API. Das Backend generiert die handgeschriebenen SVG-Dateien und speichert die finalen Bestellungen.

WordPress Admin-Einstellungen

Nach der Installation des Plugins in WordPress:

1. Gehe zu Einstellungen → Skrift Konfigurator
2. Scrolle nach unten zum Abschnitt "Backend-Verbindung"

Erforderliche Einstellungen

1. API URL / Domain

Beispiel: https://backend.deine-domain.de

Die vollständige URL zu deinem Backend-Server (ohne trailing slash).

• ✅ https://backend.example.com
• ✅ http://localhost:4000 (nur für lokale Tests)
• ❌ https://backend.example.com/ (kein Slash am Ende!)

2. API Token / Authentifizierung

Optional - Aktuell nicht implementiert, für zukünftige Erweiterungen vorbereitet.

Lasse dieses Feld erstmal leer.

3. Order Webhook URL

Beispiel: https://n8n.deine-domain.de/webhook/order

URL die aufgerufen wird, nachdem eine Bestellung abgeschickt wurde.

Wird aufgerufen:

• Business-Kunden: Sofort nach Klick auf "Jetzt kostenpflichtig bestellen"
• Privat-Kunden: Nach erfolgreicher PayPal-Zahlung (später implementiert)

Webhook-Payload:

{
  "orderNumber": "SK-2026-01-03-001",
  "customer_type": "business",
  "product": "businessbriefe",
  "quantity": 100,
  "format": "A4",
  "shipping_mode": "direct",
  "envelope": "yes",
  "customer_data": {
    "firstName": "Max",
    "lastName": "Mustermann",
    "company": "Beispiel GmbH",
    "email": "max@example.com",
    ...
  },
  "quote": {
    "total": 250.00,
    ...
  },
  "backend_result": {
    "path": "/var/skrift-output/SK-2026-01-03-001",
    "files": [...],
    "summary": {...}
  },
  "timestamp": "2026-01-03T..."
}

Verwendung:

• N8N Workflow triggern
• CRM-System benachrichtigen
• Interne Benachrichtigungen versenden

4. Redirect URL Geschäftskunden

Beispiel: https://deine-domain.de/danke-business

Wohin Business-Kunden nach dem Klick auf "Jetzt kostenpflichtig bestellen" weitergeleitet werden.

Query-Parameter:

• orderNumber - Die generierte Bestellnummer

Beispiel-Redirect:

https://deine-domain.de/danke-business?orderNumber=SK-2026-01-03-001

5. Redirect URL Privatkunden

Beispiel: https://deine-domain.de/danke-privat

Wohin Privat-Kunden nach erfolgreicher PayPal-Zahlung weitergeleitet werden.

Query-Parameter:

• orderNumber - Die generierte Bestellnummer

Backend-API Endpunkte

Das Plugin nutzt folgende Backend-Endpunkte:

1. Health Check

GET /health

Response:

{
  "status": "ok",
  "timestamp": "2026-01-03T..."
}

2. Preview Batch

POST /api/preview/batch

Request:

{
  "sessionId": "session-1234567890-abc",
  "letters": [
    {
      "text": "Liebe Oma, ...",
      "font": "tilda",
      "format": "A4",
      "placeholders": {},
      "envelope": null
    }
  ]
}

Response:

{
  "sessionId": "session-1234567890-abc",
  "previews": [
    {
      "index": 0,
      "url": "/api/preview/session-1234567890-abc/0"
    }
  ],
  "batchInfo": {
    "totalLetters": 1,
    "batchSize": 30
  }
}

3. Generate Order

POST /api/order/generate

Request:

{
  "orderNumber": "SK-2026-01-03-001",
  "letters": [...],
  "envelopes": [...],
  "metadata": {
    "customer": {...},
    "orderDate": "2026-01-03T..."
  }
}

Response:

{
  "orderNumber": "SK-2026-01-03-001",
  "path": "/var/skrift-output/SK-2026-01-03-001",
  "files": [
    "letter_000.svg",
    "envelope_000.svg",
    "order-metadata.json",
    "placeholders.csv"
  ],
  "summary": {
    "totalLetters": 100,
    "totalEnvelopes": 100,
    "fonts": ["tilda"],
    "formats": ["A4"]
  }
}

Workflow

Für Business-Kunden

1. Kunde füllt Konfigurator aus
2. Kunde klickt "Jetzt kostenpflichtig bestellen"
3. WordPress Plugin → Backend API (generateOrder)
4. Backend generiert SVG-Dateien
5. Backend speichert in /var/skrift-output/SK-...
6. WordPress Plugin → Webhook aufrufen
7. WordPress Plugin → Redirect zu Business-Danke-Seite

Für Privat-Kunden (später)

1. Kunde füllt Konfigurator aus
2. Kunde klickt "Jetzt kostenpflichtig bestellen"
3. WordPress Plugin → PayPal Checkout
4. PayPal → Zahlung erfolgreich
5. PayPal Webhook → WordPress
6. WordPress Plugin → Backend API (generateOrder)
7. Backend generiert SVG-Dateien
8. WordPress Plugin → Webhook aufrufen
9. WordPress Plugin → Redirect zu Privat-Danke-Seite

Datenmapping

Fonts

Frontend	Backend
tilda	tilda (PremiumUltra79)
alva	alva (PremiumUltra23)
ellie	ellie (PremiumUltra39)

Formate

Frontend	Backend
a4	A4
a6p	A6_PORTRAIT
a6l	A6_LANDSCAPE

Envelope-Formate

Brief-Format	Envelope-Format
A4	DIN_LANG
A6	C6

JavaScript Integration

API Client laden

Das Plugin lädt automatisch:

• configurator-api.js - Backend API Client
• configurator-backend-integration.js - Integration Logic

Globale Instanz

// Verfügbar in allen Konfigurator-Scripts
const api = window.SkriftBackendAPI;

// Health-Check
const isHealthy = await api.healthCheck();

// Preview generieren
const result = await api.generatePreviewBatch(letters);

// Order generieren
const order = await api.generateOrder(orderNumber, letters, envelopes, metadata);

Testing

1. Backend Health-Check

// In Browser-Console auf Konfigurator-Seite:
const api = window.SkriftBackendAPI;
const healthy = await api.healthCheck();
console.log('Backend healthy:', healthy);

2. Test-Order generieren

const api = window.SkriftBackendAPI;

const result = await api.generateOrder(
  api.generateOrderNumber(),
  [
    {
      text: 'Test Brief',
      font: 'tilda',
      format: 'A4',
      placeholders: {}
    }
  ],
  [],
  {
    customer: {
      type: 'business',
      firstName: 'Test',
      lastName: 'User',
      email: 'test@example.com'
    }
  }
);

console.log('Order result:', result);

Troubleshooting

Fehler: "Backend ist nicht erreichbar"

Lösung:

1. Prüfe Backend-URL in WordPress-Einstellungen
2. Teste Health-Check: curl https://backend.deine-domain.de/health
3. Prüfe Nginx Proxy Manager Konfiguration
4. Prüfe Backend-Container: docker compose logs -f

Fehler: "CORS Error"

Lösung: Nginx Proxy Manager muss CORS-Header setzen:

# In Custom Nginx Configuration (Advanced Tab)
add_header Access-Control-Allow-Origin "https://deine-wordpress-domain.de" always;
add_header Access-Control-Allow-Methods "GET, POST, OPTIONS" always;
add_header Access-Control-Allow-Headers "Content-Type, Authorization" always;

if ($request_method = 'OPTIONS') {
    return 204;
}

Fehler: "Order generation failed"

Lösung:

1. Prüfe Backend-Logs: docker compose logs -f
2. Prüfe /var/skrift-output Verzeichnis existiert
3. Prüfe Fonts sind vorhanden in /app/fonts
4. Prüfe .env hat SCRIPTALIZER_ERR_FREQUENCY=0

Webhook wird nicht aufgerufen

Lösung:

1. Prüfe Webhook-URL in WordPress-Einstellungen
2. Teste Webhook manuell mit curl
3. Prüfe N8N/Webhook-Service Logs
4. Webhook-Fehler werden ignoriert (soft fail) - Order wird trotzdem erstellt

Weitere Entwicklung

Preview-System (TODO)

Aktuell wird direkt die finale Order generiert. Zukünftig:

1. Kunde füllt Schritt 1-4 aus
2. Preview generieren mit /api/preview/batch
3. Kunde sieht Vorschau der Briefe
4. Kunde bestätigt → Order finalisieren mit /api/order/finalize

PayPal-Integration (TODO)

Für Privatkunden:

1. PayPal SDK laden
2. Order-ID an PayPal übergeben
3. Nach Zahlung Webhook empfangen
4. Backend-Order generieren
5. Weiterleitung

Support

Bei Problemen:

1. Browser-Console öffnen (F12)
2. Logs prüfen (nach [API] oder [Backend Integration] filtern)
3. Backend-Logs prüfen: docker compose logs -f
4. WordPress Debug-Log prüfen: wp-content/debug.log

Checkliste nach Installation

• Backend deployed und erreichbar
• Health-Check erfolgreich: https://backend.domain.de/health
• WordPress Admin-Einstellungen konfiguriert
  • API URL gesetzt
  • Order Webhook URL gesetzt (optional)
  • Redirect URLs gesetzt
• Test-Bestellung generiert
• Dateien in /var/skrift-output erstellt
• Webhook wurde aufgerufen (falls konfiguriert)
• Keine durchgestrichenen Wörter in SVGs
• Handschrift-Variationen sichtbar (Wortabstände, Rotation)