E-commerce
técnico: entre
o clique e a devolução

1.1 A ilusão da facilidade

Pôr um catálogo online nunca foi tão barato. É por isso que quase toda a gente subestima o resto — e o resto é onde os sistemas se partem:

Repare que a coluna da direita é quase toda sobre tempo e concorrência. Uma loja é um sistema onde muita gente age ao mesmo tempo sobre recursos finitos, e onde o processo de cada compra continua vivo durante semanas depois de o cliente ter fechado o separador.

1.2 As constantes, e porque a apostila se organiza à volta delas

A prospectiva sobre o Futuro do Comércio Digital fecha com uma lista do que não muda. Quatro dessas constantes decidem a arquitectura de qualquer loja:

1.3 O que esta apostila é

É o «como fazer» que faltava ao lado da prospectiva. Não é um manual de nenhuma plataforma: quase tudo o que aqui está aplica-se tanto a quem constrói de raiz como a quem configura uma solução pronta — porque as decisões difíceis são as mesmas, e uma plataforma tomou-as por si sem lhe dizer quais.

Pressupõe conforto com bases de dados e APIs. API Design e Arquitetura e System Design são os vizinhos naturais, e esta apostila assume-os em vez de os repetir.

1.4 Uma advertência sobre o que se lê por aí

A maior parte do material técnico sobre comércio digital é norte-americano, e há duas áreas em que isso o torna não apenas incompleto, mas errado para quem vende na Europa: a autenticação do pagamento (cap. 6) e o direito de devolução (cap. 11). Nas duas, o que lá é opcional aqui é obrigatório — e numa delas a obrigação é de Junho de 2026.

2.1 Três coisas que toda a gente chama «produto»

Confundir os três é a origem de metade dos problemas de catálogo. Existências pertencem à variante, nunca ao produto — «temos 40 camisolas» não é informação acionável se 38 forem tamanho XS.

2.2 Preço não é uma coluna

2.3 Estados, não apagar

Um produto que deixa de ser vendido não pode desaparecer — está em encomendas antigas, em facturas, em devoluções ainda por chegar. Nunca apague; mude o estado: rascunho, activo, descontinuado, arquivado. Só o segundo aparece na loja; todos continuam a existir para o histórico.

2.4 O que torna um catálogo encontrável

Três coisas que valem mais do que qualquer motor de busca sofisticado: atributos estruturados (não escondidos na descrição), vocabulário do cliente em vez do interno — quem procura «casaco» não procura «outerwear» —, e sinónimos com registo do que não teve resultados. A lista de pesquisas sem resultado é o documento mais útil de uma loja, e quase ninguém a lê.

3.1 O código que toda a gente escreve primeiro

// ler, decidir, escrever — três passos separados
var stock = repo.stockDe(sku);        // lê 3
if (stock >= quantidade) {            // decide: pode
  repo.definirStock(sku, stock - 1);  // escreve 2
  criarEncomenda(...);
}

Com um cliente de cada vez, está correcto. Com sete a carregar no mesmo segundo, os sete leem 3 antes de qualquer um escrever, os sete decidem que podem, e os sete recebem confirmação. Vendeu sete unidades de três.

3.2 A correcção, que cabe numa linha

-- ler, decidir e escrever numa só operação atómica
UPDATE variantes
   SET stock = stock - :qtd
 WHERE sku = :sku
   AND stock >= :qtd;

-- 1 linha afectada → reservado. 0 linhas → não havia.

A base de dados decide, e decide uma vez de cada vez. O número de linhas afectadas é a resposta — não é preciso ler antes nem confiar no que se leu.

3.3 Reservar não é vender

Entre pôr no cesto e pagar passam minutos. Se o stock só descer no fim, dois clientes chegam ao pagamento com a mesma unidade. Se descer no início, um cesto abandonado bloqueia stock para sempre.

A reserva tem de ter prazo — tipicamente 15 a 30 minutos — e alguém tem de a libertar quando expira. Uma reserva sem prazo é uma fuga: o stock desaparece do sistema sem sair do armazém, e ninguém liga a rotura ao carrinho que alguém abandonou há três semanas.

3.4 Sobrevender de propósito

Nem sempre é erro. Uma loja que reabastece depressa pode aceitar mais do que tem para não perder vendas. A diferença entre estratégia e avaria é uma só: o cliente sabe? «Envio em 3 a 5 dias» é uma promessa diferente de «em stock», e prometer a segunda para entregar a primeira é o que gasta a confiança que o capítulo 1 dizia decidir a compra.

4.1 Porque não é um formulário

Um formulário submete-se e acaba. Um checkout é interrompido: o cliente fecha o separador, muda de dispositivo, é levado ao banco para se autenticar (cap. 6), volta vinte minutos depois. Cada uma dessas interrupções tem de encontrar o processo onde ficou.

4.2 O campo que não existe é o campo que não falha

4.3 As três coisas que têm de estar visíveis antes do botão

1. O custo total. Portes que aparecem no último passo são a segunda maior causa de abandono, e a mais irritante porque é evitável.
2. Quando chega. Uma data estimada vale mais do que o nome do serviço de transporte.
3. Como se devolve. Não é letra pequena — é um argumento de venda, e a partir do capítulo 11 é também uma obrigação legal.

4.4 Erros que não expulsam

Validar no lado do cliente e no servidor, mostrar o erro ao lado do campo, e nunca perder o que já foi preenchido. Um checkout que devolve a página em branco depois de um erro perdeu a venda — e a irritação é lembrada muito depois de o erro ser corrigido. UX Writing e Microcopia trata do texto destas mensagens, que é onde a diferença se joga.

5.1 Os dois momentos

5.2 A chave de idempotência

O cliente carrega duas vezes. A rede repete o pedido. O seu código tenta outra vez porque não recebeu resposta. Em qualquer destes casos, sem protecção, cobra duas vezes.

POST /pagamentos
Idempotency-Key: enc_8f4c2a91-checkout   // gerada UMA vez, no início

// 1ª vez  → processa e guarda o resultado sob esta chave
// 2ª vez  → devolve o MESMO resultado, sem cobrar de novo

5.3 O webhook é a fonte de verdade, não o regresso do cliente

O padrão errado, e é o mais comum: criar a encomenda quando o cliente volta à página de sucesso. Basta o cliente fechar o separador ao voltar do banco para o dinheiro ter sido cobrado e a encomenda não existir.

5.4 Reconciliar, porque os dois lados divergem sempre

Uma vez por dia, compare o que o sistema julga ter cobrado com o que o fornecedor diz ter cobrado. Vão divergir — um webhook perdido, uma captura falhada, um reembolso feito no painel do fornecedor e não no seu sistema. A pergunta não é se acontece; é se descobre no dia seguinte ou no fecho do trimestre.

6.1 O que a lei exige

A Directiva dos Serviços de Pagamento (PSD2, 2015/2366/UE) introduziu a autenticação forte do cliente — em inglês, Strong Customer Authentication —, em vigor desde 13 de Setembro de 2019. Exige que o pagamento seja confirmado com pelo menos dois de três factores independentes:

Na prática, quase sempre uma passagem pela aplicação do banco, ou por um ecrã de autenticação intermédio, a meio do pagamento.

6.2 As isenções, e porque não se deve contar com elas

Quem decide é o banco emissor, não o comerciante. Pode pedir a isenção e ser recusada. Desenhe sempre para o caso em que a autenticação acontece e trate a isenção como um bónus — o inverso produz um sistema que funciona em testes e falha com clientes reais.

6.3 O que se ganha: a responsabilidade muda de lado

Numa compra autenticada, a responsabilidade por uma contestação fraudulenta desloca-se do comerciante para o emissor. É o contrapeso ao atrito: mais um passo no checkout, e menos exposição a fraude com cartão roubado — que é o tipo de fraude que, sem autenticação, o comerciante paga sozinho, com o produto já expedido.

6.4 O que aí vem, e o cuidado a ter ao ler sobre isso

Há uma revisão em curso — uma terceira directiva e um regulamento de serviços de pagamento — com acordo político alcançado em Novembro de 2025. Não estava adoptada em definitivo à data desta apostila. Vai encontrar muito texto a descrevê-la como se já fosse lei; antes de mudar um sistema por causa disso, confirme o estado do processo legislativo na fonte do capítulo 12.

7.1 Nunca em vírgula flutuante

// o clássico, e é verdade em quase todas as linguagens
0.1 + 0.2 === 0.3   // false
0.1 + 0.2           // 0.30000000000000004

Números de vírgula flutuante são aproximações em base dois. Aplicados a dinheiro, produzem diferenças minúsculas que se acumulam e aparecem no fecho de contas, na diferença entre a soma das linhas e o total, ou numa factura que não bate certo por um cêntimo.

7.2 Arredondar: onde, e uma vez só

Três linhas a 33,33 € com 23% de imposto podem dar dois totais diferentes conforme se arredonde por linha ou no fim. Nenhum está errado; ter os dois no mesmo sistema, sim.

Escolha uma regra, escreva-a, e aplique-a em todos os sítios — incluindo no que a factura mostra. Um cliente que soma as linhas e não chega ao total escreve ao apoio, e tem razão.

7.3 O IVA transfronteiriço, que apanha quem vende para fora

Desde Julho de 2021, existe um limiar único de 10 000 € por ano para o conjunto das vendas à distância a consumidores noutros Estados-membros. Abaixo dele, aplica-se tipicamente a taxa do país de origem; acima, aplica-se a taxa do país do consumidor.

7.4 A factura é imutável

Emitida, uma factura não se altera. Corrige-se com outro documento — nota de crédito. Isto tem duas consequências no modelo do capítulo 2: os valores são copiados para o documento, e a numeração é sequencial e sem buracos. Um número reservado e não usado é um problema, e reciclá-lo é pior.

8.1 Os estados que faltam sempre

Os quatro marcados são os que quase nunca estão no primeiro desenho, e cada um deles aparece na primeira semana de operação real.

8.2 Transições, não atribuições

A diferença entre um sistema que se aguenta e um que não: as transições permitidas são explícitas. De entregue não se volta a a aguardar pagamento. De cancelada não se passa a expedida. Escrever a lista das transições legais — e recusar as outras — é meia hora de trabalho que impede uma categoria inteira de estados impossíveis.

É a mesma ideia dos tipos fechados que Java e Spring aplica com sealed: tornar o estado impossível inexprimível, em vez de confiar que ninguém o vai escrever.

8.3 Guardar o que aconteceu, não só o que é

É o mesmo princípio dos acontecimentos contra atributos de Email, CRM e Retenção: um estado substituído apaga o passado, e em comércio o passado é o que se tem de conseguir provar.

8.4 A encomenda não é o pagamento

São dois ciclos com ritmos diferentes, e juntá-los numa tabela é o que torna impossível representar o reembolso parcial, a segunda tentativa de pagamento ou a captura que falha depois da expedição. A encomenda é o que o cliente comprou; o pagamento é uma sequência de operações de dinheiro associadas a ela. Um para muitos, sempre.

10.1 O custo de servir, decomposto

10.2 A promessa é um contrato

«Entrega em 2 a 3 dias úteis» é uma promessa cujo cumprimento não controla — depende da transportadora. Duas regras que reduzem quase todo o atrito:

• Prometa a partir de dados, não de brochura. Se a média real são 4 dias, prometer 2 gera contactos de apoio em cada encomenda.
• Avise antes de falhar. Um email a dizer «vai atrasar dois dias» custa muito menos do que um cliente a descobrir sozinho — e é a diferença entre um contratempo e uma queixa.

10.3 Seguimento: o email que evita o contacto

Cada «onde está a minha encomenda?» é tempo de pessoa. A maior parte evita-se com três mensagens automáticas — confirmada, expedida com código de seguimento, entregue — que são também as três de Email, CRM e Retenção que ninguém classifica como marketing e toda a gente lê.

Note a implicação do capítulo 4 da apostila de retenção: estas mensagens saem do domínio transaccional. Se partilhar domínio com as promoções, uma campanha infeliz impede o cliente de receber o código de seguimento — e aí o custo de apoio volta todo.

10.4 Onde está o stock não é onde está o número

O stock do sistema e o stock da prateleira divergem sempre: quebras, erros de contagem, artigos danificados, devoluções ainda por conferir. A pergunta não é como evitar a divergência — é com que frequência se mede.

Contagem cíclica, por amostragem contínua, em vez de um inventário anual que pára a operação. E uma regra clara sobre o que fazer quando falha: é preferível uma loja que diz «esgotado» a uma que aceita e cancela — a segunda gasta a confiança do capítulo 1 e o dinheiro do capítulo 5.

11.1 Os catorze dias

A Directiva dos Direitos dos Consumidores (2011/83/UE) dá ao consumidor 14 dias para se retractar de uma compra à distância, sem indicar motivo. O prazo conta a partir da recepção dos bens — não da encomenda.

Há excepções — bens personalizados, perecíveis, selados por razões de saúde já abertos, entre outras. São excepções específicas, não uma cláusula geral de escape.

11.2 O fluxo inverso é um fluxo, não uma excepção

Cada passo precisa de estado próprio, e o reembolso tem de saber a que operação de pagamento corresponde. É por isso que o capítulo 8.4 separa encomenda de pagamento — sem essa separação, um reembolso parcial não tem onde existir.

11.3 A economia, que decide mais do que a regra

Uma devolução custa o transporte de volta, o tempo de conferência, a perda de valor do artigo e, muitas vezes, o reembolso dos portes originais. Em várias categorias, é mais barato reembolsar sem pedir o artigo de volta — e é uma decisão racional, não generosidade.

12.1 As doze regras

1. Existências pertencem à variante, nunca ao produto.
2. Modele os eixos de variação como dados, não como colunas do esquema.
3. Copie o preço e a taxa para a linha de encomenda. A factura é um documento sobre o passado.
4. Ler, decidir e escrever têm de ser uma só operação sempre que o valor for disputado.
5. Reservas têm prazo, e alguém tem de as libertar.
6. Autorizar não é capturar. Capture ao expedir e vigie a validade.
7. A chave de idempotência nasce no início da compra, não no momento do envio.
8. O webhook é a fonte de verdade; o regresso do cliente só mostra.
9. Desenhe sempre para o caso em que a autenticação acontece. A isenção é bónus.
10. Dinheiro em inteiros, com a moeda ao lado, e uma só regra de arredondamento.
11. Transições explícitas. Correcções manuais na base de dados são o modelo a falhar.
12. Devolução é fluxo, não excepção — e na UE é direito, não política.

12.2 Catálogo: onde verificar

As seis ligações foram verificadas em Setembro de 2026.

12.3 O que vem a seguir

12.4 A última ideia

Quase tudo o que corre mal numa loja tem a mesma forma: alguma coisa aconteceu ao mesmo tempo que outra, ou fora da ordem esperada, e o código assumia que não. As suposições não estão escritas em lado nenhum — é por isso que ninguém as revê, e por isso que a primeira campanha a sério é sempre a primeira auditoria a sério.

O resto é a constante mais antiga do comércio, que a prospectiva já dizia: preço, disponibilidade e confiança decidem a compra. Um stock que mente destrói os três de uma só vez, e nenhuma das doze regras acima existe por outra razão.