Panoramica
Passinstance collega gli storefront e-commerce online e le casse fisiche dei punti vendita retail (POS) affinché i clienti possano accumulare punti fedeltà, riscattare voucher promozionali e spendere saldi di gift card prepagate senza soluzione di continuità tra canali web e in negozio. È possibile connettere gli store tramite la nostra suite nativa di controller Shopware 6 (/settings/workspace/integrations/shopware nella Dashboard), i riceventi webhook dedicati per Shopify (POST /webhooks/shopify o /v1/automations/webhooks/shopify/:customerId) e WooCommerce (POST /webhooks/woocommerce o /v1/automations/webhooks/woocommerce/:customerId), oppure tramite upsert REST idempotenti (POST /api/v1/passes/upsert-by-external-id).
Importante: Associ sempre l'ID cliente o ID ordine immutabile della propria piattaforma e-commerce al campo
externalIddel pass (o lo abbini aidempotencyKey). Ciò garantisce che eventuali webhook d'ordine ritentati aggiornino il pass Wallet esistente in modo idempotente anziché emettere tessere duplicate.
Architettura Storefront-to-Wallet
1. Suite nativa di integrazione Shopware 6
Passinstance include un modulo backend dedicato e una console nella Dashboard (/settings/workspace/integrations/shopware) per Shopware 6 (/shopware), orchestrati da quattro controller specializzati e tracciati tramite ShopwareInstallationStatus (PENDING | REGISTERED | CONNECTED | DEACTIVATED | UNINSTALLED):
| Controller | Percorsi montati | Operazioni principali |
|---|---|---|
Shopware Onboarding API | /v1/integrations/shopware/registration, /v1/integrations/shopware/lifecycle/:action | Gestisce l'handshake di Shopware App System, la verifica della firma, la rotazione dei segreti e le transizioni di disinstallazione (UNINSTALLED). |
Shopware Admin API | /api/v1/integrations/shopware/admin/* | Collega un canale di vendita Shopware a un workspace Passinstance, associa i modelli (PassKind) ai gruppi clienti e gestisce le regole di automazione. |
Shopware Storefront Widget | /api/v1/integrations/shopware/storefront/* | Espone badge personalizzati Aggiungi ad Apple Wallet / Salva su Google Wallet, pass ospite/ordine e riscatti con prenotazione (reserve-redemption / capture-redemption). |
Shopware Webhook Handler | /v1/integrations/shopware/webhooks | Elabora checkout.order.placed, order_transaction.state.paid, customer.written e gli hook di cancellazione/rimborso per assegnare punti o annullare voucher. |
2. Integrazione Shopify (POST /webhooks/shopify e automazioni universali)
Colleghi il proprio store Shopify o Shopify Plus indirizzando le sottoscrizioni webhook di Shopify a https://api.passinstance.com/webhooks/shopify — oppure configuri regole di automazione del workspace tramite /v1/automations/webhooks/shopify/:customerId (autenticato tramite X-Shopify-Hmac-Sha256):
| Argomento Shopify | Comportamento dell'handler Passinstance |
|---|---|
customers/create e customers/update | Predispone o aggiorna un pass fedeltà associato tramite externalId: "shopify_customer_<id>". |
orders/paid | Calcola i punti fedeltà da subtotal_price, incrementa i contatori timbri oppure emette una gift card digitale acquistata (prepaid account). |
orders/cancelled e refunds/create | Storna dal saldo del pass i punti non maturati oppure porta allo stato VOIDED eventuali coupon promozionali monouso. |
Esempio di mappatura webhook ordini Shopify (POST /api/v1/passes/upsert-by-external-id)
Quando si sviluppa un middleware Shopify personalizzato o una Checkout UI Extension, richiami direttamente l'endpoint idempotente di upsert (il file .pkpass risultante eredita automaticamente il certificato bundleId configurato sul modello):
{
"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. Integrazione WooCommerce (POST /webhooks/woocommerce e automazioni universali)
Gli store WooCommerce si connettono tramite https://api.passinstance.com/webhooks/woocommerce oppure /v1/automations/webhooks/woocommerce/:customerId (verificato tramite l'header HMAC-SHA256 X-WC-Webhook-Signature):
-
1
Nell'amministrazione WordPress, acceda a WooCommerce -> Impostazioni -> Avanzate -> Webhook.
-
2
Crei webhook per Ordine aggiornato (
order.updated), Ordine completato (order.completed) e Cliente creato (customer.created). -
3
Imposti l'URL di consegna su
https://api.passinstance.com/webhooks/woocommercee copi il segreto di firma del proprio workspace. -
4
Quando un ordine raggiunge
completed, Passinstance emette o aggiorna automaticamente il pass del cliente (identificato daexternalId) e restituisce lo smart link di download (/s/:token) da includere nelle e-mail transazionali di WooCommerce.
Esplori ulteriori connettori in Integrazioni disponibili, i provider di pagamento su /settings/workspace/integrations/payment-providers e la Panoramica integrazione Shopware.
