Límites de Puerta de Enlace de API, Carga Útil y Concurrencia
Para mantener una baja latencia en la generación de pases y proteger la estabilidad multiinquilino, Passinstance API aplica límites de tasa deterministas, topes de tamaño de carga útil y bloqueos de idempotencia en el límite de entrada.
Encabezados de Límite de Tasa y Manejo de HTTP 429
Cada respuesta de la API incluye encabezados de limitación de tasa RFC estándar y heredados para que los clientes de integración puedan regular automáticamente el ritmo de las operaciones masivas:
| Encabezado de Respuesta | Descripción |
|---|---|
RateLimit-Limit / X-RateLimit-Limit | Solicitudes máximas permitidas dentro de la ventana de ráfaga actual de 1 segundo. |
RateLimit-Remaining / X-RateLimit-Remaining | Solicitudes restantes permitidas en la ventana activa antes de la limitación. |
RateLimit-Reset / X-RateLimit-Reset | Segundos restantes hasta que se restablezca el cubo del límite de tasa. |
Retry-After | Segundos que se debe esperar antes de volver a intentarlo tras recibir una respuesta HTTP 429. |
Carga Útil de Respuesta Limitada HTTP 429:
{
"error": "Rate limit exceeded",
"retryAfter": 1
}
Restricciones de Carga Útil de Solicitud e Idempotencia
-
Cuerpo Máximo de Solicitud (
10MB): La puerta de enlace de la API aplica un límite estricto de carga útil de10MB(BODY_LIMIT) en todas las solicitudes JSON y cargas de archivos. Para la emisión de pases de gran volumen que supere unos pocos cientos de registros, utilice el trabajador asíncrono por lotes CSV (POST /api/v1/batch-processing) u operaciones de matrices fragmentadas (POST /api/v1/batch-pass-operations/create) en lugar de solicitudes individuales sobredimensionadas. -
Bloqueo de Idempotencia: Las llamadas simultáneas de escáner o de canje en punto de venta que comparten la misma
x-idempotency-key(oidempotencyKeyenPOST /v1/pos/redeem) se serializan mediante bloqueos de in-memory cache e índices únicos de base de datos (ux_scan_config_idempotency,ux_pos_tx_tenant_idempotency) para evitar deducciones dobles en redes inestables de recintos, buscando coincidencias de pases por código de barras,serialNumberoexternalId.
Restricciones de Billetera a Nivel de Plataforma (Apple y Google)
Varios límites de comportamiento se originan directamente en las arquitecturas de los sistemas operativos Apple iOS y Google Android:
| Restricción | Plataforma | Realidad Técnica y Solución Recomendada |
|---|---|---|
Límite de Push Silencioso de APNs (4096 bytes) | Apple Wallet (APNs) | El servicio de notificaciones push de Apple restringe las cargas útiles a 4096 bytes. Passinstance envía un push vacío ligero {} para despertar el iPhone, que luego descarga el paquete .pkpass completo (firmado con el bundleId / passTypeIdentifier de la plantilla) mediante GET /v1/passes/:passTypeIdentifier/:serialNumber. |
| Caché de Imágenes de Clase Compartida | Google Wallet frente a Apple Wallet | Apple vuelve a descargar el archivo ZIP .pkpass completo al actualizar, refrescando de inmediato las imágenes de franja o miniatura. Google Wallet almacena en caché de forma intensiva las URL de imagen principal y logotipo compartidas a nivel de Class en dispositivos Android; añada un nombre de archivo que invalide la caché o actualice los campos a nivel de Object para obtener cambios visuales instantáneos. |
| Supresión de Push con Valor Idéntico | Apple Wallet | iOS muestra un aviso de notificación en la pantalla de bloqueo únicamente cuando un campo con un changeMessage cambia a un nuevo valor de cadena. Volver a guardar exactamente el mismo valor no genera ningún aviso. |
| Registro de Apple Watch Enlazado | Apple Wallet + watchOS | Un único pase instalado en un iPhone sincronizado con un Apple Watch enlazado registra 2 tokens push de dispositivo distintos (installedDevices = 2) en 1 instancia de pase. |
| Bloqueo de WebView en Redes Sociales | Instagram, TikTok y LinkedIn en iOS | Los visores web integrados de aplicaciones sociales suelen bloquear las transmisiones MIME application/vnd.apple.pkpass. Las páginas de descarga inteligente (/d/:slug) detectan los visores web y guían a los titulares para que abran el enlace en Safari nativo. |
NFC Cifrado (NFC_VAS / NFC_SMART_TAP) | Hardware NFC de iOS y Android | El canje sin contacto cifrado requiere hardware lector certificado (por ejemplo, certified NFC) además de autorizaciones explícitas de comerciante para Apple VAS o Google Smart Tap; nunca está habilitado de forma predeterminada. |
Importante: Al ejecutar actualizaciones masivas de pases en decenas de miles de tarjetas activas, los trabajadores en segundo plano background job queue de Passinstance regulan automáticamente el ritmo de las transmisiones salientes HTTP/2 de Apple APNs y las llamadas REST PATCH de Google Wallet para respetar las cuotas de los proveedores en la nube.
Para obtener orientación sobre integración para desarrolladores, consulte Descripción General de la API y Autenticación y Diferencias y Limitaciones de Plataforma.
