API-Referenz

Das Plugin registriert drei Admin-API-Endpunkte (Route-Scope api) über PHP-Attribute im Controller vlp8n\Controller\Api\N8nAPI. Sie werden vom Administration-Service vlp8nService aufgerufen, können aber auch direkt über die authentifizierte Shopware-Admin-API angesprochen werden.

Endpunkte

Methode	Pfad	Beschreibung
`GET` / `POST`	`/api/_action/vlp8n/send_products`	Produkte senden
`GET` / `POST`	`/api/_action/vlp8n/send_customers`	Kunden senden
`GET` / `POST`	`/api/_action/vlp8n/send_orders`	Bestellungen senden

Parameter

Parameter	Typ	Endpunkte	Beschreibung
`sales_channel_id`	string	alle	ID des Verkaufskanals; bestimmt die genutzte Webhook-URL und den Datenkontext
`category_ids`	string[]	`send_products`	Optionaler Filter auf eine oder mehrere Kategorie-IDs
`sync_count`	int	alle	Vom Admin-Service mitgegebener Zähler

hinweis

Diese Endpunkte gehören zum Admin-API-Scope und erfordern eine gültige Authentifizierung (OAuth-Token der Shopware-Administration). Sie sind nicht öffentlich erreichbar.

Antworten

send_products:

{
  "success": true,
  "total_sync": 128,
  "total_products": 128
}

send_customers / send_orders:

{
  "success": true,
  "total_sync": 42
}

Mögliche Fehlermeldungen (success: false):

`msg`	Bedeutung
`no_webhook_url`	Für die Aktion ist keine Webhook-URL konfiguriert
`no_products_found`	Keine Produkte für die Auswahl gefunden

Webhook-Aufruf

Das Plugin sendet das Payload per HTTP POST an die konfigurierte URL:

POST <webhook-url>
Content-Type: application/json

Der Versand gilt als erfolgreich, wenn n8n mit einem HTTP-Status 2xx antwortet und kein cURL-Fehler auftritt. Der Body ist jeweils ein Array von Objekten.

Payload: Produkte

[
  {
    "id": "0190a1...",
    "number": "SW10001",
    "name": "Beispielprodukt",
    "description": "Produktbeschreibung …",
    "stock": 25,
    "priceNet": 41.18,
    "priceGross": 49.0,
    "purchasePrice": 30.0,
    "prices": { "eur": 49.0, "usd": 53.9 },
    "coverUrl": "https://shop.example.com/media/…/cover.jpg",
    "url": "https://shop.example.com/beispielprodukt",
    "categories": ["Kategorie A", "Kategorie B"],
    "options": ["Größe: L", "Farbe: Blau"],
    "customFields": { "mein_feld": "Wert" }
  }
]

prices enthält den Bruttopreis je Währung des Verkaufskanals (Schlüssel = ISO-Code in Kleinbuchstaben).
customFields-Schlüssel werden bereinigt (siehe unten).

Payload: Kunden

[
  {
    "salesChannel": "Storefront",
    "salesChannelId": "0190a1...",
    "language": "Deutsch",
    "languageLocale": "de-DE",
    "orderCount": 3,
    "orderTotalAmount": 247.5,
    "affiliateCode": "",
    "campaignCode": "",
    "customFields": { "mein_feld": "Wert" }
  }
]

(zusätzlich u. a. Stammdaten und die Standard-Rechnungsadresse des Kunden.)

Payload: Bestellungen

[
  {
    "id": "0190a1...",
    "orderNumber": "10025",
    "amountTotal": 119.9,
    "currency": "EUR",
    "salesChannel": "Storefront",
    "closedate": "2026-05-31T10:15:00+00:00",
    "lineItems": [
      { "label": "Beispielprodukt", "quantity": 2, "unitPrice": 49.0 }
    ],
    "customFields": { "mein_feld": "Wert" }
  }
]

Zu jeder Bestellung wird zusätzlich der Kunde inkl. Standard-Rechnungsadresse (street, city, zip, country) ausgegeben.

Bereinigung von Custom-Field-Schlüsseln

Damit Custom-Field-Schlüssel als valide JSON-/Objekt-Schlüssel taugen, werden sie durch sanitizeCustomFieldKey() normalisiert:

Deutsche Umlaute werden ersetzt: ä→ae, ö→oe, ü→ue, ß→ss (inkl. Großbuchstaben).
Weitere Akzentzeichen werden nach ASCII transliteriert.
Alle Zeichen außer A–Z, a–z, 0–9 und _ werden zu _.
Mehrfache _ werden zusammengefasst, führende/abschließende _ entfernt.
Ist das Ergebnis leer, wird custom_field verwendet.

➡️ Bei Problemen hilft die Fehlerbehebung.

Endpunkte​

Parameter​

Antworten​

Webhook-Aufruf​

Payload: Produkte​

Payload: Kunden​

Payload: Bestellungen​

Bereinigung von Custom-Field-Schlüsseln​