Zum Helpdesk

Entwickler-Dokumentation

NEXT-API

Mit der NEXT-API verbindest du eigene Systeme (Shop, ERP, Skripte) direkt mit Shirtking.NEXT: Produkte importieren, Bestellungen übergeben, Status, Sendungen, Bestand und Rechnungen abrufen.

1. Schnellstart

  1. Im Portal API und Webhooks öffnen.
  2. „Neuer API-Schlüssel“ klicken und die nötigen Rechte (Scopes) wählen.
  3. Den Schlüssel (beginnt mit skn_) sofort kopieren – er wird nur einmal angezeigt.
  4. Ersten Test-Aufruf senden:
curl https://next.shirt-king.de/api/public/v1/products \
  -H "Authorization: Bearer skn_DEIN_SCHLUESSEL"

Basis-Adresse aller Befehle: https://next.shirt-king.de/api/public/v1. Die vollständige maschinenlesbare Beschreibung (OpenAPI) liegt unter /openapi.json.

2. Authentifizierung & Regeln

  • Anmeldung: Jeder Aufruf braucht den Header Authorization: Bearer skn_….
  • Scopes: read (alles lesen), inventory:read, orders:write (Bestellungen anlegen), products:write (Produkte importieren).
  • Limit: 120 Aufrufe pro Minute und Schlüssel. Darüber: Status 429 – kurz warten und erneut senden.
  • Idempotency-Key: Pflicht bei allen POST-Befehlen. Sende denselben Schlüssel erneut (z. B. nach Timeout), bekommst du die erste Antwort zurück – es entsteht nichts doppelt. Tipp: deine Shop-Bestellnummer verwenden.
  • Beträge: immer netto in Cent (1290 = 12,90 €).
  • Listen: seitenweise mit ?page=1&limit=50 (max. 100). Antwort: { data: [...], meta: { page, limit, total, hasMore } }.

3. Befehle (Endpunkte)

GET/catalogScope: read

Liefert die Textil-Basisartikel mit ID, Farben, Größen, Druckverfahren und Druckflächen (Schlüssel wie front, back). Brauchst du vor jedem Produkt-Import. Suche mit ?q=hoodie.

curl "https://next.shirt-king.de/api/public/v1/catalog?q=oversized" -H "Authorization: Bearer skn_…"

POST/productsScope: products:write

Legt ein fertiges Produkt an: lädt die Druckdatei (öffentlicher https-Link, PNG/SVG/PDF, max. 50 MB), platziert sie in mm ab der linken oberen Ecke der Druckfläche, gibt das Produkt frei und erzeugt die NEXT-SKUs. Mit shopSku verknüpfst du deine bestehende Shop-SKU (z. B. von podOS) – Bestellungen mit dieser SKU werden danach automatisch erkannt.

curl -X POST https://next.shirt-king.de/api/public/v1/products \
  -H "Authorization: Bearer skn_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: import-tee-001" \
  -d '{
    "name": "Logo Tee",
    "catalogProductId": "<id aus /catalog>",
    "printMethod": "dtf",
    "prints": [{
      "area": "front",
      "artworkUrl": "https://example.com/logo.png",
      "widthMm": 250, "heightMm": 180,
      "offsetXMm": 25, "offsetYMm": 40
    }],
    "variants": [
      { "color": "Black", "size": "M", "shopSku": "PODOS-TEE-BLK-M" },
      { "color": "Black", "size": "L", "shopSku": "PODOS-TEE-BLK-L" }
    ]
  }'

Antwort 201 mit Produkt-ID und SKUs. 422 = Angaben ungültig (z. B. Farbe nicht im Katalog), 409 = Shop-SKU bereits vergeben.

GET/productsScope: read

Alle deine Produkte mit freigegebenen Varianten (NEXT-SKU, Preis) und verknüpften Shop-SKUs. Nutze das, um SKUs in deinem Shop abzugleichen.

Jedes Produkt und jede Variante enthält images mit Links zu den fertigen Mockups (Farbe, Vorder-/Rückseite). Die Links sind 6 Stunden gültig – lade die Bilder beim Import herunter und hoste sie selbst; für neue Links einfach erneut abrufen. Mit ?include=none werden keine Bilder geliefert.

PATCH/products/{id}Scope: products:write

Ändert Produktname, SKU-Präfix oder Aktiv-Status. Bereits freigegebene SKUs bleiben unverändert – ein neues Präfix gilt erst für neue Versionen. Ist das Präfix vergeben, kommt 409 sku_prefix_taken.

curl -X PATCH https://next.shirt-king.de/api/public/v1/products/6a2fb191-… \
  -H "Authorization: Bearer skn_…" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Supporter Shirt 2026", "skuPrefix": "SUP26", "active": true }'

DELETE/products/{id}/versions/{version}Scope: products:write

Verwirft eine noch nicht freigegebene Entwurfsversion. Freigegebene Versionen sind unveränderlich (409 not_draft). Ist der Entwurf die einzige Version, wird das Produkt mitgelöscht (productDeleted: true).

curl -X DELETE https://next.shirt-king.de/api/public/v1/products/6a2fb191-…/versions/2 \
  -H "Authorization: Bearer skn_…"

DELETE/products/{id}Scope: products:write

Löscht ein Produkt (Antwort 204). Wurde es schon bestellt, kommt 409 product_in_use – dann stattdessen per PATCH { "active": false } deaktivieren.

POST/ordersScope: orders:write

Übergibt eine Bestellung. sku darf eine NEXT-SKU oder eine verknüpfte Shop-SKU sein. country ist der zweistellige Ländercode (DE, AT, CH …). Die Bestellung wird sofort geprüft und – je nach Einstellung – automatisch zur Produktion freigegeben.

curl -X POST https://next.shirt-king.de/api/public/v1/orders \
  -H "Authorization: Bearer skn_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: shop-10045" \
  -d '{
    "externalRef": "shop-10045",
    "shippingAddress": {
      "name": "Max Muster", "street": "Hauptstr. 1",
      "postalCode": "10115", "city": "Berlin",
      "country": "DE", "email": "max@example.com"
    },
    "items": [{ "sku": "PODOS-TEE-BLK-M", "quantity": 2 }]
  }'

GET/orders · /orders/{id}Scope: read

Liste mit Filtern ?status=shipped und ?updated_since=2026-11-01T00:00:00Z; Einzelabruf per ID oder Bestellnummer. Typische Status: checked, clarification, in_production, shipped, cancelled.

POST/orders/{id}/cancelScope: orders:write

Storniert eine Bestellung (per ID oder Bestellnummer), solange sie noch nicht in Produktion ist. Bezahlte Beträge werden automatisch erstattet. Optional mit reason. Zu spät: 409 cancellation_not_allowed; schon storniert: meta.alreadyCancelled: true.

curl -X POST https://next.shirt-king.de/api/public/v1/orders/NX-10045/cancel \
  -H "Authorization: Bearer skn_…" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Kunde hat storniert" }'

GET/shipmentsScope: read

Sendungen mit Versanddienstleister und Sendungsnummer – zum Weitergeben an deine Kund:innen.

GET/inventoryScope: inventory:read

Aktueller Lagerbestand deiner eingelagerten Artikel.

GET/invoicesScope: read

Rechnungen und Gutschriften mit Nummer, Datum, Betrag und Zahlstatus.

4. Abläufe: Was rufe ich wann auf?

A) Bestehende Shop-Produkte übernehmen (einmalig)

  1. GET /catalog → passenden Textilartikel suchen, id, Farbnamen, Größen und Druckfläche notieren.
  2. POST /products → je Shop-Produkt einmal, mit Druckdatei und den alten Shop-SKUs als shopSku.
  3. GET /products → prüfen, ob alle Varianten und Shop-SKUs angelegt sind.

Ergebnis: Im Shop muss nichts geändert werden.

B) Täglicher Bestellablauf

  1. Kund:in bestellt und bezahlt in deinem Shop.
  2. POST /orders mit Idempotency-Key = Shop-Bestellnummer.
  3. Warten auf Webhook order.shipped – oder alle 15 Minuten GET /orders?updated_since=….
  4. GET /shipments → Sendungsnummer in deinen Shop schreiben.

C) Bestellung hängt in „Klärung“

  1. Webhook order.clarification oder Status clarification in GET /orders/{id}.
  2. Häufigste Ursache: unbekannte SKU. Im Portal bei der Bestellung „SKU verknüpfen“ klicken – oder das Produkt per POST /products mit dieser shopSku nachimportieren.

D) Monatlicher Abgleich

GET /invoices und GET /inventory für Buchhaltung und Lagerübersicht.

5. Migration bestehender Shop-Produkte

Dieses Kapitel ist bewusst sehr genau geschrieben, damit daraus ohne Rückfragen ein fertiges Migrations-Skript gebaut werden kann. Es beschreibt, wie Produkte aus einem bestehenden Shop (z. B. angelegt über podOS) nach NEXT übernommen werden, ohne dass im Shop etwas geändert werden muss.

Grundprinzip

  • Der bestehende Shop bleibt unverändert. Produkte, Texte, Bilder, Preise und URLs bleiben, wo sie sind.
  • NEXT erzeugt für jede Variante eine eigene NEXT-SKU. Die alte Shop-SKU (z. B. die podOS-SKU) wird als Alias gespeichert (Feld shopSku).
  • Kommt eine Bestellung mit einer Shop-SKU, sucht NEXT zuerst die exakte NEXT-SKU, dann den Alias. Treffer → normale Prüfung. Kein Treffer → Status clarification (Klärung) mit Grund unknown_sku.
  • Shop-SKUs sind je Konto eindeutig. Dieselbe Shop-SKU kann nicht an zwei NEXT-Varianten hängen (Fehler 409).

Schritt-für-Schritt-Migration

  1. Schlüssel anlegen: Im Portal unter API und Webhooks einen Schlüssel mit den Scopes read und products:write erstellen.
  2. Katalog lesen: GET /catalog aufrufen und je Shop-Produkt den passenden Textilartikel suchen. Notieren: id (als catalogProductId), die exakten Farbnamen, die Größen und die Druckflächen-Schlüssel (z. B. front, back) mit ihren Maßen in mm.
  3. Druckdateien bereitstellen: Jede Druckdatei muss über einen öffentlich erreichbaren https-Link abrufbar sein (PNG, SVG oder PDF, max. 50 MB, empfohlen 300 DPI). Signierte oder ablaufende Links sind ok, solange sie zum Zeitpunkt des Imports funktionieren.
  4. Produkte importieren: Je Shop-Produkt genau ein Aufruf von POST /products pro Produkt. Felder:
{
  "name":            "Produktname (Pflicht, frei wählbar)",
  "catalogProductId":"ID aus GET /catalog (Pflicht)",
  "printMethod":     "dtf | dtg | flex … (Pflicht, siehe /catalog)",
  "prints": [{
    "area":      "front | back | … (Schlüssel aus /catalog)",
    "artworkUrl":"https://…/datei.png (öffentlich erreichbar)",
    "widthMm":   250,   // Druckbreite in mm
    "heightMm":  180,   // Druckhöhe in mm
    "offsetXMm": 25,    // Abstand von links, in mm
    "offsetYMm": 40     // Abstand von oben, in mm
  }],
  "variants": [
    { "color": "Black", "size": "M", "shopSku": "PODOS-TEE-BLK-M" }
    // color/size müssen exakt zu /catalog passen
    // shopSku optional, aber für Migration entscheidend
  ]
}
  1. Idempotency-Key: Pro Produkt einen stabilen Schlüssel setzen, z. B. mig-<shop-produkt-id>. Bei Timeout denselben Aufruf einfach wiederholen – es entsteht kein Duplikat.
  2. Antwort prüfen: 201 = Produkt angelegt, freigegeben, SKUs und Aliasse erstellt. 422 = Eingabe ungültig (Nachricht nennt das Feld, z. B. unbekannte Farbe). 409 = eine shopSku ist bereits vergeben – diese Variante existiert schon, Produkt nicht erneut anlegen.
  3. Abgleich: GET /products aufrufen und prüfen, dass jedes Shop-Produkt genau ein NEXT-Produkt mit allen Varianten und Shop-SKUs hat.
  4. Testbestellung: POST /orders mit einer alten Shop-SKU senden. Erwartetes Ergebnis: Status checked (nicht clarification).

Regeln, die ein Skript einhalten muss

  • Nie zwei Produkte mit derselben shopSku anlegen – die SKU-Zuordnung ist je Konto eindeutig.
  • Farb- und Größennamen exakt wie in GET /catalog schreiben (Groß-/Kleinschreibung beachten).
  • Platzierung immer in mm ab der linken oberen Ecke der Druckfläche; Breite + Offset dürfen die Flächenbreite nicht überschreiten.
  • Bei 429 (Limit) kurz warten und wiederholen; bei 5xx mit wachsendem Abstand wiederholen; bei 422 den Inhalt korrigieren, nicht wiederholen.
  • Positionen, die es im Shop nicht gibt (z. B. nur teilweise Größen), einfach weglassen – nicht mit leeren Werten senden.

Referenz-Skript (Python)

Liest eine CSV-Datei produkte.csv mit den Spalten name, catalog_product_id, print_method, area, artwork_url, width_mm, height_mm, offset_x_mm, offset_y_mm, color, size, shop_sku und importiert alle Produkte:

import csv, json, time, urllib.request

BASE = "https://next.shirt-king.de/api/public/v1"
KEY  = "skn_DEIN_SCHLUESSEL"

def call(method, path, body=None, idem=None):
    req = urllib.request.Request(
        BASE + path, method=method,
        data=json.dumps(body).encode() if body else None,
        headers={"Authorization": f"Bearer {KEY}",
                 "Content-Type": "application/json",
                 **({"Idempotency-Key": idem} if idem else {})})
    try:
        with urllib.request.urlopen(req) as r:
            return r.status, json.loads(r.read())
    except urllib.error.HTTPError as e:
        return e.code, json.loads(e.read())

# Zeilen nach Produkt gruppieren (gleicher name = ein Produkt)
products = {}
for row in csv.DictReader(open("produkte.csv")):
    p = products.setdefault(row["name"], {
        "name": row["name"],
        "catalogProductId": row["catalog_product_id"],
        "printMethod": row["print_method"],
        "prints": [{
            "area": row["area"],
            "artworkUrl": row["artwork_url"],
            "widthMm": int(row["width_mm"]),
            "heightMm": int(row["height_mm"]),
            "offsetXMm": int(row["offset_x_mm"]),
            "offsetYMm": int(row["offset_y_mm"]),
        }],
        "variants": [],
    })
    p["variants"].append({"color": row["color"],
                          "size": row["size"],
                          "shopSku": row["shop_sku"]})

for name, body in products.items():
    idem = "mig-" + name.lower().replace(" ", "-")
    while True:
        status, res = call("POST", "/products", body, idem)
        if status == 201:
            print("OK:", name, "→", res["id"]); break
        if status == 429:
            time.sleep(5); continue
        if status == 409:
            print("Shop-SKU schon verknüpft:", name, res); break
        raise SystemExit(f"Fehler {status} bei {name}: {res}")

# Abgleich: alles angelegt?
status, res = call("GET", "/products?limit=100")
print("Produkte in NEXT:", res["meta"]["total"])

Danach: laufender Betrieb

Neue Bestellungen aus dem Shop gehen per POST /orders mit den alten Shop-SKUs ein und werden automatisch erkannt. Meldet eine Bestellung trotzdem clarification/unknown_sku, fehlt ein Alias: im Portal bei der Bestellung „SKU verknüpfen“ klicken oder die Variante per POST /products nachziehen.

6. Webhooks

Unter API und Webhooks hinterlegst du eine https-Adresse. NEXT sendet Ereignisse als POST:

order.created, order.accepted, order.clarification, order.in_production, order.shipped, order.cancelled, inventory.low, inventory.updated, invoice.created, complaint.updated

{ "id": "evt_…", "type": "order.shipped", "createdAt": "2026-11-07T10:00:00Z", "data": { … } }

Prüfe die Signatur im Header x-shirtking-signature: t=<unix>,v1=<hex>: v1 = HMAC-SHA256(dein Secret, `${t}.${body}`). Antworte mit 2xx; sonst wird bis zu 8-mal mit wachsendem Abstand (2, 4, 8 … Min.) erneut gesendet.

// Node.js
import crypto from "node:crypto";
const [t, v1] = header.split(",").map((p) => p.split("=")[1]);
const ok = crypto.createHmac("sha256", SECRET).update(`${t}.${rawBody}`).digest("hex") === v1;

7. Fehler & Tipps

Fehler kommen immer als { "error": { "code", "message" } }.

  • 401 Schlüssel fehlt/ungültig · 403 Scope fehlt · 404 nicht gefunden
  • 409 Konflikt (z. B. Idempotency-Key mit anderem Inhalt, Shop-SKU vergeben)
  • 422 Angaben ungültig – Nachricht beschreibt das Feld · 429 zu viele Aufrufe

Fragen? Schreib uns über den Helpdesk.