Skip to content
Guía del Centro de ayuda · Planes y uso
4 min de lecturaVerificado 2026-11-16

Pases activos y límites de uso

Conoce por qué solo cuentan los registros activos en Wallet y cómo opera el umbral flexible ×5.

En esta guía

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

FLUJO DE ARQUITECTURA
ARQUITECTURA INTERACTIVA
MEDICIÓN DE PASES ACTIVOS Y APLICACIÓN DE CUOTAS
ETAPA 01 EVENTOS DEL CICLO DE VIDA DEL PASE Y BILLETERA
Pase Creado (Borrador/
URL Descarga No Reclam)
Evento Guardar en Wallet
(Reg APNs / JWT Google)
Desinstalación /
Anulación Servidor
[ 0 Cuota Activa ] [ +1 activePasses ] [ Libera Cuota Activa ]
ETAPA 02 UMBRALES DE CUOTA Y MOTOR DE CUMPLIMIENTO
Umbral Flexible de Pases Creados: totalPasses <= effectiveActivePassLimit * 5
Emite Advertencia en el Panel (Nunca Interrumpe los Pases Instalados)
Límite Estricto de Pases Activos: activePasses >= effectiveActivePassLimit
Rechaza Nuevas Emisiones/Activaciones con HTTP 403/429 PASS_LIMIT_REACHED

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 activePasses de 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 PreviasNo (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. 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.

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

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
}

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:

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

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

Documentación Relacionada

¿Listo para lanzar su primer programa de tarjetas Wallet?

Cree su espacio de trabajo, configure su plantilla y pruebe una tarjeta real en Apple Wallet y Google Wallet antes de escalar.