O cliente e o desafio
O cliente é um revendedor autorizado de iluminação profissional e sistemas de segurança. O pedido inicial parecia direto: queriam uma loja online completa, sincronizada automaticamente com o catálogo do fornecedor. O fornecedor disponibilizava um endpoint de onde se podia descarregar um ficheiro CSV com toda a informação dos produtos. Em teoria, era uma questão de ler o ficheiro, mapear os campos, e ter a loja a funcionar.
Na prática, foram três viragens consecutivas — e cada uma delas exigiu uma resposta de engenharia que hoje é parte daquilo que torna esta loja um sistema sólido.
Primeira viragem: o limite da plataforma
Começámos pela escolha que qualquer equipa experiente faria perante um pedido destes: Shopify, com desenvolvimento sobre a Storefront API. Avançámos várias semanas com bons resultados visuais e uma arquitetura limpa. Foi quando começámos a integrar a sério o CSV do fornecedor que o problema apareceu na sua dimensão real.
O ficheiro tinha estrutura rica e profundamente nichada — `specifications`, `params`, `short_description_html`, `category_parent`, `related_products`, `extra_images_paths`, entre dezenas de outros campos. Estávamos a falar de produtos técnicos com folhas de especificação que precisam de ser apresentadas com hierarquia, com tabelas, com agrupamentos. O modelo de dados do Shopify, desenhado para retalho generalista, não tem onde colocar este tipo de informação estruturada de forma nativa. A nossa única alternativa dentro da plataforma era despejar tudo no campo de descrição e fazer parsing no cliente para reconstruir a estrutura — uma solução que funcionava, mas que era frágil, lenta de manter, e que iria envergonhar-nos a longo prazo.
Tomámos a decisão difícil mas correta: parar, reavaliar, e reconstruir. Esta é, em si mesma, uma das decisões mais valiosas que se pode tomar num projeto de software — e uma das mais raras, porque exige reconhecer publicamente que o caminho até ali precisa de ser refeito.
A reconstrução: uma stack desenhada para o problema
Reconstruímos a loja de raiz com Next.js no frontend, PostgreSQL como base de dados, e Stripe para processamento de pagamentos. A diferença foi imediata e estrutural: cada campo do CSV passou a ter o seu lugar próprio na base de dados, com o tipo de dados certo, com os índices certos, e com a renderização limpa que o cliente final merece. As especificações técnicas tornaram-se tabelas navegáveis em vez de blocos de texto, as imagens secundárias ganharam galeria própria, os produtos relacionados passaram a ter relações reais em vez de strings concatenadas.
Construímos em paralelo uma dashboard administrativa custom que vai muito além de um painel de gestão de produtos. Permite ao cliente gerir o catálogo, encomendas, utilizadores, descontos e códigos promocionais a partir de uma única interface — e, talvez o mais valorizado pelo cliente, alterar diretamente o material publicitário do hero da homepage e os blocos de serviços de instalação, testemunhos e conteúdo institucional sem precisar de qualquer intervenção técnica nossa. Cada campanha nova, cada promoção sazonal, cada testemunho recolhido — o cliente publica autonomamente.
Segunda viragem: o que faltava no CSV — e que ninguém pode vender sem
Com a stack nova a funcionar, descobrimos um problema que mudava completamente a proposta de valor da loja: o CSV do fornecedor não continha os manuais, fichas técnicas, firmware, software, nem qualquer recurso descarregável. Para uma loja de iluminação profissional e sistemas de segurança, isto não é um pormenor — é a razão pela qual um instalador escolhe um revendedor em vez de outro. Sem documentação técnica acessível, a loja seria competitivamente invisível.
A solução exigiu construir uma camada de integração adicional, completamente fora do escopo inicial, que enriquece cada produto com os recursos descarregáveis disponibilizados pelo fornecedor. Foi um trabalho de engenharia que envolveu desenhar um pipeline de descoberta robusto, gerir a sincronização sem sobrecarregar a infraestrutura do fornecedor, e garantir que cada produto da loja apresenta a documentação certa, sempre atualizada, sem qualquer manutenção manual por parte do cliente. Hoje, é uma das funcionalidades mais utilizadas pelos visitantes da loja.
Terceira viragem: reconstruir a árvore de categorias do zero
Mais um problema apareceu já em fase avançada: o CSV oferecia apenas dois níveis de categorização (`category` e `category_parent`), enquanto o catálogo real do fornecedor tinha uma hierarquia significativamente mais profunda. Para uma loja com centenas de produtos técnicos, navegar com dois níveis é uma experiência indigna de uma operação séria — os clientes simplesmente não encontrariam o que procuravam.
A solução foi construir um sistema de descoberta de hierarquia que, em batches altamente otimizados, consulta o endpoint de produto do fornecedor, extrai os breadcrumbs completos, e reconstrói a árvore real de categorias na nossa base de dados. O processo completo, para todo o catálogo, corre em menos de cinco minutos. O resultado é uma navegação por categorias que reflete fielmente a estrutura do fornecedor — algo que, para qualquer outro revendedor que dependa do mesmo feed CSV, é simplesmente impossível de obter.
A camada que cose tudo: sincronização inteligente
Toda esta arquitetura assenta num orquestrador de sincronização que corre de meia em meia hora. Faz o download do CSV mais recente, executa a descoberta de categorias, atualiza os recursos descarregáveis — mas, e aqui está o detalhe que torna o sistema viável a longo prazo, só toca naquilo que efetivamente mudou. Implementámos um mecanismo de diferenciação granular que compara cada produto contra o seu estado anterior e atua cirurgicamente. O ganho é triplo: writes mínimos na base de dados, logs limpos e auditáveis, e zero invalidações de cache desnecessárias no frontend. O resultado é uma loja que está sempre sincronizada e que, ao mesmo tempo, se sente sempre instantânea.
O que isto representa
Este projeto é, para nós, um caso emblemático daquilo em que somos bons: integrar sistemas que não foram desenhados para falar uns com os outros, contornar limitações de plataformas e fornecedores, e construir camadas de automação que substituem trabalho manual por engenharia silenciosa. Cada uma das três viragens deste projeto poderia ter ditado o seu fracasso. Em vez disso, cada uma tornou-se uma das funcionalidades de que mais nos orgulhamos.
O resultado
A loja está em produção, sincronizada de meia em meia hora com o catálogo do fornecedor, com documentação técnica completa em cada produto, com uma árvore de categorias profunda fielmente reconstruída, e com uma dashboard administrativa que dá ao cliente controlo editorial e operacional total. O que começou como um projeto de loja online convencional tornou-se, na prática, uma demonstração daquilo que melhor sabemos fazer: transformar fricção em sistema.
