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

Límites y comportamientos conocidos

Restricciones transparentes de Apple, Google, Samsung Wallet, correos y caché del escáner offline.

En esta guía

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.

FLUJO DE ARQUITECTURA
ARQUITECTURA INTERACTIVA
LIMITACIÓN DE TASA DE ENTRADA Y BLOQUEOS DE IDEMPOTENCIA
ETAPA 01 SOLICITUD DE CLIENTE / TPV / INTEGRACIÓN
Tamaño Máximo de Cuerpo JSON/Multipart: 10MB (BODY_LIMIT)
ETAPA 02 LIMITADOR DE TASA GLOBAL POR RÁFAGA DE 1 SEGUNDO (main.ts)
Emite RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset
Si se superaDevuelve HTTP 429 Too Many Requests (Retry-After: 1)
ETAPA 03 GUARDIA DE IDEMPOTENCIA (Idempotency Engine)
Bloquea solicitudes simultáneas duplicadas con x-idempotency-key
Aplica restricciones BD: ux_scan_config_idempotency y ux_pos_tx_tenant_idempotency

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 RespuestaDescripción
RateLimit-Limit / X-RateLimit-LimitSolicitudes máximas permitidas dentro de la ventana de ráfaga actual de 1 segundo.
RateLimit-Remaining / X-RateLimit-RemainingSolicitudes restantes permitidas en la ventana activa antes de la limitación.
RateLimit-Reset / X-RateLimit-ResetSegundos restantes hasta que se restablezca el cubo del límite de tasa.
Retry-AfterSegundos que se debe esperar antes de volver a intentarlo tras recibir una respuesta HTTP 429.

Carga Útil de Respuesta Limitada HTTP 429:

JSON
{
  "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 de 10MB (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 (o idempotencyKey en POST /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, serialNumber o externalId.

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ónPlataformaRealidad 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 CompartidaGoogle Wallet frente a Apple WalletApple 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énticoApple WalletiOS 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 EnlazadoApple Wallet + watchOSUn ú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 SocialesInstagram, TikTok y LinkedIn en iOSLos 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 AndroidEl 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.

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