Kontext: Aleta, Shopify und Grosshandelspartner

Aleta Distribution Sàrl ist ein Schweizer Distributionsunternehmen. Der Produktkatalog lebt in Shopify: Artikel, Varianten, Medien und Bestände werden dort als operative Quelle der Wahrheit geführt.

B2B-Partner — weitere Distributoren und Integratoren — brauchen einen zuverlässigen programmatischen Zugriff (Referenzpreise, Lager, Standorte), ohne Shopify-Admin-Tokens offenzulegen und ohne jedem Partner GraphQL-Komplexität aufzuerlegen.

d-side solutions hat eine öffentliche B2B-API unter api.aleta.ch konzipiert und betrieben, angebunden an den Shopify-Shop, inklusive Dokumentation und Onboarding für API-Kunden.

💡 Technische Einordnung

Es handelt sich um eine Symfony-Middleware, die Grosshandelsanforderungen (stabiles REST, JSON, abgegrenzte Zugriffe) in kontrollierte Aufrufe der Shopify-Admin-GraphQL-API übersetzt — mit Cache, Logging und konsumentengerechter Fehleroberfläche.

Die Herausforderung: Katalog öffnen ohne Shopify zu gefährden

Direkter Admin-API-Zugang für viele Distributoren erzeugt Sicherheits-, Governance- und Vertragsprobleme: jeder Partner hat andere kommerzielle Konditionen, und die Shopify-API wandelt sich mit jeder Version (entfernte Felder oder Schemaänderungen).

  • ✗Kein geteiltes Admin-Token — Admin-Schlüssel an jeden Integrator zu verteilen, vervielfacht Risiken und erschwert Rotationen.
  • ✗Katalogpreis ≠ Distributorpreis — Rabatte oder Margen müssen pro Konto deterministisch und nachvollziehbar angewendet werden.
  • ✗GraphQL-Versions-Drift — gestern gültige Selektionen können nach einem API-Versionssprung scheitern.
  • ✗Serverbetrieb — reproduzierbare Deployments, Dateirechte (Konfigurationsschreibzugriff) und strukturierte Logs für die Produktion.

🎯 Ziel

Eine versionierte REST-Oberfläche, API-Schlüssel pro Kunde mit Umfang (Produkte, Bestände, Standorte), eine Admin-Konsole zur Kontoverwaltung und eine beherrschbare Produktionspipeline.

Die Lösung: Symfony-Middleware zwischen Shopify und Integratoren

Die Symfony-8-Anwendung fungiert als Gateway: Sie authentifiziert B2B-Aufrufe (Header Authorization: Bearer … oder äquivalenter Query-Parameter), wendet kundenspezifische Preisregeln an, befragt Shopify über die Admin-GraphQL-API und liefert dokumentierte JSON-Antworten.

// Datenfluss

B2B-Integrator
REST · API-Key · Scopes
→
Symfony-Middleware
Auth · Pricing · Cache
→
Shopify Admin GraphQL
Katalog · Inventar

Beträge werden als Strings zurückgegeben, um JSON-Präzisionsfallen auf Kundenseite zu vermeiden.

Das Repository wird auf d-side-Infrastruktur ausgerollt (git pull, composer install, Symfony-Cache leeren) mit dokumentiertem Deploy-Skript — das standardisiert Releases und reduziert Umgebungsdrift.

Reales Incident: Shopify-Fehler in Produktion

Der Katalog-Endpunkt lieferte plötzlich einen generischen « Shopify upstream »-Fehler. Applikationslogs zeigten GraphQL-Fehler: Felder (weight, weightUnit auf ProductVariant) existierten in der konfigurierten Admin-API-Version nicht mehr. Die Behebung war eine Anpassung der GraphQL-Selektion an das unterstützte Schema — ein Muster, das jede Shopify-Integration langfristig einplanen muss.

Betrieb: Dateiberechtigungen

Ein weiteres typisches Thema trat in Produktion auf: Schreibfehler auf temporären Konfigurationsdateien für Kunden, wenn der Unix-Benutzer des Webservers nicht zum Deployment-Besitzer passt. Die Lösung sind konsistente Rechte und Ownership zwischen SSH-Deploy und Apache-Runtime — banal, aber für die Kontoverwaltung blockierend.

Hauptfunktionen

Versionierte REST-Oberfläche

Integratoren nutzen Endpunkte für Health-Checks, paginierte Produktlisten (Cursor, SKU, Status), Bestände und Standorte — einheitliche Authentifizierung und konfigurierbare Rate-Limits pro Kunde.

Kundenspezifische Preise

Die Middleware berechnet kontobezogene Preise (z. B. Rabatt auf Katalogpreis plus Regeln für Direktliefer-Szenarien) zentralisiert und testbar aus Shopify-Beträgen.

Admin-Konsole

Eine geschützte Web-Oberfläche erlaubt Anlegen und Deaktivieren von Kunden, Anpassen von Prozenten und Zugriffsbereichen sowie Kommunikation von Zugangsdaten ohne Offenlegung des Shopify-Admin-Tokens — jeder Partner erhält einen eigenen Schlüssel mit Präfix wie b2b_ und behandelt ihn wie jedes andere Geheimnis.

Signierte Webhooks

Ein eigener Endpunkt nimmt Shopify-Notifications mit Signaturprüfung (HMAC) entgegen und ermöglicht zuverlässige Serverreaktionen bei Katalog- oder Bestandsänderungen in Shopify.

Ergebnisse

  • ✓Klares Integrationskontrakt — REST-JSON, verständliche Fehler, Dokumentation auf demselben Host wie die API.
  • ✓Shopify bleibt Quelle der Wahrheit — kein manuelles zweites Katalogsil.
  • ✓Robustheit gegen API-Evolution — gezielte GraphQL-Anpassung nach realem Produktionsvorfall.
  • ✓Reproduzierbare Deployments — dokumentiertes Composer-Skript für Code- und Dependency-Updates auf dem Server.

Zusammenfassung

Für Aleta hat d-side solutions eine schlanke, aber vollständige B2B-Schicht über Shopify gebaut: getrennte Identitäten pro Distributor, serverseitige Preislogik und Betriebsdisziplin für Schemaänderungen und POSIX-Realität.

Dasselbe Muster — Fach-Middleware + stabile API + leichtes Admin-UI — lässt sich auf andere Marken übertragen, die ihren Katalog für Partner öffnen wollen, ohne Shopify-Sicherheit zu opfern.

Sie vertreiben B2B über Shopify und brauchen eine kontrollierte Partner-API? Kontaktieren Sie uns.

LD

Luc Demierre

Gründer & IT-Berater — d-side solutions Sàrl, Bulle

Spezialisiert auf IT-Architektur, Systemsicherheit und E-Commerce-Integration für Schweizer KMU. Gründer von d-side solutions Sàrl seit 2022.