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
- Im Portal API und Webhooks öffnen.
- „Neuer API-Schlüssel“ klicken und die nötigen Rechte (Scopes) wählen.
- Den Schlüssel (beginnt mit
skn_) sofort kopieren – er wird nur einmal angezeigt. - 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)
GET /catalog→ passenden Textilartikel suchen,id, Farbnamen, Größen und Druckfläche notieren.POST /products→ je Shop-Produkt einmal, mit Druckdatei und den alten Shop-SKUs alsshopSku.GET /products→ prüfen, ob alle Varianten und Shop-SKUs angelegt sind.
Ergebnis: Im Shop muss nichts geändert werden.
B) Täglicher Bestellablauf
- Kund:in bestellt und bezahlt in deinem Shop.
POST /ordersmitIdempotency-Key= Shop-Bestellnummer.- Warten auf Webhook
order.shipped– oder alle 15 MinutenGET /orders?updated_since=…. GET /shipments→ Sendungsnummer in deinen Shop schreiben.
C) Bestellung hängt in „Klärung“
- Webhook
order.clarificationoder StatusclarificationinGET /orders/{id}. - Häufigste Ursache: unbekannte SKU. Im Portal bei der Bestellung „SKU verknüpfen“ klicken – oder das Produkt per
POST /productsmit diesershopSkunachimportieren.
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 Grundunknown_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
- Schlüssel anlegen: Im Portal unter API und Webhooks einen Schlüssel mit den Scopes
readundproducts:writeerstellen. - Katalog lesen:
GET /catalogaufrufen und je Shop-Produkt den passenden Textilartikel suchen. Notieren:id(alscatalogProductId), die exakten Farbnamen, die Größen und die Druckflächen-Schlüssel (z. B.front,back) mit ihren Maßen in mm. - 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.
- Produkte importieren: Je Shop-Produkt genau ein Aufruf von
POST /productspro 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
]
}- 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. - 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
shopSkuist bereits vergeben – diese Variante existiert schon, Produkt nicht erneut anlegen. - Abgleich:
GET /productsaufrufen und prüfen, dass jedes Shop-Produkt genau ein NEXT-Produkt mit allen Varianten und Shop-SKUs hat. - Testbestellung:
POST /ordersmit einer alten Shop-SKU senden. Erwartetes Ergebnis: Statuschecked(nichtclarification).
Regeln, die ein Skript einhalten muss
- Nie zwei Produkte mit derselben
shopSkuanlegen – die SKU-Zuordnung ist je Konto eindeutig. - Farb- und Größennamen exakt wie in
GET /catalogschreiben (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.