Caso de estudo · 2026

Website → Notion CRM Lead Intake

Integração server-side entre o formulário da Pixel Compile e um CRM no Notion: qualificação leve, mapeamento estruturado, proteção anti-spam e telemetria sem dados pessoais.

Formulário de contacto da Pixel Compile após uma submissão local bem-sucedida — fig. 01 - Formulário expandido e confirmação no modo mock local — sem dados enviados ao Notion

Contexto

O formulário de contacto da Pixel Compile já validava dados e aplicava proteção anti-spam, mas em produção não tinha um destino configurado. Ao mesmo tempo, os contactos comerciais eram geridos num CRM próprio no Notion.

Problema

Receber uma mensagem por um serviço genérico e transcrevê-la manualmente para o CRM criaria duas fontes de verdade e trabalho repetido. A integração precisava de captar contexto suficiente sem transformar o primeiro contacto num briefing longo.

Restrições

O token do Notion nunca pode chegar ao browser; toda a entrega acontece numa rota Edge server-side.
Preview e CI não podem criar leads reais; fora de produção, o endpoint responde em modo mock.
O CRM existente usa Empresa como título obrigatório, mas o formulário também tem de aceitar freelancers sem empresa.

Decisões

Integração REST direta com a API do Notion, sem SDK, Zapier, Make ou base intermédia: uma única escrita por submissão é suficiente para este volume.
Qualificação leve com empresa opcional e quatro escolhas de serviço; quando a empresa falta, o nome da pessoa torna-se o título do registo.
Telemetria limitada a request ID, duração e categoria de erro. Nome, email, empresa e mensagem ficam fora de logs, analytics e Sentry.

Abordagem técnica

A rota valida o contrato com Zod, rejeita honeypots, limita pedidos por IP e mapeia a submissão para as propriedades Empresa, Nome, Email, Serviço, Origem, Status, datas e Observações do CRM.

A configuração usa apenas variáveis server-side. Produção falha de forma explícita se faltar configuração; desenvolvimento e preview mantêm um percurso seguro de demonstração sem escrita externa.

Resultado

O percurso fica preparado para transformar cada submissão válida num lead estruturado com Status “Novo” e Origem “Website”, sem cópia manual. A ativação final depende apenas da ligação da integração interna ao CRM e dos segredos de produção.

Diagrama do formulário, API edge e CRM no Notion — fig. 02 - Arquitetura e limites de confiança da integração

Limitações conhecidas

Não existe fila durável: se o Notion estiver indisponível, o utilizador recebe um erro e o email direto como alternativa.
Não existe notificação separada; os novos leads têm de ser consultados no CRM.
Uma resposta perdida depois de uma escrita bem-sucedida pode levar a uma repetição e a um registo duplicado.

Aprendizagens

Uma integração pequena fica mais segura quando o contrato, o mapeamento e os modos por ambiente são explícitos — não quando se acrescentam mais serviços.
O formulário e o CRM devem partilhar a mesma taxonomia comercial; isso elimina limpeza posterior e torna o pipeline mensurável desde a entrada.