Skip to content
Guide du centre d'aide · Forfaits & utilisation
4 min de lectureVérifié 2026-11-16

Passes actifs & limites d'usage

Découvrez pourquoi seules les inscriptions Wallet actives sont décomptées et le fonctionnement du seuil souple ×5.

Dans ce guide

Présentation

Contrairement aux fournisseurs historiques de portefeuilles numériques qui facturent chaque enregistrement généré en base de données ou chaque lien e-mail non ouvert, Passinstance mesure la capacité d'abonnement strictement sur les passes de portefeuille actifs (activePasses) — des instances de passes en production (pass status.ACTIVE) qui disposent actuellement d'au moins un enregistrement d'appareil joignable dans Apple Wallet (bundleId / passTypeIdentifier) ou Google Wallet.

Vous pouvez suivre votre consommation en temps réel dans le tableau de bord sous Settings -> Billing (/settings/billing/overview), via GET /api/v1/billing/usage et GET /api/v1/customer/:customerId/usage-summary, ou à travers des espaces de travail affiliés via GET /api/v1/organizations/current/billing-summary.

Flux de mesure des quotas en temps réel et d'application des limites

FLUX ARCHITECTURE SYSTÈME
ARCHITECTURE INTERACTIVE
FLUX D'ARCHITECTURE SYSTÈME : MESURE DES PASSES ACTIFS ET APPLICATION DES QUOTAS
ÉTAPE 01 CYCLE DE VIE DU PASS ET ÉVÉNEMENTS DE PORTEFEUILLE
Pass créé (Brouillon /
URL non réclamée)
Événement d'ajout
(Enreg. APNs / JWT)
Désinstallation /
Révocation serveur
[ 0 Quota actif ] [ +1 activePasses ] [ Libère le quota ]
ÉTAPE 02 SEUILS DE QUOTA ET MOTEUR D'APPLICATION
Seuil souple de passes créés : totalPasses <= effectiveActivePassLimit * 5
Émet un avertissement dans le tableau de bord (n'interrompt pas les passes)
Plafond strict de passes actifs : activePasses >= effectiveActivePassLimit
Rejette les nouvelles émissions/activations avec HTTP 403/429 PASS_LIMIT_REACHED

Important : Lorsqu'un détenteur de pass supprime un pass d'Apple Wallet ou de Google Wallet, ou lorsqu'un administrateur révoque/supprime une instance de pass obsolète, la capacité libérée est automatiquement restituée au pool activePasses de votre espace de travail.

Qu'est-ce qui est comptabilisé dans votre quota de passes actifs ?

Conformément à PASS_ANALYTICS_METRIC_DEFINITIONS (metric-definitions.ts), Passinstance évalue chaque état de pass comme suit :

État du cycle de vie du passComptabilisé dans le quota activePasses ?Justification technique
Modèles brouillons et aperçusNon (0)Les aperçus de conception et les brouillons non publiés n'ont aucun enregistrement d'appareil en production.
Passes créés / non réclamés (unclaimedPasses)Non (0)Les passes générés via import CSV, API ou campagne d'e-mailing que le client n'a pas encore enregistrés dans le portefeuille de son téléphone ne consomment aucun quota actif.
Installés et joignables (activePasses)Oui (1 par pass)Instances de passes en production avec >= 1 enregistrement d'appareil actif recevant des mises à jour push APNs ou Google Wallet.
Désinstallés / retirés (inactivePasses)Non (0)Dès que tous les appareils désenregistrent le pass (DELETE /v1/devices/.../registrations/...), le pass passe à l'état inactivePasses et cesse de consommer du quota actif.
Révoqués ou expirés (voidedPasses, expiredPasses)Non (0)Les états de pass terminaux sont exclus de activePasses dans metric-definitions.ts.

Seuil souple de passes créés vs limite stricte de passes actifs (PASS_LIMIT_REACHED)

Pour protéger la stabilité de l'infrastructure contre les boucles d'API incontrôlées tout en offrant aux équipes marketing une marge généreuse pour les envois d'e-mails à taux de conversion partiel, Passinstance applique une politique à deux niveaux :

  1. 1
    Le seuil souple de 5× sur les passes créés (activePassLimit × 5) :

- Vous pouvez générer jusqu'à 5 fois votre limite de passes actifs en nombre total d'enregistrements non réclamés (par ex., 1 000 passes créés sur le forfait Starter à 200 actifs, ou 10 000 passes créés sur le forfait Growth à 2 000 actifs). - Lorsque vous approchez de ce seuil souple, une bannière d'avertissement s'affiche dans le tableau de bord pour vous inviter à purger les anciens liens non réclamés ou à passer à un forfait supérieur.

  1. 2
    Limite stricte de passes actifs (PASS_LIMIT_REACHED) :

- Lorsque votre compteur activePasses en production atteint 100 % de votre effectiveActivePassLimit, les passes installés existants continuent de fonctionner et d'être scannés normalement, mais les nouvelles créations ou activations de passes renvoient une enveloppe d'erreur structurée PASS_LIMIT_REACHED jusqu'à ce que de la capacité soit libérée ou que le forfait soit mis à niveau.

Enveloppe d'erreur 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
}

Interrogation de l'utilisation en temps réel et des cumuls de facturation d'organisation

1. Résumé de consommation de l'espace de travail (GET /api/v1/customer/:customerId/usage-summary)

Récupérez les compteurs en temps réel pour les passes actifs, le total des passes créés, les scans mensuels, le stockage de ressources et le volume de notifications 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. Cumul de facturation à l'échelle de l'organisation (GET /api/v1/organizations/current/billing-summary)

Pour les agences et les entreprises gérant plusieurs espaces de travail affiliés (production, staging, client-a) sous une même entité Organization :

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

Documentation connexe

Prêt à lancer votre premier programme de cartes Wallet ?

Créez votre espace de travail, configurez votre modèle et testez une vraie carte dans Apple Wallet et Google Wallet avant de déployer à grande échelle.