Por qué el checkout se congelaba en iOS: diagnóstico de integración con EVO para ÁGORA Jiu-Jitsu
Diagnóstico técnico y arquitectura de integración entre app, sitio web y EVO para una academia de jiu-jitsu en Estados Unidos — desde la causa raíz de un error de checkout en iOS hasta el blueprint de un middleware seguro para conectar múltiples front-ends con la API de EVO.
ÁGORA Jiu-Jitsu Academy, una academia en Estados Unidos que usa EVO (un software de gestión muy común en academias) para matrículas y cobros, nos contactó con un problema concreto: el checkout de matrícula en línea fallaba de distintas maneras según el plan, y la clienta quería saber si la solución era ajustar lo que ya existía o construir algo nuevo — app, sitio web y una capa propia de integración con EVO.
El síntoma
En el Plan Kids, el botón de pago simplemente no aparecía en el checkout desde iPhone/Safari — sin ningún mensaje de error. En el plan de adultos, en el mismo dispositivo, todo funcionaba con normalidad. La hipótesis obvia sería "un bug de pago en iOS", pero eso no explicaba por qué fallaba solo un plan específico.
La investigación
Descartamos hipótesis una por una, con pruebas reales, no suposiciones. Se descartaron la pasarela de pago y Safari: el plan de adultos, recurrente, funcionaba en el mismo dispositivo. También se descartó la configuración del plan — al comparar ambos planes directamente vía la API de EVO, los campos de rango de edad, forma de pago y reglas de registro eran idénticos.
La causa real apareció al reproducir el problema directamente: el botón de pago existía y era clicable, pero la página del Plan Kids no se desplazaba hasta el final en iOS — el botón quedaba por debajo del área visible, inaccesible mediante el scroll normal, y solo aparecía si se reducía el zoom manualmente. Un error clásico de viewport de Safari en iOS (el comportamiento del 100vh, donde la barra de direcciones reduce la altura útil de la pantalla). La página de Kids tenía un párrafo más de texto que la de adultos, y ese contenido extra empujaba el botón fuera del área con scroll.
Un hallazgo más crítico que el bug
Durante las pruebas identificamos algo más grave que la desaparición del botón: al completar los datos hasta la etapa de pago — sin finalizar la compra — el sistema disparaba automáticamente tres correos (contrato, cuestionario e invitación de inicio de sesión) antes de cualquier confirmación de pago. Verificamos vía API si este comportamiento del CRM de EVO podía configurarse o desactivarse mediante programación — no se puede. Es una función interna del panel, opaca para cualquier integración externa. Esto cambia el problema de un "ajuste de configuración" a una "restricción estructural de la plataforma".
La arquitectura recomendada
Para un negocio que depende de transmitir hospitalidad y confianza en la experiencia digital, enviar el contrato antes de la decisión de pagar rompe esa experiencia. La recomendación técnica fue un middleware propio (BFF) como único cliente autenticado de la API de EVO — ni la app, ni el sitio, ni el checkout se comunican directamente con EVO. Este middleware mantiene su propia máquina de estados (borrador → esperando pago → pagado → matriculado) y solo activa la conversión de prospecto a miembro en EVO después de confirmado el pago — controlando con precisión el momento en que se disparan las automatizaciones de comunicación de EVO. Esta misma capa también resuelve el problema del checkout familiar, tratando a la "familia" como un concepto de primera clase en lugar de matrículas aisladas por dependiente.
¿FITI o middleware personalizado?
Antes de recomendar construir algo nuevo, evaluamos si la app white-label del propio EVO (FITI) resolvería los problemas. La respuesta fue no: los bugs de interfaz (botón desaparecido, validación de dirección) podrían no repetirse en una interfaz distinta, pero las limitaciones estructurales — el flujo familiar y el disparo prematuro de comunicaciones — provienen del backend/CRM de EVO, no de la pantalla. Cualquier interfaz construida sobre la misma API hereda las mismas restricciones. La recomendación final fue clara: usar FITI como contención de muy corto plazo, y tratar el middleware personalizado como el camino real para resolver los hallazgos estructurales.
Esta etapa se contrató y entregó como diagnóstico técnico y arquitectura — un documento, sin ninguna alteración en el entorno de producción de la clienta. La implementación del middleware y de la app es una fase futura, aún no contratada.