Skip to content
Guia da Central de Ajuda · Planos e utilização
4 min de leituraVerificado 2026-11-16

Passes ativos e limites de uso

Saiba porque apenas registos ativos em Wallet contam e como funciona o limite flexível 5× para criação.

Neste guia

Visão Geral

Ao contrário dos fornecedores tradicionais de carteiras digitais que cobram por cada registo gerado na base de dados ou ligação de e-mail não aberta, o Passinstance contabiliza a capacidade da subscrição estritamente com base em Passes Ativos na Carteira (activePasses) — instâncias de passes ativas (pass status.ACTIVE) que possuem atualmente pelo menos um registo de dispositivo contactável na Apple Wallet (bundleId / passTypeIdentifier) ou na Google Wallet.

Pode monitorizar o consumo em tempo real no Painel de Controlo em Definições -> Faturação (/settings/billing/overview), através de GET /api/v1/billing/usage e GET /api/v1/customer/:customerId/usage-summary, ou em múltiplos espaços de trabalho associados através de GET /api/v1/organizations/current/billing-summary.

Fluxo de Contabilização de Quotas em Tempo Real e Aplicação de Limites

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
CONTABILIZAÇÃO DE PASSES ATIVOS E QUOTAS
ETAPA 01 CICLO DE VIDA DO PASSE E EVENTOS DA CARTEIRA
Passe Criado (Rascunho
/ URL Não Reclamado)
Evento de Guardar na
Carteira (APNs/JWT)
Desinstalação ou
Anulação no Servidor
[ 0 Quota Ativa ] [ +1 activePasses ] [ Liberta Quota Ativa ]
ETAPA 02 LIMIARES DE QUOTA E MOTOR DE APLICAÇÃO
Limiar Suave de Passes Criados: totalPasses <= effectiveActivePassLimit * 5
Emite Aviso Preventivo no Painel (Nunca Afeta Passes Instalados Ativos)
Limite Rígido de Passes Ativos: activePasses >= effectiveActivePassLimit
Rejeita Novas Emissões/Ativações com HTTP 403/429 PASS_LIMIT_REACHED

Importante: Quando um titular elimina um passe da Apple Wallet ou da Google Wallet, ou quando um administrador anula/elimina uma instância de passe obsoleta, a capacidade libertada é devolvida automaticamente ao conjunto activePasses do seu espaço de trabalho.

O Que Conta para a Sua Quota de Passes Ativos?

Em conformidade com PASS_ANALYTICS_METRIC_DEFINITIONS (metric-definitions.ts), o Passinstance avalia cada estado do passe da seguinte forma:

Estado do Ciclo de Vida do PasseConta para a Quota activePasses?Justificação Técnica
Modelos em Rascunho e Pré-visualizaçõesNão (0)As pré-visualizações de design e os rascunhos não publicados não possuem registos de dispositivos ativos.
Passes Criados / Não Reclamados (unclaimedPasses)Não (0)Os passes gerados por importação CSV, API ou campanha de e-mail em que o cliente ainda não guardou o passe na carteira do telemóvel não consomem quota ativa.
Instalados e Contactáveis (activePasses)Sim (1 por passe)Instâncias de passes ativas com >= 1 registo de dispositivo ativo a receber atualizações push de APNs ou da Google Wallet.
Desinstalados / Removidos (inactivePasses)Não (0)Assim que todos os dispositivos cancelam o registo do passe (DELETE /v1/devices/.../registrations/...), o passe transita para inactivePasses e deixa de consumir quota ativa.
Anulados ou Expirados (voidedPasses, expiredPasses)Não (0)Os estados terminais do passe são excluídos de activePasses em metric-definitions.ts.

Limiar Suave de Passes Criados vs. Limite Rígido de Passes Ativos (PASS_LIMIT_REACHED)

Para proteger a estabilidade da infraestrutura contra ciclos descontrolados de API e, simultaneamente, dar às equipas de marketing uma margem generosa para envios de e-mail com taxas de conversão parciais, o Passinstance aplica uma política de dois níveis:

  1. 1
    O Limiar Suave de 5× para Passes Criados (activePassLimit × 5):

- Pode gerar até 5 vezes o seu limite de passes ativos no total de registos não reclamados (por exemplo, 1 000 passes criados no plano Starter de 200 ativos, ou 10 000 passes criados no plano Growth de 2 000 ativos). - Ao aproximar-se deste limiar suave, é apresentada uma faixa informativa no painel de controlo que o aconselha a limpar ligações não reclamadas antigas ou a atualizar o seu plano.

  1. 2
    Limite Rígido de Passes Ativos (PASS_LIMIT_REACHED):

- Quando a contagem de activePasses ativos atinge 100% do seu effectiveActivePassLimit, os passes instalados existentes continuam a funcionar e a ser lidos normalmente, mas novas criações ou ativações de passes devolvem um envelope de erro estruturado PASS_LIMIT_REACHED até que seja libertada capacidade ou o plano seja atualizado.

Envelope de Erro Padrão PASS_LIMIT_REACHED

JSON
{
  "success": false,
  "error": "FORBIDDEN",
  "messageKey": "api.errors.passLimitReached",
  "message": "Workspace active pass limit reached. Please upgrade your subscription plan or archive inactive passes.",
  "statusCode": 403,
  "timestamp": "2026-11-15T23:35:40.000Z",
  "path": "/api/v1/passes",
  "requestId": "req_9c410e2a",
  "code": "LIMIT_EXCEEDED",
  "errorCode": "PASS_LIMIT_REACHED",
  "activePasses": 200,
  "limit": 200,
  "upgradeRequired": true
}

Consultar Utilização em Tempo Real e Consolidações de Faturação da Organização

1. Resumo de Consumo do Espaço de Trabalho (GET /api/v1/customer/:customerId/usage-summary)

Obtenha contadores em tempo real para passes ativos, total de passes criados, leituras mensais, armazenamento de recursos e volume de notificações push:

HTTP
GET /api/v1/customer/cus_89a12b34-56c7-4d89-9e01-23456789abcd/usage-summary HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
JSON
{
  "customerId": "cus_89a12b34-56c7-4d89-9e01-23456789abcd",
  "planId": "growth_monthly",
  "meters": {
    "activePasses": {
      "used": 1420,
      "limit": 2000,
      "remaining": 580,
      "utilizationPercent": 71.0
    },
    "createdPassesSoftLimit": {
      "used": 3890,
      "softLimit": 10000,
      "warningActive": false
    },
    "scansThisPeriod": {
      "count": 14820
    },
    "pushNotificationsThisPeriod": {
      "count": 18420
    },
    "storageBytes": {
      "used": 148902400,
      "limit": 5368709120
    }
  }
}

2. Consolidação de Faturação ao Nível da Organização (GET /api/v1/organizations/current/billing-summary)

Para agências e empresas que gerem múltiplos espaços de trabalho associados (production, staging, client-a) sob uma única Organization principal:

HTTP
GET /api/v1/organizations/current/billing-summary HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
JSON
{
  "organizationId": "org_01933001-2233-7a00-8b11-001122334455",
  "organizationName": "Phenix Group Holdings",
  "totalWorkspaces": 3,
  "aggregatedActivePasses": 4810,
  "aggregatedEffectiveLimit": 12200,
  "workspaces": [
    { "customerId": "cus_89a12b34", "name": "Phenix Flagship (Prod)", "plan": "scale_10k", "activePasses": 3380, "limit": 10000 },
    { "customerId": "cus_77b21c45", "name": "Phenix Boutique", "plan": "growth", "activePasses": 1425, "limit": 2000 },
    { "customerId": "cus_66c32d56", "name": "Phenix Sandbox", "plan": "starter", "activePasses": 5, "limit": 200 }
  ]
}

Documentação 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.