Desenvolver um e-commerce de raiz com integração logística: as cinco camadas e por que ordem se constroem

«Quero uma loja online feita de raiz» costuma significar «quero uma loja que faça o que os modelos pré-feitos não fazem». E o que os modelos pré-feitos não fazem é quase sempre o mesmo: falar com quem fabrica, com quem envia e com quem cobra, sem que uma pessoa copie dados de um ecrã para outro. Este artigo explica como estruturamos esse trabalho em cinco camadas, o que leva cada uma e por que ordem se constroem. Os exemplos são de eclipseando.com, uma loja nossa que está em produção, e dos conectores de transportadora que temos publicados para o Odoo.

As cinco camadas de uma loja

Camada 1: os dados vivem num só sítio

Antes de desenhar um ecrã, é preciso decidir onde vive o catálogo. Se o cliente tem Odoo, a resposta é Odoo: artigos, preços, stock e encomendas estão lá e o site lê-os, não os copia. Se não o tem, a loja precisa da sua própria base de dados, e convém que seja pequena e aborrecida. Em eclipseando.com é SQLite, num ficheiro, com cópia de segurança. O que não pode acontecer é o preço estar no site e também numa folha de cálculo e também no ERP: ao fim de dois meses são três preços diferentes.

Camada 2: a caixa não confia no navegador

Duas regras que não negociamos. A primeira: o preço calcula-se no servidor, com o catálogo em vigor, no momento de criar a sessão de pagamento. O navegador pode guardar o carrinho, mas não pode dizer quanto vale. A segunda: uma encomenda está cobrada quando a gateway a confirma com um webhook assinado, não quando o cliente aterra na página de agradecimento. Com a Stripe isso é checkout.session.completed com a assinatura verificada; noutras gateways tem outro nome e a mesma ideia. E se, ao receber o webhook, falhar o passo seguinte, responde-se com erro para que a gateway tente de novo, e guarda-se o identificador da sessão para não produzir duas vezes.

Camada 3: cada fornecedor fala como pode

É aqui que «integração logística» deixa de ser uma expressão e se torna trabalho. Um fornecedor com API e webhook (uma tipografia sob encomenda, uma grande transportadora) integra-se nos dois sentidos: cria-se-lhe a encomenda ao cobrar e escuta-se o seu aviso de «enviado» para passar o rastreamento ao cliente. Um com API de dropshipping integra-se num sentido e consulta-se no outro: antes de cobrar, a disponibilidade real por país; depois, a encomenda. E um sem API, que os há e muitos, integra-se reduzindo o trabalho humano a um clique: o sistema produz exatamente o e-mail ou o CSV de que o fornecedor precisa, e se os seus pacotes saem com uma transportadora que envia e-mails, esses e-mails são lidos e convertidos em estados.

Dois detalhes que só se aprendem com encomendas reais. Um: o rastreamento vai por envio, não por encomenda, porque uma encomenda com dois artigos de dois fornecedores são dois pacotes. Dois: os prazos que a documentação do fornecedor indica não são os que cumpre; medem-se criando encomendas de teste e lendo o que devolve, e esses são os que se mostram ao cliente antes de pagar. Quando o fornecedor é uma transportadora e a loja usa Odoo, tudo isto já está resolvido nos conectores de transportadora que publicamos: etiqueta, rastreamento, manifesto e devolução dentro da guia de remessa.

Camada 4: o que corre sozinho e o que se volta a tentar

Uma loja tem trabalho que não pode depender de alguém se lembrar dele: esvaziar a fila de e-mails, voltar a tentar as encomendas cobradas que não chegaram ao fornecedor, ler a caixa de correio da transportadora, sincronizar o stock com os marketplaces. Cada um é uma tarefa agendada com um intervalo e um registo. A regra de conceção é que nenhuma chame um serviço externo no caminho de um pedido do utilizador: a página lê o que a tarefa deixou em cache. Assim, se o fornecedor cair às três da manhã, a loja continua a servir páginas e as encomendas são repetidas quando ele voltar.

Camada 5: o frontal, no fim e rápido

Com as quatro camadas de baixo resolvidas, o frontal é a parte mais recompensadora. Preferimos sites estáticos gerados em build (Astro em eclipseando.com) servidos por nginx ou Caddy: carregam num instante, não têm base de dados para atacar e custam o que custa um servidor pequeno. O dinâmico (carrinho, pagamento, estado da encomenda) vai por uma API à parte. O multilingue faz-se com um URL por idioma e textos próprios, não com um tradutor automático por cima, e testa-se com testes que verificam que cada modelo existe em todos os idiomas. E a velocidade mede-se antes de publicar: peso da página, imagens no tamanho em que são apresentadas, nada que bloqueie o primeiro render.

A ordem importa: de dentro para fora

O erro mais caro que vemos é começar pela camada 5. Mostra-se um site bonito na segunda semana, o cliente entusiasma-se, e as camadas 1 a 4 improvisam-se por baixo à pressa. O resultado funciona até à primeira encomenda com dois fornecedores, ou até ao primeiro webhook perdido. Nós construímos ao contrário: primeiro os dados e a caixa com os seus testes, depois as integrações com encomendas de teste reais, depois as tarefas agendadas, e o frontal no fim, quando já se sabe exatamente o que tem de mostrar. Demora o mesmo. Refaz-se muito menos.

Perguntas frequentes

Ligações úteis dentro da FlexigoTech

O que fazemos sobre isto