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
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
activePassesdo 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 Passe | Conta para a Quota activePasses? | Justificação Técnica |
|---|---|---|
| Modelos em Rascunho e Pré-visualizações | Nã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
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.
-
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
{
"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:
GET /api/v1/customer/cus_89a12b34-56c7-4d89-9e01-23456789abcd/usage-summary HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
{
"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:
GET /api/v1/organizations/current/billing-summary HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
{
"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
-
Compare escalões de capacidade e extras em Preços e Planos de Subscrição.
-
Atualize ou reduza a sua subscrição em Alterações de Plano e Cancelamento.
-
Consulte a distinção técnica entre passes e registos de dispositivos em Métricas de Emissão e Utilização de Passes.
