Conecta tu sistema con AVEX

• Upsert por identificador externo: tu sistema es el dueño del registro — el primer envío crea el pase y los siguientes reflejan los cambios, sin distinguir alta de actualización.
• Autenticación con API key por cliente y alcances por operación — una llave solo puede hacer aquello para lo que fue emitida.
• Cabecera de idempotencia para reintentos seguros y modo de simulación que valida el envío completo sin escribir nada.

Verificable: app/api/v1/**/upsert/route.ts

• Endpoint dedicado por cliente y por vertical: confirmación de pago, cuotas de proyecto, facturas de servicios y el espejo del saldo de lealtad (mismo mecanismo firmado; no es un cobro).
• Cada notificación viene firmada (HMAC) con un secreto propio de tu empresa; la verificación corre sobre el cuerpo crudo antes de procesar nada.
• Los reenvíos del mismo evento no duplican efectos — tu sistema puede reintentar sin miedo.
• AVEX nunca cobra ni es dueño de la cartera: el pago ocurre en tu sistema y el pase solo refleja su estado.

Verificable: app/api/webhooks/*/*/route.ts · app/api/payments/utility-webhook/[clientSlug]/route.ts · app/api/payments/loyalty-snapshot/[clientSlug]/route.ts

• Acepta archivos .xlsx y .xls, con validación de formato, tamaño y contenido antes de procesar.
• El mismo flujo sirve para la carga inicial y para actualizaciones masivas posteriores.
• Modo de simulación: reporta qué crearía o actualizaría sin tocar los datos, para revisar antes de confirmar.
• Pensada para arrancar hoy — la integración por API puede llegar después, cuando el volumen lo pida.

Verificable: app/api/institution/[institutionId]/ingest/route.ts

• Emitimos el archivo .pkpass con los campos y el diseño configurados por vertical.
• Firmamos cada pase con el certificado del emisor — el de AVEX por defecto, o el del cliente cuando trae el propio; la cadena Apple WWDR la verifica cada dispositivo receptor.
• Actualizaciones push vía APN para cambios de saldo, cuota, período o membresía.

Verificable: package.json → passkit-generator

• Firmamos JWTs con la cuenta de servicio para generar el enlace que agrega el pase al wallet del destinatario.
• Usamos las clases oficiales por vertical — nativas EventTicketObject/LoyaltyObject y GenericObject para los flujos heredados.
• Las actualizaciones de estado llegan al pase sin que el usuario final vuelva a iniciar sesión.

Verificable: backend/services/wallet/google/google-wallet-manager.ts

• El destinatario recibe un enlace de instalación firmado y con vencimiento — lo abre y agrega el pase a su wallet, sin crear cuenta ni instalar otra app.
• Los correos de instalación se componen desde plantillas HTML versionadas en el mismo repositorio que el código que las dispara.
• Los rebotes y quejas alimentan una lista de supresión automática para no reenviar a direcciones inválidas.
• Correo solo para distribuir el pase y administrar la cuenta: los recordatorios y el estado de pago viajan como notificación en el propio pase, no por email.

Verificable: package.json → resend

• Registras tus endpoints HTTPS y eliges a qué eventos suscribirte del catálogo cerrado: pass.created, pass.updated, pass.revoked, pass.installed, payment.received, subscription.tier_changed, ticket.validated.
• Cada entrega va firmada con un secreto por webhook, para que tu sistema verifique el origen antes de confiar en el contenido.
• Reintentos automáticos con espera creciente ante fallas; las entregas agotadas quedan registradas para inspección — nada se pierde en silencio.

Verificable: backend/services/tenant-webhook-service.ts