Skip to content
Guia da Central de Ajuda · Integrações externas
3 min de leituraVerificado 2026-11-16

Integrações de e-commerce

Ligue lojas online com a nossa integração nativa Shopware 6 ou emissão REST desencadeada por encomenda.

Neste guia

Visão Geral

O Passinstance faz a ponte entre montras de comércio eletrónico online e caixas de Ponto de Venda (POS) de retalho físico para que os clientes possam acumular pontos de fidelização, resgatar vales promocionais e utilizar saldos de cartões-presente pré-pagos de forma contínua nos canais web e em loja. Pode ligar montras utilizando a nossa suíte nativa de controladores Shopware 6 (/settings/workspace/integrations/shopware no Painel de Controlo), recetores dedicados de webhooks Shopify (POST /webhooks/shopify ou /v1/automations/webhooks/shopify/:customerId) e WooCommerce (POST /webhooks/woocommerce ou /v1/automations/webhooks/woocommerce/:customerId), ou upserts REST idempotentes (POST /api/v1/passes/upsert-by-external-id).

Importante: Mapeie sempre o ID de Cliente ou ID de Encomenda imutável da sua plataforma de comércio eletrónico para o campo externalId do passe (ou combine-o com idempotencyKey). Isto garante que os webhooks de encomenda repetidos atualizam o passe de carteira existente de forma idempotente, em vez de emitirem cartões duplicados.

Arquitetura da Montra para a Carteira

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
SINCRONIZAÇÃO DE ENCOMENDAS E FIDELIZAÇÃO
ATORES DE SISTEMA PARTICIPANTES
P1 Montra Online
P2 Camada E-Commerce Passinstance
P3 Carteira e POS em Loja
ETAPA CTX CONTEXTO App Shopware 6
ETAPA 1a PEDIDO / AÇÃO Handshake e Config.
›
/v1/integrations/shopware/*
›
(ShopwareRegistration e Admin)
ETAPA 1b PEDIDO / AÇÃO Hook de Encomenda / Carrinho
›
POST/v1/integrations/shopware/
›
webhooks
ETAPA 1c PEDIDO / AÇÃO Widget de Passe na Montra
›
Shopware Storefront Widget
ETAPA CTX CONTEXTO Shopify / WooCommerce
ETAPA 2 PEDIDO / AÇÃO POST/webhooks/shopify
›
Verificar HMACUpsert Passe|-- 3. Emitir / Atualizar Passe
›
ou /v1/automations/webhooks/..
›
(externalId = shopify_cust_id)
›
e Enviar Push à Carteira
ETAPA 4 PEDIDO / AÇÃO Resgatar em Loja via
ETAPA 5 RESPOSTA Sinc. Leitura em Loja via Webhook
›
<----------------------------------| POST/v1/pos/redeem

1. Suíte de Integração Nativa Shopware 6

O Passinstance inclui um módulo de backend dedicado e uma consola no Painel de Controlo (/settings/workspace/integrations/shopware) para o Shopware 6 (/shopware), orquestrados por quatro controladores especializados e monitorizados através de ShopwareInstallationStatus (PENDING | REGISTERED | CONNECTED | DEACTIVATED | UNINSTALLED):

ControladorCaminhos MontadosOperações Principais
Shopware Onboarding API/v1/integrations/shopware/registration, /v1/integrations/shopware/lifecycle/:actionGere o handshake do Sistema de Aplicações Shopware, verificação de assinaturas, rotação de segredos e transições de desinstalação (UNINSTALLED).
Shopware Admin API/api/v1/integrations/shopware/admin/*Liga um canal de vendas Shopware a um espaço de trabalho Passinstance, mapeia modelos (PassKind) para grupos de clientes e gere regras de automatização.
Shopware Storefront Widget/api/v1/integrations/shopware/storefront/*Apresenta botões personalizados Adicionar à Apple Wallet / Guardar na Google Wallet, passes de convidado/encomenda e resgates com reserva (reserve-redemption / capture-redemption).
Shopware Webhook Handler/v1/integrations/shopware/webhooksProcessa hooks checkout.order.placed, order_transaction.state.paid, customer.written e cancelamentos/reembolsos para atribuir pontos ou anular vales.

2. Integração Shopify (POST /webhooks/shopify e Automatizações Universais)

Ligue a sua loja Shopify ou Shopify Plus apontando as subscrições de webhooks da Shopify para https://api.passinstance.com/webhooks/shopify — ou configure regras de automatização do espaço de trabalho através de /v1/automations/webhooks/shopify/:customerId (autenticado através de X-Shopify-Hmac-Sha256):

Tópico da ShopifyComportamento do Processador Passinstance
customers/create e customers/updateAprovisiona ou atualiza um passe de fidelização de membro correspondido por externalId: "shopify_customer_<id>".
orders/paidCalcula pontos de fidelização a partir de subtotal_price, incrementa contadores de carimbos ou emite um cartão-presente digital adquirido (prepaid account).
orders/cancelled e refunds/createReverte pontos não adquiridos do saldo do passe ou transita cupões promocionais de utilização única para VOIDED.

Exemplo de Mapeamento de Webhook de Encomenda Shopify (POST /api/v1/passes/upsert-by-external-id)

Ao desenvolver um middleware personalizado para Shopify ou uma Checkout UI Extension, invoque diretamente o endpoint de upsert idempotente (o .pkpass resultante herda automaticamente o certificado bundleId configurado no modelo):

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. Integração WooCommerce (POST /webhooks/woocommerce e Automatizações Universais)

As lojas WooCommerce ligam-se através de https://api.passinstance.com/webhooks/woocommerce ou /v1/automations/webhooks/woocommerce/:customerId (verificado através do cabeçalho HMAC-SHA256 X-WC-Webhook-Signature):

  1. 1
    Na administração do WordPress, navegue até WooCommerce -> Definições -> Avançado -> Webhooks.
  2. 2
    Crie webhooks para Encomenda atualizada (order.updated), Encomenda concluída (order.completed) e Cliente criado (customer.created).
  3. 3
    Defina o URL de Entrega como https://api.passinstance.com/webhooks/woocommerce e copie o segredo de assinatura do seu espaço de trabalho.
  4. 4
    Quando uma encomenda atinge o estado completed, o Passinstance emite ou atualiza automaticamente o passe do cliente (indexado por externalId) e devolve o URL inteligente de transferência (/s/:token) para inclusão nos e-mails transacionais do WooCommerce.

Explore conectores adicionais em Integrações Disponíveis, fornecedores de pagamento em /settings/workspace/integrations/payment-providers e a Visão Geral da Integração Shopware.

Documentação de produto e API relacionada

Pronto para lançar o seu primeiro programa de cartões Wallet?

Crie o seu espaço de trabalho, configure o seu modelo e teste um cartão real na Apple Wallet e Google Wallet antes de escalar.