Descripción general
Passinstance conecta las tiendas online de comercio electrónico con los puntos de venta físicos (POS) para que los clientes puedan acumular puntos de fidelización, canjear cupones promocionales y gastar saldos prepago de tarjetas de regalo sin fricciones entre canales web y tienda física. Puede conectar sus tiendas mediante nuestra suite nativa de controladores para Shopware 6 (/settings/workspace/integrations/shopware en el Panel de control), receptores dedicados de webhooks para Shopify (POST /webhooks/shopify o /v1/automations/webhooks/shopify/:customerId) y WooCommerce (POST /webhooks/woocommerce o /v1/automations/webhooks/woocommerce/:customerId), o mediante upserts REST idempotentes (POST /api/v1/passes/upsert-by-external-id).
Importante: Asigne siempre el ID inmutable de cliente o pedido de su plataforma de comercio electrónico al campo
externalIddel pase (o combínelo conidempotencyKey). Esto garantiza que los webhooks de pedido reintentados actualicen el pase existente en Wallet de forma idempotente en lugar de emitir tarjetas duplicadas.
Arquitectura de tienda online a Wallet
1. Suite de integración nativa para Shopware 6
Passinstance incluye un módulo backend específico y una consola en el Panel de control (/settings/workspace/integrations/shopware) para Shopware 6 (/shopware) orquestados por cuatro controladores especializados y supervisados mediante ShopwareInstallationStatus (PENDING | REGISTERED | CONNECTED | DEACTIVATED | UNINSTALLED):
| Controlador | Rutas montadas | Operaciones principales |
|---|---|---|
Shopware Onboarding API | /v1/integrations/shopware/registration, /v1/integrations/shopware/lifecycle/:action | Gestiona el handshake del App System de Shopware, verificación de firmas, rotación de secretos y transiciones de desinstalación (UNINSTALLED). |
Shopware Admin API | /api/v1/integrations/shopware/admin/* | Conecta un canal de ventas de Shopware a un espacio de trabajo Passinstance, mapea plantillas (PassKind) a grupos de clientes y gestiona reglas de automatización. |
Shopware Storefront Widget | /api/v1/integrations/shopware/storefront/* | Sirve insignias personalizadas Add to Apple Wallet / Save to Google Wallet, pases de invitado/pedido y reservas de canje (reserve-redemption / capture-redemption). |
Shopware Webhook Handler | /v1/integrations/shopware/webhooks | Procesa hooks checkout.order.placed, order_transaction.state.paid, customer.written y cancelaciones/reembolsos para conceder puntos o anular vales. |
2. Integración con Shopify (POST /webhooks/shopify y Automatizaciones Universales)
Conecte su tienda Shopify o Shopify Plus dirigiendo las suscripciones de webhooks de Shopify a https://api.passinstance.com/webhooks/shopify —o configure reglas de automatización del espacio de trabajo mediante /v1/automations/webhooks/shopify/:customerId (autenticado con X-Shopify-Hmac-Sha256):
| Tema de Shopify | Comportamiento del manejador de Passinstance |
|---|---|
customers/create y customers/update | Aprovisiona o actualiza un pase de fidelización de miembro emparejado mediante externalId: "shopify_customer_<id>". |
orders/paid | Calcula puntos de fidelización a partir de subtotal_price, incrementa contadores de sellos o emite una tarjeta de regalo digital adquirida (prepaid account). |
orders/cancelled y refunds/create | Revierte puntos no consolidados del saldo del pase o pasa los cupones promocionales de un solo uso a estado VOIDED. |
Ejemplo de mapeo de webhook de pedido de Shopify (POST /api/v1/passes/upsert-by-external-id)
Al desarrollar un middleware personalizado para Shopify o una Checkout UI Extension, invoque directamente el endpoint de upsert idempotente (el archivo .pkpass resultante hereda automáticamente el certificado bundleId configurado en la plantilla):
{
"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. Integración con WooCommerce (POST /webhooks/woocommerce y Automatizaciones Universales)
Las tiendas WooCommerce se conectan mediante https://api.passinstance.com/webhooks/woocommerce o /v1/automations/webhooks/woocommerce/:customerId (verificado mediante el encabezado HMAC-SHA256 X-WC-Webhook-Signature):
-
1
En el panel de administración de WordPress, vaya a WooCommerce -> Ajustes -> Avanzado -> Webhooks.
-
2
Cree webhooks para Pedido actualizado (
order.updated), Pedido completado (order.completed) y Cliente creado (customer.created). -
3
Establezca la URL de entrega en
https://api.passinstance.com/webhooks/woocommercey copie el secreto de firma de su espacio de trabajo. -
4
Cuando un pedido alcanza el estado
completed, Passinstance emite o actualiza automáticamente el pase del cliente (vinculado porexternalId) y devuelve la URL de descarga inteligente (/s/:token) para incluirla en los correos transaccionales de WooCommerce.
Explore conectores adicionales en Integraciones disponibles, proveedores de pago en /settings/workspace/integrations/payment-providers y la Descripción general de la integración con Shopware.
