A história
Três viragens. Três decisões de engenharia.
O pedido inicial parecia direto: uma loja online sincronizada com o CSV do fornecedor. Na prática, foram três viragens consecutivas — e cada uma tornou-se uma das funcionalidades de que mais nos orgulhamos.
-
O cliente e o desafio
Um revendedor autorizado de iluminação profissional e sistemas de segurança queria uma loja completa, sincronizada automaticamente com o catálogo do fornecedor. O fornecedor disponibilizava um endpoint com um ficheiro CSV de toda a informação dos produtos. Em teoria, era ler o ficheiro, mapear os campos, e ter a loja a funcionar. Na prática, nada disto sobreviveu ao primeiro contacto com a realidade.
-
1ª viragem — o limite da plataforma
Começámos pela escolha que qualquer equipa experiente faria: Shopify, com a Storefront API. Avançámos semanas com bons resultados. Foi ao integrar o CSV a sério que o problema apareceu na sua dimensão real — campos profundamente nichados (
specifications,params,short_description_html,related_products) para produtos técnicos com folhas de especificação. O modelo de dados do Shopify não tem onde os pôr. Tomámos a decisão difícil mas correta: parar, reavaliar e reconstruir. -
A reconstrução — uma stack desenhada para o problema
Reconstruímos de raiz com Next.js, PostgreSQL e Stripe. Cada campo do CSV passou a ter o seu lugar próprio na base de dados, com o tipo certo, os índices certos e renderização limpa: especificações tornaram-se tabelas navegáveis, imagens secundárias ganharam galeria, produtos relacionados passaram a relações reais. Em paralelo, construímos uma dashboard administrativa custom — o cliente gere catálogo, encomendas, descontos e, o mais valorizado, edita o hero, serviços e testemunhos da homepage sem qualquer intervenção técnica nossa.
-
2ª viragem — o que faltava no CSV
Com a stack nova a funcionar, descobrimos que o CSV não continha manuais, fichas técnicas, firmware nem software. Para uma loja de iluminação profissional e segurança, isto não é um pormenor — é a razão pela qual um instalador escolhe um revendedor. Construímos uma camada de integração adicional, fora do escopo inicial, que enriquece cada produto com os recursos descarregáveis do fornecedor, sempre atualizados e sem manutenção manual. Hoje, é uma das funcionalidades mais utilizadas da loja.
-
3ª viragem — reconstruir a árvore de categorias
O CSV oferecia apenas dois níveis de categorização, enquanto o catálogo real tinha uma hierarquia muito mais profunda. Navegar centenas de produtos técnicos com dois níveis é uma experiência indigna de uma operação séria. Construímos um sistema de descoberta que, em batches otimizados, consulta o endpoint de produto, extrai os breadcrumbs completos e reconstrói a árvore real na nossa base de dados — o catálogo inteiro em menos de cinco minutos. Algo impossível para quem depende do mesmo feed CSV.
-
A camada que cose tudo — sincronização inteligente
Tudo assenta num orquestrador que corre de meia em meia hora: descarrega o CSV mais recente, executa a descoberta de categorias e atualiza os recursos — mas só toca no que efetivamente mudou. Um mecanismo de diferenciação granular compara cada produto com o seu estado anterior e atua cirurgicamente. O ganho é triplo: writes mínimos, logs limpos e auditáveis, e zero invalidações de cache desnecessárias. Uma loja que está sempre sincronizada e, ao mesmo tempo, se sente sempre instantânea.
