Ligar serviços: emails, pagamento, IA

A app que fala com o mundo

O sucesso da app do Tom ultrapassa a turma dele: uma colega de português usa-a com os alunos do 8.º ano, e um professor de matemática de outra escola escreveu-lhe para saber «como instalá-la para a escola dele — e quanto custa». Três vontades emergem: enviar aos alunos um resumo semanal por email, adicionar uma mensagem de encorajamento gerada por IA quando um aluno termina o dia, e propor uma versão «turma» paga para os professores das outras escolas. Três funcionalidades, um mesmo mecanismo: pôr a app a dialogar com serviços externos.

Este diálogo passa por API (interfaces de programação). O princípio: um serviço — o Resend para os emails, o Stripe para o pagamento, o Claude para a IA — expõe um balcão na Internet. A tua app apresenta-se lá com um pedido estruturado («envia este email para este endereço») e uma chave API que prova a sua identidade, e o serviço executa e responde. Não precisas de compreender como o Resend encaminha um email, tal como não precisas de compreender uma central elétrica para ligar uma tomada: a API é a tomada.

A regra de ouro: as chaves ficam no servidor

Antes da mínima ligação, uma regra absoluta. A tua chave API é um cartão bancário: quem a possuir consome o serviço em teu nome e à tua custa. Ora, todo o código que corre num navegador é legível por qualquer pessoa — um simples F12 chega. Conclusão implacável: uma chave secreta nunca deve jamais encontrar-se no código do lado do navegador. Vive do lado do servidor, onde ninguém a pode ler.

«Mas eu não tenho servidor!» Tens, quase: a Vercel (e os concorrentes) propõe funções de servidor — pequenos pedaços de código alojados neles, que se executam a pedido. O esquema é sempre o mesmo: o navegador chama a tua função de servidor (sem chave), a função chama o serviço externo (com a chave, guardada numa variável de ambiente), e devolve ao navegador apenas o resultado. A IA sabe criar estas funções na perfeição — o teu trabalho é exigir esta arquitetura nos teus prompts.

flowchart LR
  N["Navegador do aluno"] -->|"Pedido sem nenhuma chave"| F["Função de servidor na Vercel"]
  F -->|"Chamada com a chave secreta"| S["Serviço externo: Resend, Stripe ou Claude"]
  S -->|"Resposta"| F
  F -->|"Resultado limpo"| N

Enviar emails: o resumo semanal

Primeira ligação: o email. Não se enviam emails automáticos a partir da caixa Gmail pessoal — os fornecedores bloqueiam-no depressa e é frágil. Passa-se por um serviço de email transacional como o Resend, o Postmark ou o Brevo: concebidos para apps, fiáveis, e gratuitos em pequena escala (o Resend oferece 100 emails por dia, muito acima das necessidades do Tom). O prompt do Tom, completo:

Adiciona o envio de um email de resumo à minha app de acompanhamento de hábitos.
Contexto: app HTML/JS na Vercel, dados no Supabase, autenticação por link mágico.
O que quero:
1. um botão «receber o meu resumo da semana» na página principal
2. ao clique, uma função de servidor Vercel calcula os streaks e as marcações da semana do utilizador ligado, e envia-lhe um email limpo e legível via Resend
3. a chave API do Resend fica no servidor, numa variável de ambiente da Vercel — nunca no código do navegador
4. limite estrito: um envio por utilizador e por dia no máximo, com uma mensagem clara se o limite for atingido
Guia-me primeiro para criar a conta Resend e configurar a variável de ambiente na Vercel, e depois programa a função.
Uma etapa de cada vez, espero testar antes da seguinte.

Para na linha 4: «um envio por utilizador e por dia». Porquê limitar uma funcionalidade gratuita? Porque todo o botão que aciona um serviço externo pode ser martelado — por um aluno brincalhão ou por um robô — e cada envio consome a tua quota. Pôr um limite logo na conceção é um reflexo de arquiteto: proteges o teu serviço antes que ele precise. Generalizaremos este reflexo no capítulo 9.

Receber um pagamento sem programar: Stripe Payment Links

Para a versão «turma» paga, o Tom receia o pior: o pagamento online é coisa séria, regulamentada, ansiogénica. Boa surpresa: o Stripe, o serviço de pagamento mais usado pelos programadores, propõe os Payment Links — páginas de pagamento alojadas pelo Stripe, criadas em alguns cliques no painel de controlo deles, sem uma linha de código. Crias um produto («Versão turma — 29 €/ano»), o Stripe gera um URL, e a tua app só tem de mostrar um botão a apontar para esse URL. O Stripe gere o cartão bancário, a segurança, a faturação, os reembolsos.

• Cria uma conta em stripe.com e fica em modo de teste por enquanto.
• No painel de controlo: Produtos → adicionar «Versão turma» com o seu preço.
• Gera o Payment Link do produto e copia o URL.
• Pede à IA que adicione uma página «versão turma» com os benefícios e um botão para esse link.
• Testa o percurso completo em modo de teste, e depois ativa o modo real quando tudo estiver validado.

Os Payment Links têm limites — sem desbloqueio automático de funcionalidades na app depois do pagamento, por exemplo. Para a v1 do Tom, é perfeito: o professor paga via o link, o Tom recebe a notificação do Stripe e ativa a turma à mão. Cinco clientes por mês geram-se manualmente; no dia em que forem cinquenta, ligará a automatização (os «webhooks») — um problema de rico, para mais tarde. Automatizar o que só acontece cinco vezes por mês é um mau negócio.

Adicionar um toque de IA na tua app

Última ligação, a mais saborosa: usar a IA dentro da tua app — e já não apenas para a construir. A ideia do Tom: quando um aluno marca o último hábito do dia, aparece uma curta mensagem de encorajamento personalizada, gerada pela API do Claude. A mesma arquitetura do email: função de servidor, chave em variável de ambiente, limite de uso. Com duas precauções novas, próprias da IA:

Adiciona uma função «encorajamento do dia» à minha app de acompanhamento de hábitos.
Quando o utilizador marca o último hábito do dia, chama a API do Claude a partir de uma função de servidor Vercel para gerar uma curta mensagem de encorajamento personalizada:
- tom caloroso mas não piegas, adaptado a alunos do ensino básico
- menciona o streak atual e o hábito mais regular da semana
- 2 frases no máximo, em português
Restrições técnicas:
1. a chave API fica numa variável de ambiente, apenas do lado do servidor
2. limite: uma chamada por utilizador e por dia
3. prevê uma mensagem por omissão simpática se a chamada falhar ou ultrapassar 5 segundos — a app NUNCA deve partir por causa desta função
Mostra-me o texto exato do prompt que a função enviará ao Claude, para que eu o possa ajustar.

Duas linhas merecem a tua atenção. «Prevê uma mensagem por omissão se a chamada falhar»: é a degradação elegante — uma funcionalidade bónus nunca deve poder partir a app que a transporta. E «mostra-me o texto exato do prompt»: pois é, a tua app contém agora ela própria um prompt, que podes refinar como aprendeste a refinar os teus. Escreves prompts que geram código que envia prompts — o ciclo é saboroso, e dominas cada andar.

Quando um serviço externo cai

Última lição deste capítulo: a tua app depende agora de serviços que não controlas. O Resend, o Stripe ou a API do Claude podem ter uma avaria, abrandar, ou mudar as regras. Três hábitos à medida: verificar a página de estado do serviço antes de procurar o bug do teu lado («Resend status» num motor de busca), prever um comportamento de recurso para cada ligação (mensagem por omissão, botão desativado com explicação), e nunca fazer depender a função central da tua app de um serviço externo. Os hábitos do Tom marcam-se mesmo que a IA, o email e o pagamento estejam os três em baixo — é isso, uma arquitetura saudável.

A tua app sabe agora escrever, cobrar e refletir. Mas cada ligação também aumentou a sua superfície de exposição: chaves a proteger, entradas a validar, limites a fazer respeitar. Antes de ir mais longe, é hora de proteger seriamente o conjunto — é o programa do capítulo 9.