Descripción General
A diferencia de los proveedores heredados de billeteras digitales que facturan por cada registro generado en la base de datos o cada enlace de correo electrónico sin abrir, Passinstance mide la capacidad de suscripción estrictamente sobre los Pases de Billetera Activos (activePasses): instancias de pases en vivo (pass status.ACTIVE) que cuentan actualmente con al menos un registro de dispositivo alcanzable en Apple Wallet (bundleId / passTypeIdentifier) o Google Wallet.
Puede supervisar el consumo en tiempo real en el Panel bajo Configuración -> Facturación (/settings/billing/overview), mediante GET /api/v1/billing/usage y GET /api/v1/customer/:customerId/usage-summary, o entre espacios de trabajo hermanos mediante GET /api/v1/organizations/current/billing-summary.
Flujo de Medición de Cuotas y Aplicación de Límites en Tiempo Real
Importante: Cuando un titular elimina un pase de Apple Wallet o Google Wallet, o cuando un administrador anula o elimina una instancia de pase obsoleta, la capacidad liberada se devuelve automáticamente al grupo de
activePassesde su espacio de trabajo.
¿Qué Cuenta para su Cuota de Pases Activos?
De acuerdo con PASS_ANALYTICS_METRIC_DEFINITIONS (metric-definitions.ts), Passinstance evalúa cada estado del pase de la siguiente manera:
| Estado del Ciclo de Vida del Pase | ¿Cuenta para la Cuota activePasses? | Justificación Técnica |
|---|---|---|
| Plantillas en Borrador y Vistas Previas | No (0) | Las vistas previas de diseño y los borradores no publicados no tienen registros de dispositivos activos. |
Pases Creados / No Reclamados (unclaimedPasses) | No (0) | Los pases generados mediante importación CSV, API o campaña de correo electrónico en los que el cliente aún no ha guardado el pase en la billetera de su teléfono no consumen cuota activa. |
Instalados y Alcanzables (activePasses) | Sí (1 por pase) | Instancias de pases en vivo con >= 1 registro de dispositivo activo que recibe actualizaciones push de APNs o Google Wallet. |
Desinstalados / Eliminados (inactivePasses) | No (0) | Una vez que todos los dispositivos cancelan el registro del pase (DELETE /v1/devices/.../registrations/...), el pase pasa a inactivePasses y deja de consumir cuota activa. |
Anulados o Expirados (voidedPasses, expiredPasses) | No (0) | Los estados terminales de los pases están excluidos de activePasses en metric-definitions.ts. |
Umbral Flexible de Pases Creados frente a Límite Estricto Activo (PASS_LIMIT_REACHED)
Para proteger la estabilidad de la infraestructura contra bucles descontrolados de API y, al mismo tiempo, ofrecer a los equipos de marketing un margen amplio para envíos de correo electrónico con tasas de conversión parciales, Passinstance aplica una política de dos niveles:
-
1
El Umbral Flexible de 5× para Pases Creados (
activePassLimit × 5):
- Puede generar hasta 5 veces su límite de pases activos en registros totales no reclamados (por ejemplo, 1,000 pases creados en el plan Starter de 200 activos, o 10,000 pases creados en el plan Growth de 2,000 activos). - Al acercarse a este umbral flexible, aparece un aviso informativo en el panel que le sugiere depurar los enlaces antiguos no reclamados o mejorar su plan.
-
2
Límite Estricto de Pases Activos (
PASS_LIMIT_REACHED):
- Cuando su recuento en vivo de activePasses alcanza el 100 % de su effectiveActivePassLimit, los pases instalados existentes siguen funcionando y escaneándose con normalidad, pero las nuevas creaciones o activaciones de pases devuelven un sobre de error estructurado PASS_LIMIT_REACHED hasta que se libere o amplíe la capacidad.
Sobre de Error Estándar 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
}
Consulta del Uso en Tiempo Real y Resúmenes de Facturación de la Organización
1. Resumen de Consumo del Espacio de Trabajo (GET /api/v1/customer/:customerId/usage-summary)
Recupere los medidores en tiempo real para pases activos, total de pases creados, escaneos mensuales, almacenamiento de recursos y volumen de notificaciones 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. Resumen de Facturación de Toda la Organización (GET /api/v1/organizations/current/billing-summary)
Para agencias y empresas que gestionan múltiples espacios de trabajo hermanos (production, staging, client-a) bajo una misma 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 }
]
}
Documentación Relacionada
-
Compare los niveles de capacidad y los complementos en Precios y Planes de Suscripción.
-
Mejore o reduzca su suscripción en Cambios de Plan y Cancelación.
-
Revise la distinción técnica entre pases y registros de dispositivos en Métricas de Emisión y Uso de Pases.
