Visão geral
Clubes de fitness, associações desportivas, clubes sociais privados, espaços de coworking e organizações sem fins lucrativos substituem cartões de sócio em plástico dispendiosos por passes digitais em direto na Apple Wallet e Google Wallet. Os cartões refletem o patamar de subscrição ativo, atualizam automaticamente as datas de renovação após pagamento e aplicam validação de check-in diário nas receções.
Arquitetura no backend e tipos de passe
No backend da Passinstance, as credenciais de subscrição tiram partido de layouts dedicados a membros:
-
Tipo de Passe (pass type):
membershipougeneric(apresenta credenciais de membro com selos de patamar nítidos e cabeçalhos com data de validade). -
Modelos Demo de Catálogo:
gym-membershipehotel-membership. -
Tipo de Mecânica (mechanic type):
RENEW_EXPIRATION. -
Esquema principal de sócio:
- primaryFields: Nome completo do sócio ({fullName}). - secondaryFields: Patamar de sócio ({membershipTier}) e Estado ({status}). - auxiliaryFields: N.º de sócio ({memberNumber}) e Sócio desde ({memberSince}). - headerFields: Data de validade ({expirationDate}) formatada via ISO 8601 com formatação localizada.
Extensão automática da validade e sincronização de renovações
A Passinstance disponibiliza dois fluxos distintos de renovação:
1. Integração CRM e faturação orientada por webhooks
Quando um sócio renova a sua subscrição recorrente através da Stripe, Recurly ou software próprio de faturação:
-
O sistema externo de faturação envia um pedido idempotente para
POST /api/v1/passes/upsert-by-external-id(ouPUT /api/v1/passes/by-external-id/:externalId) indexado porexternalId(restrição únicacustomerId+externalIdentre passes ativos não eliminados). -
A Passinstance cria o cartão (
action: "CREATED") se nenhum passe ativo corresponder aexternalId, ou fundeattributes,expirationDateestatus: "ACTIVE"atualizados (action: "UPDATED"), devolvendo{ success: true, data: { pass, action: "CREATED" | "UPDATED" } }. -
Um push silencioso em segundo plano atualiza o cartão na Apple Wallet e Google Wallet, apresentando um alerta nativo no ecrã bloqueado quando os campos definem mensagens de alteração
%@. -
Para planos familiares ou agregados, associe cartões de membros sob um
bundleIdpartilhado (/api/v1/bundles) ouPassProjectpara que todos os passes sejam instalados em conjunto.
2. Expiração orientada por check-in (RENEW_EXPIRATION)
Para subscrições por pacote de entradas ou prolongadas por visita:
-
A mecânica
RENEW_EXPIRATIONadiciona automaticamente um intervalo configurado (ex.:+30 dias) aexpirationDatesempre que o passe é lido com sucesso num torniquete de entrada.
Controlos de segurança e invariantes antipartilha
Para proteger as receitas recorrentes de subscrições, a Passinstance implementa restrições de partilha ao nível do dispositivo:
-
Restrição de AirDrop na Apple Wallet (
sharingProhibited: true): Oculta os ícones nativos de partilha de passe e AirDrop do iOS, vinculando estritamente o cartão de sócio à conta iCloud verificada do sócio e aos dispositivos registados. -
Edições em autoatendimento controladas (
allowUserEdits: true): Permite aos sócios atualizar dados pessoais autorizados (como telefone ou e-mail de contacto) através de um portal web seguro, bloqueando campos críticos (expirationDate,membershipTier,memberNumber) atrás de controlos de perfil administrativo. -
Proteções no torniquete de receção (
CHECK_IN scan mode): A app Passinstance Scanner verificastatus === ACTIVEe confirma que o passe não expirou nem foi assinalado por falha de pagamento.
Autoatendimento para sócios e emissão em massa
-
Registo de novos sócios: Integre novos sócios sem fricção utilizando formulários públicos PassFlow com pagamentos integrados por cartão ou verificação OTP por SMS.
-
Sincronização da lista de sócios existente: Importe milhares de sócios existentes em poucos minutos através do Worker CSV de Operações em Lote (
POST /api/v1/batch-processing), sem introdução manual de dados.
Importante: Ativar
sharingProhibited: truenas definições do modelo impede os sócios de ginásios e clubes de enviarem por mensagem ou AirDrop o seu passe de sócio ativo a convidados não pagantes.
Saiba mais em Cartões de Sócio, Centros de Fitness e Clubes e Subscrições sem fins lucrativos.
