WooCommerce headless com Astro

WooCommerce headless não é uma loja nova. wp-admin, stock, encomendas e gateways ficam. O HTML que o cliente descarrega já não é um tema PHP. O Astro 7 imprime o catálogo. O checkout, se a loja cobra em MB Way e Multibanco, fica no WooCommerce.

Um pedido clássico de WooCommerce corre PHP, a object cache, a lista de plugins e o tema, para uma ficha de produto que não mudou desde terça. Uma cache HTML à frente do origin resolve grande parte disto. Headless é o corte seguinte: o catálogo é uma árvore estática, o carrinho é uma ilha pequena, o dinheiro continua a bater no origin que já tem âmbito PCI.

Este artigo é o corte. Camadas de cache, TTFB e LCP de campo vivem em Headless WooCommerce com Astro, desempenho de comércio eletrónico. As superfícies comerciais são programador WooCommerce e programador Astro. A mesma separação sem carrinho está no guia de arquitetura headless.

A Portent mediu uma queda de conversão de cerca de 4,42% por cada segundo extra de carregamento. É uma inclinação, não uma promessa de que o Astro imprime dinheiro. Vamos para headless quando o tema e a lista de plugins são o teto, não quando o briefing é uma captura de PageSpeed.

No WordCamp Porto o briefing repetiu-se três vezes em 2025: Core Web Vitals no catálogo, e duas sprints depois o produto real ainda era a referência Multibanco. A ficha sai do PHP. A cobrança, em Portugal, quase nunca.

#O que fica de facto no WooCommerce

O back office não se mexe. Produtos, variações, stock, cupões, encomendas, reembolsos, relatórios. Stripe, PayPal, Klarna, MB Way, Multibanco, Payshop. Portes por tabela, pontos CTT, DPD Pickup. Plugins de IVA e OSS. Conectores ERP que escrevem na encomenda. Isto é PHP, e deve continuar a ser PHP.

O que sai é o tema da loja: header.php, o template de produto, o widget do mini-carrinho, o Elementor na homepage, o zoom da imagem, o carrossel de “completar o look” que enfileira 200 KB para mostrar três referências.

A redação continua no mesmo wp-admin. Se não puder, não foi headless. Montou um segundo PIM e vai odiá-lo ao terceiro mês. Numa loja de têxtil em Famalicão a equipa de produto continuava a publicar fichas no WooCommerce. O erro foi dar-lhes também um CMS de catálogo “moderno” para traduzir atributos. À sexta semana pediam o editor de produto de sempre. Uma origem de verdade do produto. O HTML é um consumidor, não um segundo armazém.

xmlrpc e a rota pública de utilizadores REST precisam do mesmo endurecimento que qualquer origin WordPress. Headless não esconde o wp-admin. Ponha Access ou Zero Trust à frente. A CDN do catálogo não é uma firewall.

Encomendas, notas internas, reembolsos parciais e o correio de “encomenda recebida” saem do WooCommerce. O frontend Astro não assina esses e-mails. Se um agente de atendimento precisa de mudar um estado, faz isso no wp-admin, não num painel React paralelo. Dois painéis de encomenda é assim que se perde um reembolso de MB Way.

Os relatórios do WooCommerce (e os que o ERP lê) continuam a ler a tabela de encomendas. Headless não muda o modelo de dados. Muda quem imprime o HTML da ficha. Se a contabilidade pede um CSV à sexta, continua a sair de PHP.

O campo NIF, a checkbox “fatura com NIF” e o texto legal junto ao ato de comprar não são merchandising da ficha. São dados da encomenda. Ficam no origin. O catálogo pode repetir NIF e morada no rodapé estático. A encomenda leva a cópia que a contabilidade já edita sem um deploy Astro.

#O plugin que morre com o tema

Este é o inventário que ninguém quer fazer, e é todo o risco.

Morre com o tema (reconstrói-se como ilha, ou deita-se fora):

• Swatches de variação que substituem a lista por pontos de cor
• Vista rápida e adicionar ao carrinho por Ajax no loop
• Zoom de imagem e visores 360
• Popups de upsell, barras de escassez falsa, widgets de “outros também compraram” que pintam em woocommerce_after_shop_loop
• Page builders na homepage e em landings de produto
• Plugins de checkout de uma página que se apropriam dos templates checkout

Fica (API ou webhook, sem tema):

• Gateways de pagamento (IfthenPay, EuPago, Stripe, PayPal, SIBS)
• Envio e recolha (CTT Expresso, CTT Pontos, DPD, recolha local, tarifas por tabela)
• Impostos (incluindo OSS)
• Subscrições e memberships, enquanto o estado se consulta e não é o CSS do plugin a pintá-lo
• Klaviyo / Mailchimp / E-goi por hooks de encomenda
• ERP (ver o pillar de integração WooCommerce ERP)

Se os truques de conversão da loja vivem na primeira lista, headless é um redesign, não um projeto de velocidade. Faça o orçamento como redesign. O alcance do programador WooCommerce é honesto com esse corte. Vimos uma loja “passar a headless” e reinstalar o tema antigo no checkout porque o plugin de uma página era o produto a sério. Isso são duas montras. Não faça isso.

Um teste útil: no staging desative o tema e carregue um URL de produto com um tema em branco. O que continua lá (preço, stock, adicionar ao carrinho via Store API) é o que fica. O que desapareceu (swatches, badges, HTML do estimador de entrega) é trabalho. Se a lista desaparecida é a razão pela qual compram, reserve orçamento para ilhas. Se é decoração, deite fora.

Produtos compostos, packs e add-ons estão na zona cinzenta. Alguns expõem REST, outros só filtram woocommerce_add_to_cart. Se adicionar um pack ao carrinho dá 404 na Store API, essa referência não é catálogo estático até alguém escrever o mapeamento. Não descubra isto na manhã do corte.

Numa loja de material desportivo em Braga o “configurador” de tamanho e gravação era um plugin que enganchava o loop e escrevia na sessão PHP. A Store API não conhecia a gravação. O catálogo publicou-se em Astro e o botão de compra devolvia um carrinho com o tamanho e sem o texto. O arranjo não foi mais GraphQL. Foi deixar essa ficha em PHP até haver um atributo real e um endpoint que o aceite.

Os badges de “envio 24/48” que o tema pinta a partir de uma meta são dados. Leve-os para o payload de SSG. Os badges que um plugin de escassez pinta com um temporizador em JavaScript não são dados. São um penso de conversão. Em headless ou deita-os fora, ou reescreve-os como ilha com regras que consiga explicar. Um temporizador a mentir no catálogo estático é o mesmo temporizador a mentir no tema. Mudar o formato não torna o texto verdadeiro.

Os shortcodes dentro da descrição longa são o outro buraco. the_content de um produto não é um contrato. Se a ficha cola [delivery_estimator] ou um formulário de tamanhos de um page builder, esse HTML espera um runtime PHP. Ou substitui o shortcode por um campo que o Astro saiba pintar, ou essa ficha não sai do tema.

Widgets CTT e DPD no loop da categoria (“levantar neste ponto”) também morrem. A tarifa pode ficar, porque é PHP no origin. O mapa de pontos é vizinho do tema. Se o inventário o classificar como envio, vai descobrir no corte que o mapa era HTML injetado no template, não uma API.

#Astro 7 para o catálogo, não para a loja

O defeito do Astro 7 é HTML e CSS. JavaScript só onde marca uma ilha.

Catálogo que deve ser estático:

• Home, categoria, produto, conteúdos, páginas legais de leitura
• getStaticPaths a partir da lista de produtos no build
• AVIF a partir da biblioteca de média, sizes que coincidem com a grelha, não 100vw numa miniatura de 320 px

Ilhas:

• Adicionar ao carrinho, quantidade, seletor de variação
• Mini-carrinho
• Pesquisa que bate num índice, não em PHP ?s=
• Talvez Stripe Elements num passo de pagamento à medida, se de facto não puder redirecionar

client:visible no adicionar ao carrinho. client:idle na pesquisa. Uma ficha que importa um pack inteiro de ícones para dentro da ilha já perdeu o ponto. A mesma regra que qualquer outro front Astro 7: a ilha é um componente, não uma desculpa para hidratar a página.

Rebuilds: um webhook updated de produto reconstrói esse caminho, ou um conjunto pequeno (produto, as suas categorias, a home se faz merchandising). Rebuilds de catálogo inteiro a cada dez minutos são assim que se descobre que tem 40 000 SKU. Incremental ou sob pedido. Cloudflare, ou o host que já usa. Não “Vercel porque o tutorial dizia” se o resto da pilha já está no Cloudflare Pages.

Pesquisa: PHP ?s= é um hit PHP. Num catálogo estático, a pesquisa é um índice no cliente (catálogos pequenos), um índice externo (Algolia, Meilisearch, Typesense) alimentado com o mesmo payload que o SSG, ou uma consulta Store API / REST a partir de uma ilha. Não mande a caixa de pesquisa para o WordPress se o resto da loja nunca o faz. As facetas que precisam de stock ao vivo vão junto da caixa de compra, não no HTML do SSG.

Produtos relacionados: se estão merchandised no wp-admin, são dados. Consulte-os no build. Se saíam de woocommerce_output_related_products do tema, nunca foram dados, foram template. Reconstrua-os como faixa estática da mesma categoria, ou deite fora.

As imagens ficam na biblioteca de média do WordPress. O Astro lê URLs, ou um passo de build copia AVIF. Não invente um segundo DAM salvo se já o tiver. A imagem LCP continua a ser o hero da ficha. Headless não escolhe o formato por si. Um PNG de 3 MB no origin continua a ser um PNG de 3 MB na edge. Isso discute-se no guia de desempenho, não aqui.

A pré-visualização editorial precisa de ver um rascunho de produto no host Astro. Um webhook ou um token de preview que pede um produto ao origin chega. Se preview significa “entre no wp-admin e use o personalizador do tema”, não acabou o corte, e vão continuar a pedir o tema velho.

O catálogo é um documento. O carrinho é uma aplicação. Misturar os dois no mesmo runtime é assim que o Next acaba a hidratar a ficha para mudar uma lista de tamanho.

Não hidrate avaliações, a tabela de tamanhos nem o bloco de “portes grátis a partir de” se esses dados já vinham no payload de build. Uma ilha por ficha, não uma SPA por ficha. O programador Astro que trata cada secção como candidata a client:load está a montar o tema PHP outra vez, com mais passos.

Landings de campanha no Elementor todas as quintas-feiras não são catálogo. Ou lhes dá um contrato de blocos com preview no Astro, ou deixa essas URLs no WordPress e só tira /produto/ e /categoria/. Headless por URL, não por religião. Uma marca de cosmética em Lisboa que publicava seis landings por mês no builder descobriu isto na semana do corte: as URLs de anúncio apontavam para templates PHP que já ninguém atualizava. O catálogo estava rápido. A aquisição estava morta.

#Store API versus GraphQL para carrinho e catálogo

Dois tubos. Misturá-los é a ferida autoinfligida habitual.

Build de catálogo: WPGraphQL + WooGraphQL, ou o endpoint REST de produtos, em tempo de build. Uma consulta por ficha. Quer nome, preços, estado de stock, imagens, categorias, atributos. Não quer o carrinho.

Carrinho e sessão: WooCommerce Store API (/wp-json/wc/store/v1/cart). É dona do cookie do carrinho, nonces, cupões, cálculo de portes. Esse cookie tem de estar no origin que mais tarde recebe o checkout. Se o sítio Astro é loja.exemplo.pt e o Woo é cms.exemplo.pt, tem um problema de cookie antes de ter um problema de React. O mesmo sítio, ou um proxy documentado.

Vemos equipas adicionar ao carrinho com mutações WooGraphQL porque o catálogo já fala GraphQL. Depois a página de checkout no WooCommerce mostra o cesto vazio. A sessão não se moveu. Store API para o carrinho. GraphQL para o payload de SSG. Escreva isto no canal de desenvolvimento.

Cookies do mesmo sítio: se o Astro está no apex e o WordPress em wp., fixe o domínio do cookie do carrinho de forma explícita e faça proxy de /wp-json/wc/store/ para o origin. CORS na Store API não substitui o cookie. SameSite=Lax num redirecionamento de checkout entre dois hosts parece “o MB Way funciona no staging” (mesmo host) e “carrinho vazio em produção” (dois hosts). Um hostname para quem compra, hostname interno para o wp-admin.

O nonce que caduca numa página estática é um bug real. A ilha do carrinho tem de pedir um nonce fresco à Store API ao hidratar, não cozer um no HTML do SSG desta manhã. Os nonces cozidos respondem 403 ao fim de umas horas e o botão de adicionar ao carrinho “não faz nada”. Numa loja de vinhos em Vila Nova de Gaia esse sintoma diagnosticou-se como “o Astro está partido”. Não estava. O HTML das 06:00 levava um nonce das 06:00.

O stock no build é uma fotografia. Um tamanho esgotado que continua no HTML é uma devolução. O webhook woocommerce_product_set_stock (ou o equivalente da variação) tem de invalidar esse caminho. Se não puder fazê-lo, não faça SSG da caixa de compra. Pinte-a a partir da Store API no momento do pedido, ainda como ilha pequena. O HTML do catálogo pode continuar estático.

Os cupões vivem na Store API. Um código colado num banner estático serve como merchandising. Aplicá-lo é um POST ao carrinho, não um campo no SSG. O mesmo com o cálculo de portes: uma tabela de continente na ficha é texto. A tarifa legal sai no checkout, com código postal. Não congele portes por distrito no HTML salvo se também congelar caminhos por distrito e souber invalidá-los. Açores e Madeira não são uma linha de rodapé. São regras de envio no origin.

GraphQL brilha quando a ficha precisa de produto, variações, atributos, imagem e três relacionados numa só ida. REST brilha em webhooks e escritas. A Store API brilha porque já fala a língua do carrinho. Três ferramentas, três trabalhos. Um cliente Apollo que muta o carrinho é um quarto trabalho que não pediu.

#Manter o checkout no WooCommerce, não numa ilha Astro

O default é híbrido: catálogo estático, carrinho ilha, checkout PHP. Redirecionar para /checkout/ com o cookie da Store API já posto, cache HTML em bypass. Cada plugin de gateway, de portes e de “encomenda recebida” dispara como ontem.

Checkout à medida no Astro significa reimplementar morada e código postal, portes que mudam com o CP, IVA, JS das gateways, retornos 3-D Secure, tentativas de pagamento falhado e ligações “pagar encomenda” que saem do correio. Fizémo-lo quando uma marca precisava de um passo que nenhum template PHP aguentava. É um produto. Não é o default.

PCI fica onde estava. O titular introduz o cartão no terminal da gateway, não no origin e não numa ilha que reenvia PAN. O híbrido não alarga o âmbito. O checkout à medida, sim, salvo se copiar ao milímetro o fluxo alojado que já tinha.

Páginas de encomenda recebida e a minha conta podem continuar no WooCommerce. Headless não significa “cada URL é Astro”. Significa que os URLs que se anunciam são ficheiros. /a-minha-conta/ atrás de Access ou atrás de login está bem como PHP.

O detalhe português (MB Way, Multibanco, CTT, fatura) não cabe neste parágrafo. Cabe na secção a seguir ao stock. O corte operacional é o mesmo: não “acabe o headless” a reescrever o único template que já cobra.

#Stock, cache

Ficheiros estáticos numa CDN escalam. O stock não. Dois clientes a comprar a última unidade é um problema de loja, não de PageSpeed.

O padrão que aguenta:

1. O HTML do catálogo é estático, preço incluído, até um webhook dizer o contrário.
2. A caixa de compra pergunta à Store API o stock_status ao hidratar a ilha, ou aceita uma janela curta de dado velho e compensa no checkout (o WooCommerce já recusa a sobrevenda se o configurou assim).
3. A criação da encomenda é origin. ERP e correio disparam aí.

“Utilizadores concorrentes ilimitados” é verdade para o HTML. É falso para o checkout, para o stock, para a base de dados. Dimensione PHP para o pico de checkout que de facto tem (um drop, uma newsletter, a Black Friday, o Natal). A CDN não passa o cartão e não passa o MB Way.

Uma cache HTML à frente de um tema clássico continua a ser a primeira alavanca. Se o TTFB já é baixo e o LCP é a imagem hero, leia o irmão de desempenho. Headless não endireita um PNG de 3 MB.

A sobrevenda de um tamanho 42 num drop de calçado em São João da Madeira não se discute no canal de frontend. Discute-se no de operações: o webhook chegou, o caminho invalidou-se, a ilha perguntou, o checkout recusou? Quatro armadilhas, quatro donos. Se só mede LCP, não vê o tamanho 42.

Os transients de stock na object cache e o HTML estático são dois relógios. Sincronize-os por evento (webhook), não por cron de dez minutos. O cron é o motivo pelo qual um tamanho esgotado às 10:03 continua “adicionar ao carrinho” até às 10:10. Num drop isso são encomendas que depois cancela à mão.

Cloudflare (ou o host que use) pode reconstruir um caminho. Não pode reconstruir o armazém. O ERP da integração WooCommerce continua a ser a verdade de existências se assim o pactuaram. O WooCommerce é o escravo que o checkout consulta. O Astro não é um terceiro armazém.

Dois últimos conjuntos do mesmo tamanho 42 são o ticket clássico. O HTML estático diz “há”. A ilha depois da hidratação diz “não há”. O checkout Woo recusa. O cliente vê três verdades em noventa segundos. Ou o webhook de stock invalida a ficha antes do drop se espalhar, ou a caixa de compra é viva, ou vende a mais de propósito e acerta no checkout. Escolha uma e escreva-a no runbook. Não deixe isto como “a CDN aguenta tudo”.

#MB Way, Multibanco e a fatura que continua no PHP

O tutorial com Stripe Elements cala-se sobre MB Way, referência Multibanco e o mapa de pontos CTT. A conversão de uma loja portuguesa senta-se no checkout, e o checkout é uma pilha de plugins que imprimem HTML nos templates Woo.

MB Way não é um botão que copia para uma ilha. É um método SIBS, quase sempre dentro de um plugin de gateway (IfthenPay, EuPago, Easypay, o gateway SIBS que a loja já tem no wp-admin). O plugin pede o número de telemóvel no template de checkout, cria a encomenda no Woo, dispara o pedido à SIBS e espera um callback no origin. Esse POST não pode cair na CDN do Astro. Pintar um botão “MB Way” numa ilha sem o contrato da gateway é um protótipo. A encomenda fica em “aguardando pagamento” e o atendimento liga ao desenvolvimento.

Multibanco é o outro método que o telemóvel português espera ver ao lado do cartão. Entidade, referência, valor. O plugin gera a referência quando a encomenda existe no Woo. O cliente paga no multibanco, no homebanking ou na app, horas depois. O estado muda quando o callback chega ao PHP. Se o checkout Astro cria um PaymentIntent noutro sítio e só depois faz POST da encomenda, não há referência, não há entidade, não há e-mail com os três números. A loja vendeu um ecrã. Não vendeu um método de pagamento.

Payshop segue o mesmo padrão: referência gerada no origin, pagamento tardio, webhook no PHP. Não é um widget solto.

IfthenPay e EuPago (e os primos que a loja já paga) engancham o checkout Woo. Os retornos, as notificações e as URLs /?wc-api= pertencem à lista de omissão de cache, cada uma com nome. Checkout como ilha Astro significa reimplementar esses retornos. Por omissão não o fazemos.

Vimos uma loja de cosmética em Lisboa que, depois de um tutorial com Stripe Elements, escondeu o Multibanco porque “o cartão é mais moderno”. No telemóvel, um checkout português sem Multibanco e sem MB Way é outra loja. Ao fim de duas semanas voltaram ao checkout Woo e deixaram o Astro no catálogo. Foi a correção certa, não uma falha de headless. A falha foi desligar o checkout.

Os widgets CTT Expresso, CTT Pontos e DPD Pickup (mapa de ponto, geolocalização, gravação do point_id na meta da encomenda, depois etiqueta e tracking) injetam-se nos templates de checkout. Morrem no dia em que sai desses templates. No híbrido ficam. Se insistir num checkout Astro, reconstrói o widget contra a API do transportador, com o mesmo contrato de código postal e de peso que o Woo já calcula. Isso não é uma sprint de “pôr um mapa”. É um segundo produto de envios. A maior parte das lojas não precisa.

Portes continente versus Açores e Madeira continuam a calcular-se no origin. Uma linha estática “portes grátis em Portugal” na ficha é merchandising. A linha legal sai no checkout, com o CP. Não congele essa frase no SSG de março se em agosto passou a servir as ilhas, ou se deixou de as servir.

A fatura não sai do Astro. A origem da fatura fica no PHP: a encomenda muda de estado no WooCommerce e o conector de faturação emite. Moloni, InvoiceXpress, Vendus, PHC, Primavera, Sage. O gancho é woocommerce_order_status_processing ou pago. Software certificado, ATCUD, QR da fatura, SAF-T (PT): isto vive no programa de faturação que ouviu a encomenda Woo, não no HTML do catálogo. Este texto não é um guia fiscal e não substitui o contabilista que a loja já paga. O que auditamos é se o gancho ainda dispara depois do corte.

Se um checkout próprio faz PaymentIntent no Stripe e só mais tarde faz POST da encomenda ao Woo, o plugin de faturas ou cala-se, ou recebe um documento sem taxas de IVA e sem NIF. A contabilidade não engole isso. Deixe o nascimento da encomenda onde a contabilidade já escuta.

Campo NIF, checkbox “compra com NIF”, validação do número: são campos de checkout de plugins portugueses, não da ficha de produto. No Astro não os recriamos “para a marca ficar redonda”. Ficam no PHP. Contra-reembolso também: é método de pagamento mais método de envio no origin.

IVA e OSS calculam-se no origin. Um preço em EUR na ficha é preço de merchandising. A linha de checkout é a legal. Não faça SSG por país salvo se também fizer caminhos por país e souber invalidá-los. A maior parte das lojas mostra um preço de catálogo e deixa o Woo aplicar o imposto ao pagar. Isso vale. Mostrar um IVA português congelado a um visitante em França é assim que a contabilidade lhe escreve.

Webhooks das gateways (/?wc-api=, notificações IfthenPay, EuPago, Stripe) batem no origin, não na CDN do Astro. Cada caminho de skip de cache tem nome. A mesma disciplina que um WAF: se não tem nome, alguém o vai cachear.

Híbrido que pomos: catálogo estático, carrinho como ilha Store API, ligação “Finalizar compra” para /checkout/ Woo, cache omite esse caminho, cookie do carrinho já sentado. Cada gateway, cada imposto, cada e-mail “encomenda recebida”, cada gancho woocommerce_thankyou (ERP, fatura, transportador) continua a disparar. O âmbito PCI fica onde estava.

Não “acabe o headless” a reescrever o único template que já gera referência Multibanco. O argumento de conversão nas lojas portuguesas que separamos era: a ficha é o sítio de rejeição, o checkout não. Deixe o checkout. Tire o PHP do URL do produto.

#Quando não ir para headless

• Catálogo de umas dezenas de SKU, sem problema de tráfego, edições no personalizador todas as semanas
• A montra é a lista de plugins (builders, checkout de uma página, chat embutido no tema)
• Ninguém da equipa vai ser dono do repositório Astro depois do lançamento
• O briefing é “PageSpeed no máximo” e a ficha já tem cache HTML e AVIF

Então: dieta de plugins, cache HTML, pipeline de imagem, espaço de consentimento. Mais barato, reversível. Headless é um corte de sistemas. Agora tem dois deploys, duas pré-visualizações, dois modos de falha. Compensa quando o tema é o gargalo e o catálogo é sobretudo leitura.

Subscrições e memberships: o direito vive no Woo. A página Astro pode mostrar “tem acesso” se puder perguntar. Se o plugin de membership só pinta ao embrulhar the_content em PHP, esse conteúdo não está no seu SSG. Ou o expõe, ou deixa esses URLs no WordPress.

Uma loja B2B em Matosinhos com preços por função, mínimos de encomenda e pagamento a 30 dias não é um catálogo estático com uma ilha. O preço que o comprador vê depende de uma sessão. O Astro pode imprimir a ficha genérica. A caixa de compra, o preço líquido e o checkout ficam no PHP, ou monta um runtime por pedido (e então pergunte-se porque chama a isto headless).

Se o marketing publica landings de campanha no Elementor todas as quintas e espera vê-las em produção à sexta, um catálogo Astro tira-lhes essa alavanca. Ou lhes dá um contrato de blocos com preview, ou deixa as landings no WordPress e só tira produto e categoria.

Ninguém dono de TypeScript mais um freelancer PHP que “já se desenrasca no front” é a fila de incidências do trimestre. Dois pipelines sem dono não é arquitetura.

Se a loja ainda não tem staging fiável, logs, backups testados e um runbook de IfthenPay, headless acrescenta pontos de falha. Corrija tema, imagens, cache e alojamento primeiro. A separação da frente entra quando a organização já trata a loja como sistema.

#Sequência de migração

1. Inventário. Lista de plugins em fica / morre / desconhecido. O desconhecido é um spike, não uma surpresa no dia do corte.
2. API na loja viva. A Store API já está no WooCommerce moderno. GraphQL se o build do catálogo o quiser. O cliente não vê nada.
3. Catálogo Astro num host de staging, dados reais de produto, ainda sem checkout. Compare permalinks. Aqui saem as lutas de barra final e de base de categoria, não na semana oito.
4. Ilha de carrinho + cookie contra o origin de staging. Adicionar, cupão, esvaziar. Então, e só então, ligue o checkout.
5. O checkout continua no Woo. Bypass de cache. Gateways em sandbox a sério (IfthenPay de testes, não um mock). Correio de encomenda. Caminho de reembolso. Um pagamento MB Way de 1 € no terminal de teste não é opcional. Uma referência Multibanco gerada e paga no sandbox também não.
6. SEO. Mapa de 301, canónicas, JSON-LD de produto a partir dos mesmos campos que a página, sitemap de URLs Astro. Inspecione um URL de produto antes do corte. Não invente lastmod em 10 000 SKU.
7. Corte o DNS do catálogo. Deixe wp-admin e checkout no origin. Veja os webhooks de stock durante uma semana.

O blue-green do catálogo é fácil (são ficheiros). O blue-green do checkout é o de hoje: já tem um. Não invente um segundo.

A semana do corte é sobretudo DNS e 301, não React. Deixe uma janela curta em que o tema velho ainda responde a um bypass de cabeçalho para comparar uma referência. No momento em que as duas montras adicionam ao carrinho contra a mesma Store API, vai duplicar linhas a partir de separadores velhos. Drene o tema antigo: 301, depois 410 nos assets do tema, depois apague. Dual-run “por precaução” é assim que o personalizador volta.

Mapeie também os feeds. Google Merchant, catálogo Meta, o XML que o ERP come: se liam permalinks do tema, agora leem permalinks do Astro, ou um 301. Um feed que continua a apontar para uma ficha do tema morto com ?add-to-cart= é tráfego que não converte.

Os cupões de campanha que o marketing tinha em landings Elementor há que recriá-los como URLs Astro ou deixar essas landings no WordPress. Não os perca no corte porque “não eram catálogo”. Eram aquisição.

Confirme no staging o NIF, a referência Multibanco e o ponto CTT numa encomenda real de teste. Se estes três passam, o corte de sistemas está a honrar o origin. Se falham, o catálogo rápido não importa.

#Auditoria e leitura

LCP de campo, camadas de cache e peso do payload da Store API: guia de desempenho. O corte de sistemas: esta página. O pillar de programador WooCommerce é o trabalho comercial de catálogo. Programador Astro é o front. A integração ERP é o que não pode partir quando o tema morre. A arquitetura headless é o mesmo corte sem carrinho.

O Handbook do WooCommerce (Store API, checkout blocks) e o canal #woocommerce do Make WordPress Slack são as referências de contrato, não um curso genérico de “headless commerce”. IfthenPay e EuPago publicam a documentação de callback no painel de comerciante; leia-a antes de pintar um botão MB Way no front. Moloni e InvoiceXpress documentam os ganchos de encomenda que a fatura espera. Confirme esses ganchos no staging, não no dia do corte.

#Conclusão

WooCommerce como loja. Astro 7 como catálogo. Carrinho como ilha sobre Store API. Checkout em PHP. Os plugins que pintavam o tema reconstroem-se ou deitam-se fora. Os plugins que levavam o negócio ficam. GraphQL constrói páginas. GraphQL não segura o cesto. Em Portugal, MB Way, Multibanco e a fatura no PHP são o argumento mais curto para não tirar o checkout do origin.

Escreva com a lista de plugins e com se o checkout pode ficar no WooCommerce. Se a resposta é “tem de parecer idêntico ao checkout de uma página do tema”, está a comprar um redesign. A superfície de programador WooCommerce é onde esse alcance começa. O front, quando o alcance é catálogo, está em programador Astro.

A ficha rápida, o carrinho pequeno, a cobrança aborrecida. Esse é o corte que aguenta uma Black Friday no continente. O resto é teatro de arquitetura. Se o tema já entrega HTML de ficha num tempo que a Portent não castigaria, não desacople para uma captura. Desacople quando o PHP da ficha é o teto e o checkout, de facto, pode ficar onde está.

A pré-visualização editorial e a biblioteca de média continuam no WordPress. O Astro consome. Se preview significa o personalizador, o corte não acabou. Se as imagens passam por um segundo DAM “porque headless”, inventou um problema que a integração ERP não pediu. Uma origem de produto, uma origem de encomenda, uma origem de fatura. O HTML da ficha é o único sítio onde o Astro é dono.