Contexto
Um checkout headless na VTEX. A vitrine é construída pelo time, o carrinho e o pedido vivem no
orderForm da VTEX e são acessados pela Checkout API, e em volta desse núcleo ficam as
partes que a plataforma é dona: fluxos de conversão, pagamentos, pedidos e autenticação para vários
lojistas e lojas virtuais.
Essa divisão coloca boa parte do resultado no front-end. As regras de negócio do carrinho são da VTEX; como o cliente é guiado por elas, o que a tela diz quando algo falha e quantos passos e quanto ruído existem entre um carrinho cheio e um pedido pago são nossos. Em um checkout, essa diferença é receita.
Problema
- Features precisam entrar sem quebrar quem já consome a API.
- Checkout é o caminho da receita: comportamento correto importa mais que código elegante, e falhas aparecem na hora.
- Os dados cruzam fronteiras: pedidos, pagamentos e autenticação vivem em serviços diferentes, comunicando por REST e gRPC.
- Uma mudança de interface no back-end implica mudança coordenada nas aplicações que a consomem.
- Conversão se decide em coisas pequenas: um passo a mais, um erro que não diz o que fazer, um campo que pede uma informação que o cliente precisa ir buscar.
- Em uma tela de pagamento, acessibilidade não é acabamento: foco de teclado, rótulos e como os erros são anunciados decidem se parte dos clientes consegue comprar.
Minha responsabilidade
Evoluir features e endpoints existentes, criar novos endpoints quando a feature exigia (seguindo os padrões arquiteturais já estabelecidos pelo time), consumir essas APIs no front-end e escrever testes. A maior parte do que eu fiz ficou no lado voltado ao cliente: guiar o cliente pelo fluxo, tirar passos e ruído, e manter as telas de pagamento e autenticação usáveis para todo mundo.
O que eu trabalhei
- Fluxos de checkout e conversão nas aplicações web: guiar o cliente pelos passos, apertar o texto e os estados, e tirar atrito onde o fluxo pedia mais do que precisava.
- Pagamentos e pedidos: features em torno do ciclo de vida do pedido, e como o estado de um pedido é apresentado ao cliente em vez de só estar correto no servidor.
- Autenticação: códigos de uso único por SMS, e-mail e WhatsApp, nas aplicações que consomem a plataforma.
- Acessibilidade e usabilidade nas telas de pagamento: navegação por teclado e ordem de foco, foco visível, rótulos ligados aos campos e erros que dizem o que fazer em vez de só o que deu errado.
- Endpoints: evolução dos existentes e criação de novos quando a feature exigia, consumindo-os em seguida no front-end.
- Observabilidade e testes: Sentry para problemas em produção, testes automatizados como rede de segurança para mudanças em um caminho de receita.
Como eu abordei
Antes de escrever qualquer coisa eu lia os outros endpoints do mesmo serviço e seguia as convenções deles (nomenclatura, formato de erro, validação), porque consistência é o que torna uma API aprendível. Em mudanças de contrato, eu tratava os consumidores existentes como restrição: estender em vez de redefinir, e manter o comportamento anterior válido. Como a mesma mudança costuma atravessar back-end e front-end, eu trabalhava dos dois lados do contrato em vez de entregar um formato que ninguém tinha validado. E para tudo que tocava dinheiro ou estado de pedido, os testes vinham antes de a mudança entrar.
Desafios
- Manter compatibilidade enquanto a API compartilhada por várias aplicações evolui.
- Raciocinar através das fronteiras REST e gRPC dentro de uma mesma feature.
- Debugar em um sistema onde o caminho de falha tem consequência de negócio, usando logs, traces pela stack de observabilidade e rastreamento de erros.
- Corrigir problemas de UI cuja causa raiz estava no contrato da API: o bug visível raramente estava onde a correção pertencia.
- Fazer o checkout funcionar para quem usa teclado e leitor de tela sem piorar o fluxo para todo mundo.
Decisões e trade-offs
- Seguir os padrões existentes em vez de introduzir um novo. Trade-off: às vezes um padrão não é o encaixe perfeito, mas um código consistente para o próximo engenheiro valia mais que uma solução localmente elegante.
- Estender contratos de forma aditiva. Trade-off: a superfície da API cresce e carrega campos legados; a alternativa era coordenar mudanças que quebram clientes.
- Tirar passos antes de adicionar features. Trade-off: o resultado visível é um fluxo mais curto, e não uma capacidade nova, o que é mais difícil de mostrar numa demo e mais fácil de medir em conversão.
- Guiar o cliente em vez de só reportar o erro. Trade-off: mais estados para escrever e manter por tela, em troca de menos becos sem saída, menos contato de suporte e menos carrinhos abandonados.
- Acessibilidade como parte do fluxo, não como etapa posterior. Trade-off: mais marcação e mais estados para manter; em troca, as telas de pagamento funcionam para quem usa teclado e leitor de tela, que também são clientes.
Resultado
Features entregues em um caminho crítico de receita, a maior parte delas na camada de experiência do checkout. A escala em volta: mais de R$3 bilhões transacionados na plataforma.
O que aprendi
- Em uma API compartilhada, compatibilidade é uma feature com custo de design próprio.
- Ler o código existente antes de escrever código novo é a revisão de arquitetura mais barata que existe.
- Entender a consequência de negócio de uma falha muda o quanto de teste é suficiente.
- Em um checkout, a interface faz parte da regra de negócio: um estado confuso é um pedido perdido, não um problema estético.