Skip to content
Guia da Central de Ajuda
3 min de leituraVerificado 2026-11-16

Cartões de sócio e subscrição

Substitua cartões plásticos de clubes, ginásios e associações por cartões com datas de renovação sempre atualizadas.

Neste guia

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): membership ou generic (apresenta credenciais de membro com selos de patamar nítidos e cabeçalhos com data de validade).
  • Modelos Demo de Catálogo: gym-membership e hotel-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.

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
CICLO DE RENOVAÇÃO DE SUBSCRIÇÃO
ATORES DE SISTEMA PARTICIPANTES
P1 Webhook Stripe / CRM
P2 API Principal Passinstance
P3 Base de Dados Passinstance database
P4 Carteira Dispositivo Sócio
ETAPA CTX CONTEXTO customer.subscription.updated
ETAPA 1 PEDIDO / AÇÃO POST/api/v1/passes/upsert-by-external-id
ETAPA 2 PEDIDO / AÇÃO Prolongar Validade
›
expirationDate: "2027-12-31 23:59")
›
(Atualizar Registo e
›
limpar suspensões)
ETAPA 3 PEDIDO / AÇÃO Push APNs Silencioso
ETAPA 4 RESPOSTA 200 OK ({ data: { pass, action } })
›
e Google REST PATCH | (Alerta Ecrã Bloq.
›
"Subscrição renovada")

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 (ou PUT /api/v1/passes/by-external-id/:externalId) indexado por externalId (restrição única customerId + externalId entre passes ativos não eliminados).
  • A Passinstance cria o cartão (action: "CREATED") se nenhum passe ativo corresponder a externalId, ou funde attributes, expirationDate e status: "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 bundleId partilhado (/api/v1/bundles) ou PassProject para 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_EXPIRATION adiciona automaticamente um intervalo configurado (ex.: +30 dias) a expirationDate sempre 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 verifica status === ACTIVE e 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: true nas 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.

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.