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 metidempotencyKey). 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
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):
| Controller | Gekoppelde paden | Belangrijkste bewerkingen |
|---|---|---|
Shopware Onboarding API | /v1/integrations/shopware/registration, /v1/integrations/shopware/lifecycle/:action | Verwerkt 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/webhooks | Verwerkt 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-onderwerp | Gedrag van Passinstance-handler |
|---|---|
customers/create & customers/update | Maakt een ledenloyaliteitspas aan of werkt deze bij op basis van externalId: "shopify_customer_<id>". |
orders/paid | Berekent loyaliteitspunten op basis van subtotal_price, verhoogt stempeltellers of geeft een gekochte digitale cadeaubon (prepaid account) uit. |
orders/cancelled & refunds/create | Draait 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):
{
"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
Navigeer in WordPress Admin naar WooCommerce -> Instellingen -> Geavanceerd -> Webhooks.
-
2
Maak webhooks aan voor Bestelling bijgewerkt (
order.updated), Bestelling afgerond (order.completed) en Klant aangemaakt (customer.created). -
3
Stel de aflever-URL in op
https://api.passinstance.com/webhooks/woocommerceen kopieer het ondertekeningsgeheim van uw werkruimte. -
4
Wanneer een bestelling de status
completedbereikt, geeft Passinstance automatisch de pas van de klant uit of werkt deze bij (gekoppeld viaexternalId) 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.
