Skip to content
Guida del Centro assistenza · Piani e utilizzo
4 min di letturaVerificato 2026-11-16

Pass attivi e limiti d'uso

Scopri perché contano solo le registrazioni Wallet attive e come funziona la soglia flessibile 5× creati.

In questa guida

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

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
MISURAZIONE DEI PASS ATTIVI E APPLICAZIONE DELLE QUOTE
FASE 01 CICLO DI VITA DEL PASS ED EVENTI WALLET
Pass creato (Bozza /
URL non riscattato)
Evento salvataggio
(Reg. APNs / JWT Google
Rimozione dal wallet
o annullamento srv
[ 0 Quota attiva ] [ +1 activePasses ] [ Libera quota attiva]
FASE 02 SOGLIE DI QUOTA E MOTORE DI APPLICAZIONE
Soglia flessibile pass creati: totalPasses <= effectiveActivePassLimit * 5
Mostra un avviso consultivo nella Dashboard (non blocca mai i pass attivi)
Limite rigido pass attivi: activePasses >= effectiveActivePassLimit
Rifiuta nuove emissioni/attivazioni con HTTP 403/429 PASS_LIMIT_REACHED

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 activePasses del 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 passConta nella quota activePasses?Motivazione tecnica
Modelli in bozza e anteprimeNo (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. 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.

  1. 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

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
}

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:

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. 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:

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 }
  ]
}

Documentazione correlata

Pronto a lanciare il tuo primo programma di carte Wallet?

Crea il tuo workspace, configura il modello e testa una carta reale in Apple Wallet e Google Wallet prima di scalare.