Skip to content
Guida del Centro assistenza · Integrazioni di terze parti
3 min di letturaVerificato 2026-11-16

Integrazioni e-commerce

Collega store online tramite il nostro connettore nativo Shopware 6 o chiamate REST attivate da ordini.

In questa guida

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 externalId del pass (o lo abbini a idempotencyKey). Ciò garantisce che eventuali webhook d'ordine ritentati aggiornino il pass Wallet esistente in modo idempotente anziché emettere tessere duplicate.

Architettura Storefront-to-Wallet

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
SINCRONIZZAZIONE ORDINI E-COMMERCE E PROGRAMMA FEDELTÀ
ATTORI DI SISTEMA COINVOLTI
P1 Storefront online
P2 Livello E-Commerce Passinstance
P3 Wallet e POS in negozio
FASE CTX CONTESTO App Shopware 6
FASE 1a RICHIESTA / AZIONE Handshake e config
›
/v1/integrations/shopware/*
›
(ShopwareRegistration e Admin)
FASE 1b RICHIESTA / AZIONE Hook ordine / carrello
›
POST/v1/integrations/shopware/
›
webhooks
FASE 1c RICHIESTA / AZIONE Widget pass storefront
›
Shopware Storefront Widget
FASE CTX CONTESTO Shopify / WooCommerce
FASE 2 RICHIESTA / AZIONE POST/webhooks/shopify
›
Verifica HMACUpsert pass|-- 3. Emette / Aggiorna pass
›
o /v1/automations/webhooks/..
›
(externalId = shopify_cust_id)
›
e push al Wallet
FASE 4 RICHIESTA / AZIONE Riscatta in negozio via
FASE 5 RISPOSTA Sincronizza scansione via webhook
›
<----------------------------------| POST/v1/pos/redeem

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):

ControllerPercorsi montatiOperazioni principali
Shopware Onboarding API/v1/integrations/shopware/registration, /v1/integrations/shopware/lifecycle/:actionGestisce 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/webhooksElabora 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 ShopifyComportamento dell'handler Passinstance
customers/create e customers/updatePredispone o aggiorna un pass fedeltà associato tramite externalId: "shopify_customer_<id>".
orders/paidCalcola i punti fedeltà da subtotal_price, incrementa i contatori timbri oppure emette una gift card digitale acquistata (prepaid account).
orders/cancelled e refunds/createStorna 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):

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. 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. 1
    Nell'amministrazione WordPress, acceda a WooCommerce -> Impostazioni -> Avanzate -> Webhook.
  2. 2
    Crei webhook per Ordine aggiornato (order.updated), Ordine completato (order.completed) e Cliente creato (customer.created).
  3. 3
    Imposti l'URL di consegna su https://api.passinstance.com/webhooks/woocommerce e copi il segreto di firma del proprio workspace.
  4. 4
    Quando un ordine raggiunge completed, Passinstance emette o aggiorna automaticamente il pass del cliente (identificato da externalId) 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.

Documentazione prodotto e API correlata

Pronto a lanciare il tuo primo programma di carte Wallet?

Crea il tuo workspace, configura il modello e testa una carta reale in Apple Wallet e Google Wallet prima di scalare.