Skip to content
Helpcentrum-gids · Externe integraties
3 min leestijdGecontroleerd 2026-11-16

E-commerce-integraties

Koppel webshops via onze eigen Shopware 6-integratie of via webhookgestuurde REST-uitgifte.

In deze gids

Overzicht

Passinstance slaat een brug tussen online e-commerce webwinkels en fysieke Point-of-Sale (POS) winkelkassa's, zodat klanten naadloos loyaliteitspunten kunnen sparen, promotievouchers kunnen verzilveren en vooraf betaalde cadeaubonsaldi kunnen besteden via zowel web- als winkelkanalen. U kunt webwinkels koppelen met behulp van onze systeemeigen Shopware 6-controllersuite (/settings/workspace/integrations/shopware in het Dashboard), speciale webhookontvangers voor Shopify (POST /webhooks/shopify of /v1/automations/webhooks/shopify/:customerId) en WooCommerce (POST /webhooks/woocommerce of /v1/automations/webhooks/woocommerce/:customerId), of idempotente REST-upserts (POST /api/v1/passes/upsert-by-external-id).

Belangrijk: Koppel het onveranderlijke klant-ID of order-ID van uw e-commerceplatform altijd aan het externalId-veld van de pas (of combineer dit met idempotencyKey). Dit garandeert dat opnieuw verzonden orderwebhooks de bestaande wallet-pas idempotent bijwerken in plaats van dubbele kaarten uit te geven.

Architectuur van webwinkel naar wallet

SYSTEEMARCHITECTUUR
INTERACTIEVE ARCHITECTUUR
SYSTEEMARCHITECTUURSTROOM: SYNCHRONISATIE VAN E-COMMERCEBESTELLINGEN & LOYALITEIT
DEELNEMENDE SYSTEEMACTOREN
P1 Online webwinkel
P2 Passinstance E-commercelaag
P3 Wallet & Winkel-POS
STAP CTX KONTEXT Shopware 6-app
STAP 1a VERZOEK / ACTIE Handshake & Config
›
/v1/integrations/shopware/*
›
(ShopwareRegistration & Admin)
STAP 1b VERZOEK / ACTIE Order- / Winkelwagenhook
›
POST/v1/integrations/shopware/
›
webhooks
STAP 1c VERZOEK / ACTIE Etalage-paswidget
›
Shopware Storefront Widget
STAP CTX KONTEXT Shopify / WooCommerce
STAP 2 VERZOEK / ACTIE POST/webhooks/shopify
›
Verifieer HMACUpsert pas|3. Geef pas uit / werk bij
›
of /v1/automations/webhooks/..
›
(externalId = shopify_cust_id)
›
& push naar Wallet
STAP 4 VERZOEK / ACTIE Verzilver in winkel via
STAP 5 ANTWOORD Sync winkelscan via webhook
›
<----------------------------------| POST/v1/pos/redeem

1. Systeemeigen Shopware 6-integratiesuite

Passinstance bevat een speciale backendmodule en Dashboardconsole (/settings/workspace/integrations/shopware) voor Shopware 6 (/shopware), aangestuurd door vier gespecialiseerde controllers en gevolgd via ShopwareInstallationStatus (PENDING | REGISTERED | CONNECTED | DEACTIVATED | UNINSTALLED):

ControllerGekoppelde padenBelangrijkste bewerkingen
Shopware Onboarding API/v1/integrations/shopware/registration, /v1/integrations/shopware/lifecycle/:actionVerwerkt de handshake van het Shopware App System, handtekeningverificatie, geheimrotatie en de-installatieovergangen (UNINSTALLED).
Shopware Admin API/api/v1/integrations/shopware/admin/*Verbindt een Shopware-verkoopkanaal met een Passinstance-werkruimte, koppelt sjablonen (PassKind) aan klantgroepen en beheert automatiseringsregels.
Shopware Storefront Widget/api/v1/integrations/shopware/storefront/*Serveert gepersonaliseerde Add to Apple Wallet / Save to Google Wallet-badges, gast-/bestelpassen en reserveringsverzilveringen (reserve-redemption / capture-redemption).
Shopware Webhook Handler/v1/integrations/shopware/webhooksVerwerkt checkout.order.placed, order_transaction.state.paid, customer.written en annulerings-/terugbetalingshooks om punten toe te kennen of vouchers ongeldig te verklaren.

2. Shopify-integratie (POST /webhooks/shopify & Universele automatiseringen)

Koppel uw Shopify- of Shopify Plus-winkel door Shopify-webhookabonnementen te verwijzen naar https://api.passinstance.com/webhooks/shopify — of configureer automatiseringsregels voor uw werkruimte via /v1/automations/webhooks/shopify/:customerId (geauthenticeerd via X-Shopify-Hmac-Sha256):

Shopify-onderwerpGedrag van Passinstance-handler
customers/create & customers/updateMaakt een ledenloyaliteitspas aan of werkt deze bij op basis van externalId: "shopify_customer_<id>".
orders/paidBerekent loyaliteitspunten op basis van subtotal_price, verhoogt stempeltellers of geeft een gekochte digitale cadeaubon (prepaid account) uit.
orders/cancelled & refunds/createDraait onverdiende punten van het passaldo terug of zet eenmalige promotiecoupons om naar VOIDED.

Voorbeeld van Shopify-orderwebhookkoppeling (POST /api/v1/passes/upsert-by-external-id)

Wanneer u een aangepaste Shopify-middleware of Checkout UI Extension bouwt, roept u rechtstreeks het idempotente upsert-eindpunt aan (de resulterende .pkpass erft automatisch het geconfigureerde bundleId-certificaat van het sjabloon):

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-integratie (POST /webhooks/woocommerce & Universele automatiseringen)

WooCommerce-winkels maken verbinding via https://api.passinstance.com/webhooks/woocommerce of /v1/automations/webhooks/woocommerce/:customerId (geverifieerd via de HMAC-SHA256-header X-WC-Webhook-Signature):

  1. 1
    Navigeer in WordPress Admin naar WooCommerce -> Instellingen -> Geavanceerd -> Webhooks.
  2. 2
    Maak webhooks aan voor Bestelling bijgewerkt (order.updated), Bestelling afgerond (order.completed) en Klant aangemaakt (customer.created).
  3. 3
    Stel de aflever-URL in op https://api.passinstance.com/webhooks/woocommerce en kopieer het ondertekeningsgeheim van uw werkruimte.
  4. 4
    Wanneer een bestelling de status completed bereikt, geeft Passinstance automatisch de pas van de klant uit of werkt deze bij (gekoppeld via externalId) en retourneert de slimme download-URL (/s/:token) voor opname in transactionele WooCommerce-e-mails.

Verken aanvullende connectoren in Beschikbare integraties, betalingsproviders op /settings/workspace/integrations/payment-providers en het Overzicht van de Shopware-integratie.

Gerelateerde product- en ontwikkelaarsdocs

Klaar om uw eerste kaartprogramma te lanceren?

Maak uw workspace aan, configureer uw sjabloon en test een echte kaart in Apple Wallet en Google Wallet voordat u opschaalt.