Skip to content
Hilfecenter-Anleitung · Drittanbieter-Integrationen
3 Min. LesezeitGeprüft 2026-11-16

E-Commerce-Integrationen

Verbinden Sie Shops nativ über Shopware 6 oder per bestellausgelöster REST-Ausgabe für individuelle Storefronts.

In dieser Anleitung

Überblick

Passinstance verbindet Online-Storefronts mit stationären Point-of-Sale-(POS-)Kassen im Einzelhandel, sodass Kunden Treuepunkte sammeln, Aktionsgutscheine einlösen und Prepaid-Geschenkkarten-Guthaben nahtlos über Web- und Filialkanäle hinweg nutzen können. Sie können Storefronts über unsere native Shopware-6-Controller-Suite (/settings/workspace/integrations/shopware im Dashboard), dedizierte Shopify- (POST /webhooks/shopify oder /v1/automations/webhooks/shopify/:customerId) und WooCommerce-Webhook-Empfänger (POST /webhooks/woocommerce oder /v1/automations/webhooks/woocommerce/:customerId) oder idempotente REST-Upserts (POST /api/v1/passes/upsert-by-external-id) anbinden.

Wichtig: Ordnen Sie die unveränderliche Kunden-ID oder Bestell-ID Ihrer E-Commerce-Plattform stets dem Feld externalId des Passes zu (oder kombinieren Sie sie mit idempotencyKey). So stellen Sie sicher, dass erneut zugestellte Bestell-Webhooks den bestehenden Wallet-Pass idempotent aktualisieren, statt doppelte Karten auszustellen.

Storefront-to-Wallet-Architektur

SYSTEMARCHITEKTUR-ABLAUF
INTERAKTIVE ARCHITEKTUR
E-COMMERCE-BESTELL- & TREUESYNCHRONISATION
BETEILIGTE SYSTEMKOMPONENTEN
P1 Online-Storefront
P2 Passinstance E-Commerce-Schicht
P3 Wallet & Filial-POS
SCHRITT CTX KONTEXT Shopware 6 App
SCHRITT 1a ANFRAGE / AKTION Handshake & Konfiguration
›
/v1/integrations/shopware/*
›
(ShopwareRegistration & Admin)
SCHRITT 1b ANFRAGE / AKTION Bestell- / Warenkorb-Hook
›
POST/v1/integrations/shopware/
›
webhooks
SCHRITT 1c ANFRAGE / AKTION Storefront-Pass-Widget
›
Shopware Storefront Widget
SCHRITT CTX KONTEXT Shopify / WooCommerce
SCHRITT 2 ANFRAGE / AKTION POST/webhooks/shopify
›
HMAC prüfenPass-Upsert|-- 3. Pass ausstellen /
›
oder /v1/automations/webhooks/..
›
(externalId = shopify_cust_id)
›
aktualisieren & Push
SCHRITT 4 ANFRAGE / AKTION Im Laden einlösen via
SCHRITT 5 ANTWORT Filial-Scan per Webhook melden
›
<----------------------------------| POST/v1/pos/redeem

1. Native Shopware-6-Integrations-Suite

Passinstance enthält ein dediziertes Backend-Modul sowie eine Dashboard-Konsole (/settings/workspace/integrations/shopware) für Shopware 6 (/shopware), orchestriert durch vier spezialisierte Controller und verfolgt über ShopwareInstallationStatus (PENDING | REGISTERED | CONNECTED | DEACTIVATED | UNINSTALLED):

ControllerEingebundene PfadeZentrale Operationen
Shopware Onboarding API/v1/integrations/shopware/registration, /v1/integrations/shopware/lifecycle/:actionÜbernimmt den Shopware-App-System-Handshake, Signaturprüfung, Secret-Rotation und Deinstallationsübergänge (UNINSTALLED).
Shopware Admin API/api/v1/integrations/shopware/admin/*Verbindet einen Shopware-Verkaufskanal mit einem Passinstance-Arbeitsbereich, ordnet Vorlagen (PassKind) Kundengruppen zu und verwaltet Automatisierungsregeln.
Shopware Storefront Widget/api/v1/integrations/shopware/storefront/*Liefert personalisierte Zu Apple Wallet hinzufügen / Zu Google Wallet hinzufügen-Badges, Gast-/Bestellpässe sowie Reservierungseinlösungen (reserve-redemption / capture-redemption) aus.
Shopware Webhook Handler/v1/integrations/shopware/webhooksVerarbeitet checkout.order.placed, order_transaction.state.paid, customer.written sowie Stornierungs-/Erstattungs-Hooks, um Punkte gutzuschreiben oder Gutscheine zu entwerten.

2. Shopify-Integration (POST /webhooks/shopify & Universelle Automatisierungen)

Verbinden Sie Ihren Shopify- oder Shopify-Plus-Shop, indem Sie Shopify-Webhook-Abonnements auf https://api.passinstance.com/webhooks/shopify ausrichten — oder konfigurieren Sie Arbeitsbereich-Automatisierungsregeln über /v1/automations/webhooks/shopify/:customerId (authentifiziert via X-Shopify-Hmac-Sha256):

Shopify-ThemaVerhalten des Passinstance-Handlers
customers/create & customers/updateStellt einen Mitglieder-Treuepass bereit oder aktualisiert ihn anhand von externalId: "shopify_customer_<id>".
orders/paidBerechnet Treuepunkte aus subtotal_price, erhöht Stempelzähler oder stellt eine gekaufte digitale Geschenkkarte (prepaid account) aus.
orders/cancelled & refunds/createZieht nicht verdiente Punkte vom Pass-Guthaben wieder ab oder setzt Einmal-Aktionscoupons auf VOIDED.

Beispiel für Shopify-Bestell-Webhook-Mapping (POST /api/v1/passes/upsert-by-external-id)

Wenn Sie eine eigene Shopify-Middleware oder Checkout UI Extension entwickeln, rufen Sie den idempotenten Upsert-Endpunkt direkt auf (die resultierende .pkpass-Datei übernimmt automatisch das in der Vorlage konfigurierte bundleId-Zertifikat):

JSON
{
  "templateId": "tmpl_shopify_vip_loyalty",
  "externalId": "shopify_cust_74920184",
  "attributes": {
    "holderName": "Lukas Weber",
    "email": "lukas.weber@example.com",
    "points": 450,
    "tier": "SILVER",
    "lastOrderNumber": "#1049"
  }
}

3. WooCommerce-Integration (POST /webhooks/woocommerce & Universelle Automatisierungen)

WooCommerce-Shops verbinden sich über https://api.passinstance.com/webhooks/woocommerce oder /v1/automations/webhooks/woocommerce/:customerId (verifiziert über den HMAC-SHA256-Header X-WC-Webhook-Signature):

  1. 1
    Navigieren Sie im WordPress-Adminbereich zu WooCommerce -> Einstellungen -> Erweitert -> Webhooks.
  2. 2
    Erstellen Sie Webhooks für Bestellung aktualisiert (order.updated), Bestellung abgeschlossen (order.completed) und Kunde erstellt (customer.created).
  3. 3
    Setzen Sie die Übermittlungs-URL auf https://api.passinstance.com/webhooks/woocommerce und hinterlegen Sie das Signaturgeheimnis Ihres Arbeitsbereichs.
  4. 4
    Sobald eine Bestellung den Status completed erreicht, stellt Passinstance automatisch den Pass des Kunden aus oder aktualisiert ihn (zugeordnet über externalId) und liefert die Smart-Download-URL (/s/:token) zur Einbindung in transaktionale WooCommerce-E-Mails zurück.

Weitere Konnektoren finden Sie unter Verfügbare Integrationen, Zahlungsanbieter unter /settings/workspace/integrations/payment-providers sowie die Shopware-Integrationsübersicht.

Weiterführende Produkt- & Entwicklerdoku

Bereit für Ihr erstes Wallet-Kartenprogramm?

Erstellen Sie Ihren Workspace, konfigurieren Sie Ihre Vorlage und testen Sie eine echte Karte in Apple Wallet und Google Wallet, bevor Sie skalieren.