API-Referenz — Next Commerce

📖

Übersicht

🏭 Hersteller-API

Produkte, Händler, Webhooks, Compliance / GPSR

🏪 Händler-API

Inventar, Zuweisungen, Stripe-Auszahlungen

🔒 Session-Cookie

NextAuth.js. Öffentliche Widget-Endpunkte: kein Auth.

📦 application/json

Standard. Ausnahmen als multipart/form-data markiert.

⚙️

Konventionen

Feld	Hinweis	Beispiel
Preise	Integer · Cent	`2500` = 25.00 EUR
Länder	ISO 3166-1 alpha-2	`DE`, `AT`, `CH`
Zeitstempel	ISO 8601	`2026-04-17T10:30:00Z`
SKU	Eindeutig je Hersteller	`brandId + sku`

Pagination Envelope

{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 1, "limit": 30, "totalCount": 142,
    "hasNextPage": true, "hasPreviousPage": false
  }
}

🔑

Authentifizierung

Session-Cookie via NextAuth.js

ℹ️

Session-Cookie: Alle Dashboard-APIs benötigen einen gültigen Session-Cookie. Öffentliche Endpunkte (Widget, Checkout) sind auth-frei.

POST/api/auth/registerRegistrieren

Erstellt ein neues Konto. type: brand für Hersteller, dealer für Händler.

Feld	Typ	Pflicht	Hinweis
type	"brand"\|"dealer"	Ja
email	string	Ja	Unique
password	string	Ja	Min 8 chars
firstName/lastName	string	Ja
companyName	string	Nein
baseCurrency	string	Nein	Händler only, unveränderlich
product	string	Nein	`DEALER_CHECKOUT` \| `LISTINGSHIELD`
invitationId	string	Nein

Response 200

{
  "success": true,
  "userId": "cuid_xxx",
  "role": "BRAND",
  "redirectUrl": "/brand"
}

⚠️

Rate limit: 5 / min / IP · 5 / 24h / email

POST/api/auth/callback/credentialsSign In

POST/api/auth/forgot-passwordPasswort vergessen

GET/api/auth/verify-email?token=xxxE-Mail bestätigen

📦

Hersteller — Produkte

role: BRAND

GET/api/brand/products?page=1&limit=30Auflisten

POST/api/brand/productsErstellen

Feld	Typ	Pflicht	Hinweis
sku	string	Ja	Unique per brand
name	string	Ja
description	string	Ja
weight	number	Ja	kg
recommendedPrice	integer	Nein	Cent
images	string[]	Nein	URLs
nameTranslations	object	Nein	{"en":"..."}
category	string	Nein
countryOfOrigin	string	Nein	ISO
internalProductId	string	Nein

⚠️

400 "SKU already exists for this brand"

GET/api/brand/products/:idGET / PUT / DELETE

POST/api/brand/products/bulk-importCSV Import

Content-Type: multipart/form-data

Feld	Typ	Pflicht	Hinweis
csv	File	Ja
zip	File	Nein
mode	string	Ja	`create_only` \| `update_only` \| `create_and_update`
skipTranslation	boolean	Ja	Skip DeepL
action	string	Ja	`validate` \| `import`

Response 200

{
  "totalProcessed": 50, "successCount": 48, "failureCount": 2,
  "results": [
    { "sku": "ABC-123", "success": true, "action": "created" },
    { "sku": "DEF-456", "success": false, "error": "Invalid weight" }
  ]
}

SSE progress: GET /api/brand/products/bulk-import/progress/:importId

POST/api/brand/products/bulk-assignMassenzuweisung

POST/api/brand/products/activateModul aktivieren

🤝

Hersteller — Händler

role: BRAND

GET/api/brand/dealers?productId=xxxAuflisten

PATCH/api/brand/dealers/countriesLänder

POST/api/brand/dealers/:dealerId/assign-productsProdukte zuweisen

POST/api/brand/invitationsHändler einladen

Feld	Pflicht
recipientEmail	Ja
recipientFirstName	Nein
country	Nein
assignedProductIds	Nein

🔔

Hersteller — Webhooks

role: BRAND

💡

Webhooks senden POST bei Bestellereignissen. Retry-Backoff: 1 min → 5 min → 30 min → 2 Std → 24 Std.

POST/api/brand/webhooksErstellen

Feld	Hinweis
url	HTTPS endpoint
events	`["order.created", "order.confirmed", "order.fulfilled"]`
isActive	boolean

GET|POST /api/brand/webhooks · PATCH|DELETE /api/brand/webhooks/:id
POST /api/brand/webhooks/:id/test · GET /api/brand/webhooks/:id/logs

🛡️

Hersteller — Compliance / GPSR

role: BRAND · ListingShield

ℹ️

Compliance kaskadiert: Hersteller → Kategorie → Produkt. Produktwerte überschreiben Kategorie-Werte.

GET/api/brand/compliance/companyCompany GPSR

POST/api/brand/compliance/categoriesKategorie-Compliance

Feld	Hinweis
categoryName
safetyWarnings
ageRestriction
warrantyInfo
disposalInstructions

GET/api/brand/products/:id/complianceProdukt-Compliance

POST/api/brand/compliance/invite-dealerListingShield einladen

Feld	Pflicht	Hinweis
websiteUrl	Ja
contactEmail	Ja
createNew	Nein	Force create if duplicate domain

📦

Händler — Inventar

role: DEALER

POST/api/dealer/inventoryHinzufügen

Feld	Typ	Pflicht	Hinweis
sku	string	Ja	Product SKU
brandId	string	Ja
price	integer	Ja	Cent
stockLevel	integer	Ja
discount	number	Nein	%
deliveryDays	integer	Nein	Default: 3

Response 200

{
  "success": true,
  "inventory": { "price": 19900, "stockLevel": 50, "deliveryDays": 3 }
}

⚠️

403 nicht autorisiert · 400 Produkt bereits im Inventar

PUT/api/dealer/inventory/:idAktualisieren

DELETE/api/inventory/:idLöschen

📋

Händler — Zuweisungen

role: DEALER

GET/api/dealer/assignments?status=PENDINGAuflisten

POST/api/dealer/assignments/:id/acceptAnnehmen

Feld	Pflicht	Hinweis
price	Ja	Cent
stockLevel	Nein
deliveryDays	Nein	Default: 3

DELETE/api/dealer/assignments/:idAblehnen

🛒

Händler — Bestellungen

role: DEALER

POST/api/dealer/orders/refundRückerstattung

💡

Stripe kehrt Transfer und Plattformgebühr automatisch proportional um.

Feld	Pflicht	Hinweis
orderId	Ja
refundType	Ja	`"full"` \| `"partial"`
reason	Ja
totalAmount	Ja	Cent
refundedItems	Nein	[{productId, sku, quantity, amount}]
shippingRefund	Nein	Cent

💰

Händler — Stripe

role: DEALER

💡

Händler erhalten ihre Marge via Stripe Split-Payment automatisch bei Kaufabschluss.

POST/api/dealer/stripe/onboarding-linkOnboarding starten

📡

Webhook Events

Event	Wann
order.created	Bestellung erstellt, Zahlung ausstehend
order.confirmed	Zahlung erfolgreich
order.fulfilled	Versandt

Webhook Payload

{
  "event": "order.created",
  "timestamp": "2026-04-17T10:30:00Z",
  "data": {
    "orderId": "order_id", "orderCode": "ORD-12345",
    "grandTotal": 10700, // 107,00 EUR
    "currency": "EUR",
    "customer": { "email": "[email protected]" },
    "items": [{ "sku": "ABC-123", "quantity": 1, "dealerId": "dealer_id" }]
  }
}

⚠️

Fehler & HTTP-Codes

Error Format

{
  "error": "Human-readable message",
  "code": "MACHINE_READABLE_CODE",
  "required": ["field1"]
}

Status	Bedeutung
`200`	OK
`400`	Validation error
`401`	Not authenticated
`403`	Not authorized / COUNTRY_NOT_ASSIGNED
`404`	Not found
`409`	Conflict
`429`	Rate limited
`500`	Server error

🚦

Rate Limits

Tier	Limit	Fenster	Gilt für
AUTH	5	1 min / IP	Register, login, password reset
REGISTRATION_EMAIL	5	24h / email	Registration only
AUTHENTICATED	500	1 min / IP	All dashboard APIs
PUBLIC	100	1 min / IP	Widget, checkout

429 Response

{ "error": "Too many requests", "retryAfter": 45 }

Next Commerce API

Übersicht

Konventionen

Authentifizierung

Hersteller — Produkte

Hersteller — Händler

Hersteller — Webhooks

Hersteller — Compliance / GPSR

Händler — Inventar

Händler — Zuweisungen

Händler — Bestellungen

Händler — Stripe

Webhook Events

Fehler & HTTP-Codes

Rate Limits