Panoramica
A differenza dei fornitori legacy di portafogli digitali che addebitano ogni record generato nel database o ogni link email non aperto, Passinstance misura la capacità dell'abbonamento esclusivamente sui Pass attivi nel wallet (activePasses), ovvero istanze di pass attive (pass status.ACTIVE) che dispongono attualmente di almeno una registrazione di dispositivo raggiungibile in Apple Wallet (bundleId / passTypeIdentifier) o Google Wallet.
Può monitorare il consumo in tempo reale nella Dashboard in Impostazioni -> Fatturazione (/settings/billing/overview), tramite GET /api/v1/billing/usage e GET /api/v1/customer/:customerId/usage-summary, oppure tra workspace affiliati tramite GET /api/v1/organizations/current/billing-summary.
Flusso di misurazione della quota in tempo reale e applicazione dei limiti
Importante: Quando un titolare elimina un pass da Apple Wallet o Google Wallet, o quando un amministratore annulla o elimina un'istanza di pass obsoleta, la capacità liberata viene restituita automaticamente al pool
activePassesdel workspace.
Cosa rientra nel calcolo della quota di pass attivi?
In conformità con PASS_ANALYTICS_METRIC_DEFINITIONS (metric-definitions.ts), Passinstance valuta ogni stato del pass come segue:
| Stato del ciclo di vita del pass | Conta nella quota activePasses? | Motivazione tecnica |
|---|---|---|
| Modelli in bozza e anteprime | No (0) | Le anteprime di design e le bozze non pubblicate non hanno registrazioni di dispositivi attive. |
Pass creati / non riscattati (unclaimedPasses) | No (0) | I pass generati tramite importazione CSV, API o campagna email che il cliente non ha ancora salvato nel wallet dello smartphone non consumano quota attiva. |
Installati e raggiungibili (activePasses) | Sì (1 per pass) | Istanze di pass attive con >= 1 registrazione di dispositivo attiva che riceve aggiornamenti push APNs o Google Wallet. |
Disinstallati / rimossi (inactivePasses) | No (0) | Quando tutti i dispositivi annullano la registrazione del pass (DELETE /v1/devices/.../registrations/...), il pass passa a inactivePasses e smette di consumare quota attiva. |
Annullati o scaduti (voidedPasses, expiredPasses) | No (0) | Gli stati terminali del pass sono esclusi da activePasses in metric-definitions.ts. |
Soglia flessibile di pass creati rispetto al limite rigido di pass attivi (PASS_LIMIT_REACHED)
Per proteggere la stabilità dell'infrastruttura da cicli API incontrollati offrendo al contempo ai team di marketing ampio margine per invii di email con tassi di conversione parziali, Passinstance applica una politica a due livelli:
-
1
La soglia flessibile di 5× per i pass creati (
activePassLimit × 5):
- È possibile generare fino a 5 volte il limite di pass attivi in record totali non riscattati (ad esempio, 1.000 pass creati sul piano Starter da 200 pass attivi, oppure 10.000 pass creati sul piano Growth da 2.000 pass attivi). - L'avvicinarsi a questa soglia flessibile mostra un banner informativo nella Dashboard che invita a eliminare i link non riscattati obsoleti o ad aggiornare il piano.
-
2
Limite rigido di pass attivi (
PASS_LIMIT_REACHED):
- Quando il conteggio activePasses attivo raggiunge il 100% di effectiveActivePassLimit, i pass già installati continuano a funzionare e a essere scansionati normalmente, ma le nuove creazioni o attivazioni di pass restituiscono una busta di errore strutturata PASS_LIMIT_REACHED finché non viene liberata capacità o effettuato un upgrade.
Busta di errore standard 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
}
Interrogazione dell'utilizzo in tempo reale e dei riepiloghi di fatturazione dell'organizzazione
1. Riepilogo dei consumi del workspace (GET /api/v1/customer/:customerId/usage-summary)
Recuperi i contatori in tempo reale per i pass attivi, il totale dei pass creati, le scansioni mensili, lo spazio di archiviazione degli asset e il volume delle notifiche 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. Riepilogo aggregato di fatturazione a livello di organizzazione (GET /api/v1/organizations/current/billing-summary)
Per le agenzie e le imprese che gestiscono più workspace affiliati (production, staging, client-a) sotto un'unica Organization ombrello:
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 }
]
}
Documentazione correlata
-
Confronti le fasce di capacità e i componenti aggiuntivi in Prezzi e piani di abbonamento.
-
Effettui l'upgrade o il downgrade del Suo abbonamento in Modifiche al piano e cancellazione.
-
Esamini la distinzione tecnica tra pass e registrazioni di dispositivi in Metriche di emissione e utilizzo dei pass.
