Skip to content
Guía del Centro de ayuda · Integraciones externas
3 min de lecturaVerificado 2026-11-16

Integraciones e-commerce

Conecta tiendas online con nuestra integración nativa Shopware 6 o emisión REST por webhooks.

En esta guía

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 externalId del pase (o combínelo con idempotencyKey). 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

FLUJO DE ARQUITECTURA
ARQUITECTURA INTERACTIVA
SINCRONIZACIÓN DE PEDIDOS Y FIDELIZACIÓN E-COMMERCE
ACTORES DEL SISTEMA
P1 Tienda online
P2 Capa e-commerce Passinstance
P3 Wallet y POS en tienda
PASO CTX CONTEXTO App Shopware 6
PASO 1a SOLICITUD / ACCIÓN Handshake y configuración
›
/v1/integrations/shopware/*
›
(ShopwareRegistration y Admin)
PASO 1b SOLICITUD / ACCIÓN Hook de pedido / carrito
›
POST/v1/integrations/shopware/
›
webhooks
PASO 1c SOLICITUD / ACCIÓN Widget de pase en tienda
›
Shopware Storefront Widget
PASO CTX CONTEXTO Shopify / WooCommerce
PASO 2 SOLICITUD / ACCIÓN POST/webhooks/shopify
›
Verificar HMACUpsert Pass|-- 3. Emitir / Actualizar pase
›
o /v1/automations/webhooks/..
›
(externalId = shopify_cust_id)
›
y push a Wallet
PASO 4 SOLICITUD / ACCIÓN Canje en tienda vía
PASO 5 RESPUESTA Sincronizar escaneo vía Webhook
›
<----------------------------------| POST/v1/pos/redeem

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

ControladorRutas montadasOperaciones principales
Shopware Onboarding API/v1/integrations/shopware/registration, /v1/integrations/shopware/lifecycle/:actionGestiona 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/webhooksProcesa 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 ShopifyComportamiento del manejador de Passinstance
customers/create y customers/updateAprovisiona o actualiza un pase de fidelización de miembro emparejado mediante externalId: "shopify_customer_<id>".
orders/paidCalcula 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/createRevierte 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):

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. 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. 1
    En el panel de administración de WordPress, vaya a WooCommerce -> Ajustes -> Avanzado -> Webhooks.
  2. 2
    Cree webhooks para Pedido actualizado (order.updated), Pedido completado (order.completed) y Cliente creado (customer.created).
  3. 3
    Establezca la URL de entrega en https://api.passinstance.com/webhooks/woocommerce y copie el secreto de firma de su espacio de trabajo.
  4. 4
    Cuando un pedido alcanza el estado completed, Passinstance emite o actualiza automáticamente el pase del cliente (vinculado por externalId) 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.

Documentación de producto y API relacionada

¿Listo para lanzar su primer programa de tarjetas Wallet?

Cree su espacio de trabajo, configure su plantilla y pruebe una tarjeta real en Apple Wallet y Google Wallet antes de escalar.