Skrift-Kofnigurator/Docker Backend/TILDA_API_BEISPIEL.md

# Tilda Font API-Aufruf Beispiel

## Konfiguration
- **Error Frequency:** 0 (keine durchgestrichenen Wörter)
- **Wortabstand-Variation:** ±5% für natürlicheres Schriftbild
- **Font:** Tilda (Scriptalizer: PremiumUltra79)

---

## 1. Preview-Generierung (empfohlen)

### Endpoint
```
POST http://localhost:4000/api/preview/batch
```

### Request Headers
```
Content-Type: application/json
```

### Request Body
```json
{
  "sessionId": "meine-session-12345",
  "letters": [
    {
      "index": 0,
      "format": "a4",
      "font": "tilda",
      "text": "Sehr geehrte Damen und Herren,\n\nhiermit möchten wir Ihnen mitteilen, dass Ihre Bestellung erfolgreich bearbeitet wurde.\n\nWir bedanken uns für Ihr Vertrauen und freuen uns auf eine weitere Zusammenarbeit.\n\nMit freundlichen Grüßen\nIhr Skrift-Team",
      "placeholders": {}
    }
  ]
}
```

### cURL Beispiel
```bash
curl -X POST http://localhost:4000/api/preview/batch \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "meine-session-12345",
    "letters": [
      {
        "index": 0,
        "format": "a4",
        "font": "tilda",
        "text": "Sehr geehrte Damen und Herren,\n\nhiermit möchten wir Ihnen mitteilen, dass Ihre Bestellung erfolgreich bearbeitet wurde.\n\nWir bedanken uns für Ihr Vertrauen und freuen uns auf eine weitere Zusammenarbeit.\n\nMit freundlichen Grüßen\nIhr Skrift-Team",
        "placeholders": {}
      }
    ]
  }'
```

### Response
```json
{
  "sessionId": "meine-session-12345",
  "files": [
    {
      "index": 0,
      "filename": "letter_000.svg",
      "url": "/api/preview/meine-session-12345/letter_000.svg"
    }
  ],
  "csvUrl": "/api/preview/meine-session-12345/placeholders.csv"
}
```

### Preview SVG abrufen
```bash
curl http://localhost:4000/api/preview/meine-session-12345/letter_000.svg -o preview.svg
```

---

## 2. Mit Platzhaltern

### Request Body
```json
{
  "sessionId": "platzhalter-test",
  "letters": [
    {
      "index": 0,
      "format": "a4",
      "font": "tilda",
      "text": "Sehr geehrte/r [[Vorname]] [[Nachname]],\n\nhiermit bestätigen wir Ihre Bestellung [[Bestellnummer]].\n\nIhr persönlicher Gutscheincode: [[Gutscheincode]]\nGültig bis: [[Ablaufdatum]]\n\nMit freundlichen Grüßen",
      "placeholders": {
        "Vorname": "Max",
        "Nachname": "Mustermann",
        "Bestellnummer": "SK-2026-001",
        "Gutscheincode": "SAVE20",
        "Ablaufdatum": "31.12.2026"
      }
    }
  ]
}
```

---

## 3. Mehrere Briefe (Batch)

### Request Body
```json
{
  "sessionId": "batch-test",
  "letters": [
    {
      "index": 0,
      "format": "a4",
      "font": "tilda",
      "text": "Sehr geehrte/r [[Vorname]] [[Nachname]],\n\nvielen Dank für Ihre Bestellung!",
      "placeholders": {
        "Vorname": "Max",
        "Nachname": "Mustermann"
      }
    },
    {
      "index": 1,
      "format": "a4",
      "font": "tilda",
      "text": "Sehr geehrte/r [[Vorname]] [[Nachname]],\n\nvielen Dank für Ihre Bestellung!",
      "placeholders": {
        "Vorname": "Anna",
        "Nachname": "Schmidt"
      }
    },
    {
      "index": 2,
      "format": "a4",
      "font": "tilda",
      "text": "Sehr geehrte/r [[Vorname]] [[Nachname]],\n\nvielen Dank für Ihre Bestellung!",
      "placeholders": {
        "Vorname": "Thomas",
        "Nachname": "Müller"
      }
    }
  ]
}
```

**Hinweis:** Bis zu 30 Briefe pro Batch möglich (konfigurierbar)

---

## 4. Bestellung finalisieren

Nach der Vorschau kann die Bestellung finalisiert werden:

### Endpoint
```
POST http://localhost:4000/api/order/finalize
```

### Request Body
```json
{
  "sessionId": "meine-session-12345",
  "orderNumber": "SK-2026-01-02-001"
}
```

### cURL Beispiel
```bash
curl -X POST http://localhost:4000/api/order/finalize \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "meine-session-12345",
    "orderNumber": "SK-2026-01-02-001"
  }'
```

### Response
```json
{
  "orderNumber": "SK-2026-01-02-001",
  "outputPath": "/app/output/SK-2026-01-02-001",
  "files": [
    "letter_000.svg",
    "placeholders.csv"
  ],
  "timestamp": "2026-01-02T09:11:00.000Z"
}
```

---

## 5. Direkte Bestellungs-Generierung (ohne Preview)

### Endpoint
```
POST http://localhost:4000/api/order/generate
```

### Request Body
```json
{
  "orderNumber": "SK-2026-01-02-002",
  "letters": [
    {
      "index": 0,
      "format": "a4",
      "font": "tilda",
      "text": "Sehr geehrte Damen und Herren,\n\nhiermit bestätigen wir den Eingang Ihrer Bestellung.\n\nMit freundlichen Grüßen",
      "placeholders": {}
    }
  ]
}
```

### cURL Beispiel
```bash
curl -X POST http://localhost:4000/api/order/generate \
  -H "Content-Type: application/json" \
  -d '{
    "orderNumber": "SK-2026-01-02-002",
    "letters": [
      {
        "index": 0,
        "format": "a4",
        "font": "tilda",
        "text": "Sehr geehrte Damen und Herren,\n\nhiermit bestätigen wir den Eingang Ihrer Bestellung.\n\nMit freundlichen Grüßen",
        "placeholders": {}
      }
    ]
  }'
```

---

## Verfügbare Formate

- **a4**: A4 Hochformat (210 × 297 mm)
- **a6p**: A6 Hochformat (105 × 148 mm)
- **a6l**: A6 Querformat (148 × 105 mm)

---

## Verfügbare Fonts

- **tilda**: Scriptalizer PremiumUltra79
- **alva**: Scriptalizer PremiumUltra23
- **ellie**: Scriptalizer PremiumUltra39

---

## Features

✅ **Keine Fehler:** Error Frequency = 0 (keine durchgestrichenen Wörter)
✅ **Wortabstand-Variation:** ±5% natürliche Variation für realistischeres Schriftbild
✅ **Platzhalter:** Automatische Ersetzung von [[Platzhalter]]
✅ **CSV-Export:** Automatische Generierung der Platzhalter-Tabelle
✅ **Batch-Verarbeitung:** Bis zu 30 Briefe pro Request
✅ **Preview-Caching:** 2 Stunden Cache für schnellere Finalisierung
✅ **Rate Limiting:** 2 Requests/Minute Schutz

---

## Output

Die generierten SVG-Dateien befinden sich in:
- **Preview:** `/app/cache/previews/{sessionId}/`
- **Finale Bestellung:** `/app/output/{orderNumber}/`

Struktur:
```
output/SK-2026-01-02-001/
├── letter_000.svg
├── letter_001.svg
├── placeholders.csv
└── order-metadata.json
```

---

## Beispiel Output

**letter_000.svg:**
```xml
<svg xmlns="http://www.w3.org/2000/svg"
     width="210mm"
     height="297mm"
     viewBox="0 0 793.8 1122.66">
  <rect x="0" y="0" width="793.8" height="1122.66" fill="#FFFFFF" />
  <path d="M1549 1857q-55 73 -124.5 125..."
        transform="matrix(0.00846,0,0,-0.00846,75.6,120.5)"
        stroke="#000000"
        stroke-width="0.6"
        fill="none"
        stroke-linecap="round"
        stroke-linejoin="round" />
  <!-- ~2000 weitere Pfade für handgeschriebenen Text -->
</svg>
```

Dateigröße: ~100-120 KB pro A4-Seite

---

## WordPress Integration Beispiel

```javascript
// Im WordPress Plugin
const response = await fetch('https://api.skrift.de/api/preview/batch', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    sessionId: generateUUID(),
    letters: [
      {
        index: 0,
        format: 'a4',
        font: 'tilda',
        text: brieftext,
        placeholders: platzhalterDaten
      }
    ]
  })
});

const data = await response.json();
// Zeige Preview: data.files[0].url
```

---

**Stand:** 2026-01-02
**Version:** 1.0.0