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
externalIddo passe (ou combine-o comidempotencyKey). 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
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):
| Controlador | Caminhos Montados | Operações Principais |
|---|---|---|
Shopware Onboarding API | /v1/integrations/shopware/registration, /v1/integrations/shopware/lifecycle/:action | Gere 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/webhooks | Processa 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 Shopify | Comportamento do Processador Passinstance |
|---|---|
customers/create e customers/update | Aprovisiona ou atualiza um passe de fidelização de membro correspondido por externalId: "shopify_customer_<id>". |
orders/paid | Calcula 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/create | Reverte 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):
{
"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
Na administração do WordPress, navegue até WooCommerce -> Definições -> Avançado -> Webhooks.
-
2
Crie webhooks para Encomenda atualizada (
order.updated), Encomenda concluída (order.completed) e Cliente criado (customer.created). -
3
Defina o URL de Entrega como
https://api.passinstance.com/webhooks/woocommercee copie o segredo de assinatura do seu espaço de trabalho. -
4
Quando uma encomenda atinge o estado
completed, o Passinstance emite ou atualiza automaticamente o passe do cliente (indexado porexternalId) 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.
