Aperçu
Passinstance relie vos boutiques en ligne et vos terminaux de caisse physiques (POS) afin que vos clients puissent cumuler des points de fidélité, encaisser des bons promotionnels et dépenser leurs cartes cadeaux prépayées indifféremment sur le web et en magasin. Connectez vos boutiques grâce à notre suite native Shopware 6 (/settings/workspace/integrations/shopware dans le tableau de bord), nos récepteurs webhook dédiés Shopify (POST /webhooks/shopify ou /v1/automations/webhooks/shopify/:customerId) et WooCommerce (POST /webhooks/woocommerce ou /v1/automations/webhooks/woocommerce/:customerId), ou via des upserts REST idempotents (POST /api/v1/passes/upsert-by-external-id).
Important : Associez toujours l'identifiant client immuable ou l'ID de commande de votre plateforme e-commerce au champ
externalIddu passe (ou associez-le àidempotencyKey). Ainsi, toute nouvelle tentative d'envoi d'un webhook de commande mettra à jour le passe existant de façon idempotente au lieu d'émettre des doublons.
Architecture boutique-vers-Wallet
1. Suite d'intégration native Shopware 6
Passinstance propose un module backend dédié et une console dans le tableau de bord (/settings/workspace/integrations/shopware) pour Shopware 6 (/shopware), orchestrés par quatre contrôleurs spécialisés et suivis via ShopwareInstallationStatus (PENDING \| REGISTERED \| CONNECTED \| DEACTIVATED \| UNINSTALLED) :
| Contrôleur | Chemins montés | Opérations principales |
|---|---|---|
Shopware Onboarding API | /v1/integrations/shopware/registration, /v1/integrations/shopware/lifecycle/:action | Gère la poignée de main du Shopware App System, la vérification des signatures, la rotation des secrets et les transitions de désinstallation (UNINSTALLED). |
Shopware Admin API | /api/v1/integrations/shopware/admin/* | Relie un canal de vente Shopware à un espace Passinstance, associe les modèles (PassKind) aux groupes de clients et gère les règles d'automatisation. |
Shopware Storefront Widget | /api/v1/integrations/shopware/storefront/* | Délivre les boutons personnalisés Add to Apple Wallet / Save to Google Wallet, les cartes invités/commandes et les réservations de remise (reserve-redemption / capture-redemption). |
Shopware Webhook Handler | /v1/integrations/shopware/webhooks | Traite checkout.order.placed, order_transaction.state.paid, customer.written et les annulations/remboursements pour créditer des points ou invalider des bons. |
2. Intégration Shopify (POST /webhooks/shopify & automatisations universelles)
Connectez votre boutique Shopify ou Shopify Plus en pointant vos abonnements webhook vers https://api.passinstance.com/webhooks/shopify — ou configurez des règles d'automatisation via /v1/automations/webhooks/shopify/:customerId (authentifié via X-Shopify-Hmac-Sha256) :
| Sujet Shopify | Comportement du gestionnaire Passinstance |
|---|---|
customers/create & customers/update | Crée ou met à jour un passe de fidélité membre apparié par externalId: "shopify_customer_<id>". |
orders/paid | Calcule les points de fidélité à partir de subtotal_price, incrémente les tampons ou émet une carte cadeau numérique achetée (prepaid account). |
orders/cancelled & refunds/create | Annule les points acquis non mérités sur le solde du passe ou fait passer les coupons promotionnels à usage unique à VOIDED. |
Exemple de correspondance webhook commande Shopify (POST /api/v1/passes/upsert-by-external-id)
Lorsque vous développez un middleware Shopify sur mesure ou une Checkout UI Extension, appelez directement le point d'entrée d'upsert idempotent (le .pkpass résultant hérite automatiquement du certificat bundleId configuré sur le modèle) :
{
"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. Intégration WooCommerce (POST /webhooks/woocommerce & automatisations universelles)
Les boutiques WooCommerce se connectent via https://api.passinstance.com/webhooks/woocommerce ou /v1/automations/webhooks/woocommerce/:customerId (vérifiés par l'en-tête HMAC-SHA256 X-WC-Webhook-Signature) :
-
1
Dans l'administration WordPress, ouvrez WooCommerce -> Réglages -> Avancé -> Webhooks.
-
2
Créez des webhooks pour Commande mise à jour (
order.updated), Commande terminée (order.completed) et Client créé (customer.created). -
3
Définissez l'URL de livraison sur
https://api.passinstance.com/webhooks/woocommerceet copiez le secret de signature de votre espace de travail. -
4
Lorsqu'une commande passe à
completed, Passinstance émet ou actualise automatiquement la carte du client (indexée parexternalId) et retourne le lien intelligent de téléchargement (/s/:token) pour l'insérer dans vos e-mails transactionnels WooCommerce.
Découvrez nos autres connecteurs dans Intégrations disponibles, la configuration des prestataires de paiement sous /settings/workspace/integrations/payment-providers, et la Présentation de l'intégration Shopware.
