# GrafikFusion API für Textildruckaufträge

Mit dieser Schnittstelle können Sie Textildruckaufträge direkt und sicher an GrafikFusion übermitteln. Nach erfolgreicher Übertragung erhalten Sie eine eindeutige GrafikFusion-Auftragsnummer.

## 1. Zugangsdaten

Sie erhalten von GrafikFusion:

- die API-Adresse;
- einen geheimen API-Schlüssel;
- diese Dokumentation und eine JSON-Vorlage.

API-Adresse:

```text
https://dashboard.grafikfusion.de/api/external/textile-orders
```

Der API-Schlüssel muss bei jeder Anfrage als HTTP-Header übertragen werden:

```text
X-API-Key: IHR_API_SCHLUESSEL
```

Alternativ wird ein Bearer-Token unterstützt:

```text
Authorization: Bearer IHR_API_SCHLUESSEL
```

Der API-Schlüssel ist vertraulich und darf nicht öffentlich, im Browser-Quelltext oder in frei zugänglichen Dateien gespeichert werden. Die Übertragung sollte aus Ihrem Server oder Warenwirtschaftssystem erfolgen.

## 2. Anfrage

- Methode: `POST`
- Content-Type: `application/json`
- Zeichenkodierung: UTF-8

Beispiel mit curl:

```bash
curl --request POST \
  --url "https://dashboard.grafikfusion.de/api/external/textile-orders" \
  --header "Content-Type: application/json" \
  --header "X-API-Key: IHR_API_SCHLUESSEL" \
  --data @textile-order.json
```

## 3. Vollständiges JSON-Beispiel

```json
{
  "external_reference": "IHR-SYSTEM-2026-000123",
  "customer": {
    "number": "K-10025",
    "name": "Musterfirma GmbH",
    "contact": "Max Mustermann",
    "role": "Einkauf",
    "phone": "+49 123 456789",
    "email": "max@beispiel.de",
    "address": "Musterstraße 1, 12345 Musterstadt",
    "notes": "Anlieferung nur vormittags"
  },
  "due_date": "2026-07-31",
  "status": "Offener Auftrag",
  "mockup": "",
  "items": [
    {
      "product": "Creator 2.0 T-Shirt",
      "sku": "STTU169",
      "supplier": "Stanley/Stella",
      "color": "Black",
      "sizes": {
        "S": 5,
        "M": 10,
        "L": 8,
        "XL": 4,
        "2XL": 2
      },
      "needs_purchase": true,
      "placements": [
        "Brust klein links",
        "Rücken groß"
      ],
      "print_dimensions": "Brust 10 × 8 cm; Rücken 28 × 35 cm",
      "production_notes": "Logo auf der Brust, Motiv groß auf dem Rücken",
      "proofs": []
    }
  ]
}
```

## 4. Felder des Auftrags

### Auftragsdaten

| Feld | Pflicht | Beschreibung |
|---|---:|---|
| `external_reference` | Ja | Eindeutige Auftragskennung aus Ihrem System, maximal 120 Zeichen. Sie verhindert Doppelübertragungen. |
| `customer` | Ja | Kunden- und Kontaktdaten. |
| `due_date` | Nein | Gewünschter Liefertermin im Format `YYYY-MM-DD`. |
| `status` | Ja | Für neue Aufträge normalerweise `Offener Auftrag`. |
| `mockup` | Nein | Allgemeiner Korrekturabzug als Data-URL oder eine leere Zeichenfolge. |
| `items` | Ja | Liste mit mindestens einer Textilposition, maximal 50 Positionen. |

### Kundendaten

| Feld | Pflicht | Beschreibung |
|---|---:|---|
| `number` | Nein | Ihre Kundennummer. Ein vorhandener Kunde kann darüber erkannt werden. |
| `name` | Ja bei Neukunden | Firma oder Kundenname. |
| `contact` | Nein | Ansprechpartner. |
| `role` | Nein | Funktion des Ansprechpartners. |
| `phone` | Nein | Telefonnummer. |
| `email` | Empfohlen | E-Mail-Adresse und zusätzliches Erkennungsmerkmal. |
| `address` | Nein | Rechnungs- oder Lieferanschrift. |
| `notes` | Nein | Wichtige dauerhafte Kundenhinweise. |

Vorhandene Kunden werden nacheinander über Kundennummer, E-Mail-Adresse oder exakten Namen gesucht. Wird kein Treffer gefunden, legt GrafikFusion einen neuen Kunden an.

### Textilpositionen

| Feld | Pflicht | Beschreibung |
|---|---:|---|
| `product` | Ja | Modell- oder Produktbezeichnung. |
| `sku` | Nein | Artikelnummer des Textils. |
| `supplier` | Ja | Exakter Händlername aus der GrafikFusion-Händlerliste. |
| `color` | Ja | Farbe oder Farbcode. |
| `sizes` | Ja | Größen und Mengen als JSON-Objekt. Mindestens eine Menge muss größer als null sein. |
| `needs_purchase` | Ja | `true`, wenn GrafikFusion die Ware bestellen soll; sonst `false`. |
| `placements` | Nein | Eine oder mehrere Druck- beziehungsweise Stickpositionen. |
| `print_dimensions` | Nein | Maße der Drucke oder Stickereien. |
| `production_notes` | Nein | Technische Hinweise zur Ausführung. |
| `proofs` | Nein | Bis zu zehn positionsbezogene Korrekturabzüge als Data-URLs. |

## 5. Unterstützte Größen

Erwachsenengrößen:

```text
XXS, XS, S, M, L, XL, 2XL, 3XL, 4XL, 5XL
```

Kindergrößen:

```text
50, 56, 62, 68, 74, 80, 86, 92, 98, 104, 110, 116,
122, 128, 134, 140, 146, 152, 158, 164, 170, 176
```

Größen mit der Menge null müssen nicht übertragen werden.

## 6. Korrekturabzüge und Dateien

Bilder und PDFs werden als Data-URL übertragen:

```text
data:image/png;base64,iVBORw0KGgoAAA...
data:image/jpeg;base64,/9j/4AAQSkZJRg...
data:application/pdf;base64,JVBERi0xLjQ...
```

Pro Textilposition sind maximal zehn Korrekturabzüge vorgesehen. Große Dateien sollten vor der Übertragung sinnvoll komprimiert werden.

## 7. Erfolgreiche Antwort

HTTP-Status: `201 Created`

```json
{
  "ok": true,
  "duplicate": false,
  "order_id": 42,
  "order_number": "GF-2026-0042",
  "quantity": 29,
  "status": "Offener Auftrag"
}
```

Die Eigenschaft `order_number` ist die verbindliche GrafikFusion-Auftragsnummer und sollte in Ihrem System gespeichert werden.

## 8. Dublettenschutz

Wird dieselbe `external_reference` erneut übertragen, legt die Schnittstelle keinen zweiten Auftrag an. Sie antwortet mit dem bereits vorhandenen Auftrag:

```json
{
  "ok": true,
  "duplicate": true,
  "order_id": 42,
  "order_number": "GF-2026-0042"
}
```

## 9. Fehlermeldungen

| HTTP-Status | Bedeutung |
|---:|---|
| `400` | Pflichtfeld fehlt, Wert ungültig oder Händler nicht bekannt. |
| `401` | API-Schlüssel fehlt oder ist ungültig. |
| `409` | Konflikt durch eine bereits verwendete externe Referenz. |
| `500` | Interner Fehler bei der Verarbeitung. |

Fehlerantwort:

```json
{
  "error": "Position 1: Produkt, Händler und Farbe sind Pflichtfelder."
}
```

## 10. Hinweise zur Einführung

1. Zuerst einen Testauftrag mit einer eindeutigen Testreferenz senden.
2. Die zurückgegebene GrafikFusion-Auftragsnummer speichern.
3. Zusammen mit GrafikFusion prüfen, ob Kunde, Textilien, Größen, Farben, Händler und Druckpositionen vollständig angekommen sind.
4. Erst danach die Schnittstelle für Produktivaufträge aktivieren.

Bei technischen Rückfragen stellen Sie bitte die verwendete `external_reference`, den Zeitpunkt der Übertragung und die vollständige Fehlerantwort bereit. Den API-Schlüssel niemals per unverschlüsselter E-Mail oder in einem Support-Screenshot mitsenden.