Visão Geral
O Passinstance disponibiliza superfícies de integração de primeira classe para plataformas de automatização sem código (Zapier, Make), montras de comércio eletrónico, sistemas CRM, processadores de pagamentos e clouds de marketing, configuradas em Definições do Espaço de Trabalho -> Integrações (/settings/workspace/integrations, /connectors, /connected-apps e /link-generator). Além da API REST /api/v1 e dos webhooks de saída, o Passinstance expõe uma superfície de descoberta OAuth/iPaaS (Integrations API) e recetores de webhooks de entrada de fornecedores sem prefixo (/webhooks/*).
Importante: Os endpoints de webhooks de entrada de fornecedores (
/webhooks/stripe,/webhooks/shopify, etc.) estão explicitamente excluídos do prefixo global/api/v1emmain.ts, para que correspondam imediatamente às convenções estritas de URLs de callback e aos verificadores de assinatura criptográfica de fornecedores terceiros.
Arquitetura de Conectividade de Integrações
Superfície de Integração OAuth para Zapier e Make (Integrations API)
Os construtores de automatização low-code ligam-se ao Passinstance através de tokens Bearer OAuth 2.0 (OAuth 2.0 Authentication + Permission Scope Validation) sob /api/v1:
| Método | Endpoint | Âmbito OAuth Necessário | Finalidade no Zapier / Make |
|---|---|---|---|
| GET | /api/v1/me | Token OAuth2 válido | Verifica as credenciais de ligação e devolve o contexto autenticado do tenant e do utilizador (Connected Integrations API). |
| GET | /api/v1/templates/:templateId/attributes | templates:read | Preenche dinamicamente os campos personalizados do modelo (memberName, points, tier) dentro do editor de ações. |
| POST | /api/v1/webhook-subscriptions | webhooks:write | Regista uma subscrição de webhook ({ event, targetUrl, metadata? }) quando um utilizador ativa um Zap ou cenário. |
GET / DELETE | /api/v1/webhook-subscriptions | webhooks:read / webhooks:write | Lista ou remove subscrições de webhooks geridas por OAuth (/api/v1/oauth/connections para a interface de aplicações ligadas). |
Categorias integration category Suportadas
Ao criar integrações no espaço de trabalho (/api/v1/integrations), o Passinstance classifica os conectores utilizando o integration category do Passinstance database com 21 valores: CRM, MARKETING_AUTOMATION, PAYMENT, TICKETING, GEOLOCATION, NOTIFICATIONS, ANALYTICS, INVENTORY, ACCOUNTING, CREATE_PASS_URL, FTP_JOB, IFRAME_PASS_DOWNLOAD, GOOGLE_ANALYTICS, NFC_PERSONALIZATION, PASS_DATA_FTP_UPLOAD, NAS_DATA_FTP_UPLOAD, FTP_IMPORT_JOB, FTP_EXPORT_JOB, EMBED_PASS_DOWNLOAD, WEB_ANALYTICS e PARAMETERIZED_PASS_LINK.
Rotas Dedicadas de Webhooks de Entrada de Fornecedores (/webhooks/*)
O Passinstance disponibiliza recetores dedicados de webhooks de entrada com verificação de assinatura para 10 grandes plataformas de comércio, CRM, mensagens e eventos (além de /v1/automations/webhooks/shopify/:customerId e /woocommerce/:customerId para correspondência multi-tenant de regras de montra):
| Plataforma do Fornecedor | Rota de Callback de Entrada | Eventos Acionadores Típicos Processados | Ação Automatizada no Passinstance |
|---|---|---|---|
| Stripe | POST /webhooks/stripe e POST /webhooks/stripe/billing | checkout.session.completed, invoice.paid, customer.subscription.deleted | Emite passes de adesão pagos (webhook de PassFlow também em /api/v1/pass-flows/public/webhooks/stripe) ou anula em caso de cancelamento. |
| Shopify | POST /webhooks/shopify | orders/paid, orders/cancelled, customers/create, refunds/create | Emite/atualiza cartões de fidelização ou cartões-presente (externalId) e anula vales reembolsados. |
| WooCommerce | POST /webhooks/woocommerce | order.completed, order.refunded, customer.created | Aprovisiona cartões de crédito de loja, atualiza pontos de fidelização e sincroniza resgates de encomendas. |
| Salesforce | POST /webhooks/salesforce | Outbound Message / Evento de Plataforma (Contact, Opportunity, CampaignMember) | Emite passes VIP quando negócios são fechados (X-Passinstance-Salesforce-Signature). |
| HubSpot | POST /webhooks/hubspot | contact.creation, contact.propertyChange, deal.propertyChange | Inscreve contactos de CRM em Experiências na Carteira e sincroniza alterações de escalão. |
| Klaviyo | POST /webhooks/klaviyo | Ação de Webhook de Fluxo (Entrada em segmento, marco VIP, fluxo de aniversário) | Gera ligações de passes personalizadas ou aciona notificações push no ecrã bloqueado. |
| Twilio | POST /webhooks/twilio | Callbacks de estado de entrega SMS e adesões por palavra-chave SMS de entrada | Monitoriza recibos de entrega de passes por SMS e emite passes quando os clientes enviam uma palavra-chave por mensagem. |
| Eventbrite | POST /webhooks/eventbrite | order.placed, attendee.updated, attendee.checked_in | Emite bilhetes de eventos Apple/Google Wallet (.pkpass assinado com bundleId) e sincroniza o estado de registo de entrada na porta. |
| Typeform | POST /webhooks/typeform | Webhook de submissão form_response | Converte submissões de inquéritos ou formulários de angariação de contactos diretamente em passes de carteira personalizados. |
| Zoho CRM | POST /webhooks/zoho | Webhook de regra de fluxo de trabalho (Leads, Contacts, Deals) | Emite e atualiza cartões de membro a partir de transições de fluxo de trabalho no Zoho CRM. |
Opções Adicionais de Conectividade Nativa
-
Plugin Nativo Shopware 6: Suíte completa de controladores de administração, montra, registo e webhooks (/shopware e Integrações de Comércio Eletrónico).
-
Sincronização Agendada em Lote FTP / SFTP: Tarefas noturnas automatizadas de importação e exportação CSV (
FTP_IMPORT_JOB/FTP_EXPORT_JOB) para sistemas ERP tradicionais e POS de retalho. -
URLs Dinâmicos de Carteira e Widgets Incorporáveis: Geração de URLs assinados (
/settings/workspace/integrations/link-generator) e botões HTML prontos a incorporar (EMBED_PASS_DOWNLOAD,IFRAME_PASS_DOWNLOAD).
Explore todos os conectores em /integrations e descubra a automatização interna de regras em Configuração de Fluxos de Trabalho.
