Problemas comuns e resolução de problemas
Sintomas, causas e correcções para problemas que conseguimos verificar no produto.
Se o seu problema não estiver aqui, envie um e-mail para support@rowie.io com capturas de ecrã e o ID da transacção (ou ID da sessão, ou número de factura) sempre que possível.
"Setup required" em Banking ou Tap to Pay
O ecrã Account do POS móvel apresenta um distintivo Setup required na linha Banking, e o Tap to Pay / Terminal Readers ficam desactivados, até que a Stripe Connect tenha concluído o onboarding e as cobranças estejam activadas.
- Portal de vendedor → Banking (barra lateral → grupo FINANCE) → verifique o estado.
- Se o onboarding não estiver concluído, percorra o formulário alojado do Stripe — ele indicar-lhe-á exactamente o que falta (identificação, dados bancários, informações da empresa).
- A primeira configuração pode demorar 1–2 dias para o Stripe verificar.
A verificação de "ready to charge" no código da aplicação é connectStatus.hasConnectedAccount && connectStatus.chargesEnabled — ambos têm de ser verdadeiros.
"Cannot delete location — it still has ..."
O portal bloqueia a desactivação de uma localização se existirem registos dependentes. A mensagem exacta indica o que está a bloquear. As verificações (rowie-api/src/routes/locations.ts):
- Open or in-progress table sessions — liquide-as ou cancele-as primeiro.
- Menus, floor plans, active bookings, booking pages — reatribua a outra localização ou elimine-os primeiro.
- Only location in the org — não pode eliminar a última.
Mova as dependências e tente novamente.
"Cannot delete menu with open sessions or tabs"
Um menu (catalog) não é eliminado enquanto existirem sessões ou tabs abertos contra ele. Liquide-os ou cancele-os na página Tables e tente eliminar novamente. O mesmo padrão aplica-se a:
- Floor plans / tables com sessões activas.
- Events / ticket tiers com bilhetes vendidos.
- Vendor subscription plans com subscritores activos (cancele ou migre-os primeiro).
- Tip pools que não estejam em draft (só pode eliminar pools enquanto estiverem em draft).
"Authentication failed" ou ecrã preso após inactividade prolongada
Os tokens de autenticação expiram após 15 minutos; tanto a aplicação móvel como o portal de vendedor renovam automaticamente num 401. Se a renovação falhar (por exemplo, o refresh token também expirou após 7 dias, ou iniciou sessão noutro dispositivo e foi expulso), verá uma notificação "Authentication failed" e será redireccionado para o login.
- Apenas no móvel: quando inicia sessão num segundo dispositivo, o primeiro recebe SESSION_KICKED e é forçado a terminar sessão — é intencional (protecção contra roubo de telemóvel).
- O portal de vendedor não impõe sessão única — pode manter vários separadores abertos.
Se estiver preso a meio de um ecrã: termine sessão e volte a iniciar.
Falha ao fechar um tab / "Payment failed"
Quando um cartão guardado é cobrado off-session para fechar um tab e o Stripe o recusa, a sessão volta a open para poder tentar novamente. Causas comuns:
- O cartão exige nova autenticação / 3DS para cada cobrança.
- Regra anti-fraude do emissor sobre cobranças off-session.
- Fundos insuficientes.
Limitação conhecida: as chaves de idempotência do Stripe para close-tab são estáveis durante 24 horas. Se a primeira tentativa de close-tab foi recusada, repetir com o mesmo cartão imediatamente devolve a mesma tentativa recusada. Solução: efectue um novo pagamento Tap to Pay em vez de fechar pelo cartão guardado, ou peça ao cliente para guardar um novo cartão.
"Payment setup required" no checkout
O POS móvel mostra isto quando tenta cobrar mas a Stripe Connect não está totalmente configurada. A correcção é a mesma do distintivo "Setup required" acima — termine o onboarding em Banking.
Recibos: enviar e reenviar
Os recibos do Tap to Pay têm de ser enviados explicitamente — não são entregues automaticamente pelo Stripe nas transacções card_present.
- No ecrã Payment Result, logo após uma cobrança, introduza o e-mail do cliente e toque em Send receipt.
- Mais tarde, abra qualquer transacção em History → Send receipt.
Se os recibos não chegarem, verifique primeiro o spam e depois confirme que o e-mail está correcto na transacção.
Os dados em tempo real parecem desactualizados
A aplicação usa Socket.IO para enviar actualizações (encomendas, sessões, tabs, menus, reservas, facturas, pay runs). O TanStack Query está configurado com stale time infinito e sem polling — as invalidações vêm de eventos de socket.
Se algo parecer desactualizado:
- Faça pull-to-refresh no ecrã (móvel) ou recarregue a página (portal de vendedor).
- Termine sessão e volte a iniciar para forçar uma nova ligação de socket.
- Verifique se o URL da API está acessível a partir do seu dispositivo.
O socket do vendedor reconecta automaticamente com tokens novos (callback de autenticação dinâmico). O cliente móvel tenta até 10 reconexões com backoff entre 1–5 s.
Rate-limit (HTTP 429) nas páginas públicas de menu / table / booking
A API limita por IP + session ID a criação de preorders, sessões e reservas públicas para mitigar fraude (acrescentado após o incidente de Abril de 2026). O tráfego normal de clientes não atinge este limite. Se um load-test ou um ciclo acidental de retries o accionar, aguarde a janela esvaziar (um minuto) e tente novamente.
O botão Tap to Pay está cinzento
- Apple Tap to Pay entitlement: na primeira vez numa nova conta Stripe Connect, a Apple demora 1–2 dias a activar o dispositivo.
- Banking não activo: ver "Setup required" acima.
- Dispositivo errado: o Tap to Pay precisa de iPhone XS ou mais recente em iOS 16.4+ com código de acesso, ou Android com NFC (SDK 26+).
Conta marcada para revisão
Depois de as heurísticas de fraude serem accionadas (taxa de cobranças bloqueadas ou falhadas acima dos limites), o review_status da conta passa a needs_review e os auto-payouts são suspensos. Contacte o suporte — assim que a equipa Rowie aprovar a conta na fila administrativa, os payouts retomam. A utilização só-leitura do produto continua a funcionar.