Ü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
externalIddes Passes zu (oder kombinieren Sie sie mitidempotencyKey). So stellen Sie sicher, dass erneut zugestellte Bestell-Webhooks den bestehenden Wallet-Pass idempotent aktualisieren, statt doppelte Karten auszustellen.
Storefront-to-Wallet-Architektur
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):
| Controller | Eingebundene Pfade | Zentrale 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/webhooks | Verarbeitet 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-Thema | Verhalten des Passinstance-Handlers |
|---|---|
customers/create & customers/update | Stellt einen Mitglieder-Treuepass bereit oder aktualisiert ihn anhand von externalId: "shopify_customer_<id>". |
orders/paid | Berechnet Treuepunkte aus subtotal_price, erhöht Stempelzähler oder stellt eine gekaufte digitale Geschenkkarte (prepaid account) aus. |
orders/cancelled & refunds/create | Zieht 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):
{
"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
Navigieren Sie im WordPress-Adminbereich zu WooCommerce -> Einstellungen -> Erweitert -> Webhooks.
-
2
Erstellen Sie Webhooks für Bestellung aktualisiert (
order.updated), Bestellung abgeschlossen (order.completed) und Kunde erstellt (customer.created). -
3
Setzen Sie die Übermittlungs-URL auf
https://api.passinstance.com/webhooks/woocommerceund hinterlegen Sie das Signaturgeheimnis Ihres Arbeitsbereichs. -
4
Sobald eine Bestellung den Status
completederreicht, stellt Passinstance automatisch den Pass des Kunden aus oder aktualisiert ihn (zugeordnet überexternalId) 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.
