Por que o checkout trava no iOS: diagnóstico de integração EVO para a ÁGORA Jiu-Jitsu

A ÁGORA Jiu-Jitsu Academy, uma academia nos Estados Unidos que usa o EVO (software de gestão bastante comum em academias) para matrículas e cobrança, nos procurou com um problema concreto: o checkout de matrícula online estava falhando de formas diferentes dependendo do plano, e a cliente queria entender se a solução era ajustar o que já existia ou construir algo novo — app, site e uma camada própria de integração com o EVO.

O sintoma

No Plano Kids, o botão de pagamento simplesmente não aparecia no checkout via iPhone/Safari — sem nenhuma mensagem de erro. No plano adulto, no mesmo aparelho, tudo funcionava normalmente. A hipótese óbvia seria "bug de pagamento no iOS", mas isso não explicava por que só um plano específico falhava.

A investigação

Eliminamos hipóteses uma a uma, com teste real, não achismo. O gateway de pagamento e o Safari foram descartados: o plano adulto, recorrente, funcionava no mesmo aparelho. A configuração do plano também foi descartada — comparando os dois planos diretamente via API do EVO, os campos de faixa etária, forma de pagamento e regras de cadastro eram idênticos.

A causa real apareceu na reprodução direta: o botão de pagamento existia e era clicável, mas a página do Plano Kids não rolava até o fim no iOS — o botão ficava abaixo da área visível, inacessível pela rolagem normal, só aparecendo ao reduzir o zoom manualmente. Um bug clássico de viewport do Safari no iOS (o comportamento do 100vh, em que a barra de endereço reduz a altura útil da tela). A página do Kids tinha um parágrafo a mais de texto que a do adulto, e esse conteúdo extra empurrava o botão para fora da área rolável.

Um achado mais crítico que o bug

Durante os testes, identificamos algo mais sério que o botão sumindo: ao preencher os dados até a etapa de pagamento — sem concluir a compra — o sistema disparava automaticamente três e-mails (contrato, questionário e convite de login) antes de qualquer confirmação de pagamento. Verificamos via API se esse comportamento do CRM do EVO podia ser configurado ou desligado programaticamente — não pode. É um recurso interno do painel, opaco para qualquer integração externa. Isso muda o problema de "ajuste de configuração" para "restrição estrutural da plataforma".

A arquitetura recomendada

Para um negócio que depende de transmitir hospitalidade e confiança na experiência digital, enviar contrato antes da decisão de pagar quebra essa experiência. A recomendação técnica foi um middleware próprio (BFF) como único cliente autenticado da API do EVO — nenhum app, site ou checkout fala diretamente com o EVO. Esse middleware mantém sua própria máquina de estados (rascunho → aguardando pagamento → pago → matriculado) e só aciona a conversão de prospect em membro no EVO depois da confirmação de pagamento — controlando exatamente o momento em que os automatismos de comunicação do EVO passam a disparar. A mesma camada também resolve o problema do checkout familiar, tratando "família" como conceito de primeira classe no lugar de matrículas isoladas por dependente.

FITI ou middleware customizado?

Antes de recomendar construir algo novo, avaliamos se o app white-label do próprio EVO (FITI) resolveria os problemas. A resposta foi não: os bugs de UI (botão sumindo, validação de endereço) até poderiam não se repetir numa interface diferente, mas as limitações estruturais — fluxo familiar e disparo prematuro de comunicação — vêm do backend/CRM do EVO, não da tela. Qualquer interface sobre a mesma API herda as mesmas restrições. A recomendação final foi clara: usar o FITI como contenção de curtíssimo prazo, e tratar o middleware customizado como o caminho real para resolver os achados estruturais.

Esta etapa foi contratada e entregue como diagnóstico técnico e arquitetura — um documento, sem alteração no ambiente de produção da cliente. A implementação do middleware e do app é uma fase futura, ainda não contratada.