Shopify headless com Next.js: coleções, produtos, carrinho e encomendas através da API

Os temas Shopify servem a grande maioria das lojas. Mas algumas marcas esbarram nos seus limites: um design muito específico, um desempenho a levar ao máximo, uma loja que tem de coexistir com um site de conteúdos, um configurador ou uma área de cliente à medida. A solução chama-se Shopify headless: mantém-se a Shopify para tudo o que faz muito bem e constrói-se a montra com um framework moderno como o Next.js. Eis como funciona, em concreto.

Headless, o que é?

Uma loja Shopify clássica é um back-office (produtos, stocks, encomendas, clientes) e uma «cabeça»: o tema que mostra a loja. Em headless, retira-se essa cabeça. A Shopify torna-se um motor de e-commerce acessível por API, e o site visível pelos clientes é uma aplicação independente, desenvolvida à medida e alojada separadamente.

• A Shopify gere: o catálogo, as variantes, os stocks, os preços e moedas, as promoções, o pagamento, as encomendas, os envios, o back-office.
• O Next.js gere: a apresentação das páginas, a navegação, o design, o conteúdo editorial, o desempenho e o SEO.
• A API faz a ligação: a Storefront API da Shopify, em GraphQL, fornece os dados dos produtos e gere o carrinho.

A arquitetura tipo

1. O Next.js gera as páginas de coleções e de produtos de forma estática, a partir dos dados da Storefront API.
2. Um CMS (por exemplo Payload, Sanity ou os metacampos da Shopify) gere os conteúdos editoriais: página inicial, lookbooks, blog. Veja o nosso artigo sobre os CMS headless.
3. O carrinho é criado e atualizado através da Cart API da Shopify, a partir do navegador ou do servidor.
4. O pagamento faz-se no checkout Shopify, seguro e otimizado, ou através de uma encomenda criada pela Admin API em certos casos.
5. Webhooks da Shopify avisam o site quando um produto, um preço ou um stock muda, para regenerar apenas as páginas em causa.

Mostrar as coleções e os produtos

A Storefront API consulta-se em GraphQL com um token de acesso público, criado a partir do canal «Headless» da Shopify. Pedem-se exatamente os campos de que se precisa, nada mais. Exemplo para uma página de coleção:

query Collection($handle: String!) {
  collection(handle: $handle) {
    title
    description
    seo { title description }
    products(first: 24) {
      nodes {
        handle
        title
        featuredImage { url altText width height }
        priceRange {
          minVariantPrice { amount currencyCode }
        }
      }
    }
  }
}

Do lado do Next.js, a chamada faz-se a partir de um componente de servidor. Os dados ficam em cache e associados a uma etiqueta, o que permite regenerar as páginas a pedido quando a Shopify assinala uma alteração:

export async function shopifyFetch(query, variables, tags = []) {
  const res = await fetch(process.env.SHOPIFY_STOREFRONT_URL, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Shopify-Storefront-Access-Token': process.env.SHOPIFY_STOREFRONT_TOKEN,
    },
    body: JSON.stringify({ query, variables }),
    next: { tags },
  });

  const { data, errors } = await res.json();
  if (errors) throw new Error(errors[0].message);
  return data;
}

As páginas de produto seguem o mesmo princípio: título, descrição, imagens, variantes (tamanho, cor) com a sua disponibilidade, metacampos para as informações complementares (composição, guia de tamanhos, conselhos de manutenção). A filtragem e a ordenação das coleções também estão disponíveis na API.

Gerir o carrinho

O carrinho é gerido pela Shopify, não pelo seu site: é isso que garante preços, promoções e stocks sempre certos. Cria-se um carrinho na primeira adição, guarda-se o seu identificador num cookie e depois acrescentam-se, alteram-se ou removem-se linhas.

mutation CreateCart($lines: [CartLineInput!]!) {
  cartCreate(input: { lines: $lines }) {
    cart {
      id
      checkoutUrl
      totalQuantity
      cost {
        totalAmount { amount currencyCode }
      }
    }
    userErrors { field message }
  }
}

As mutações cartLinesAdd, cartLinesUpdate e cartLinesRemove tratam do resto. Os códigos promocionais, as notas de encomenda e os atributos personalizados (gravação, mensagem de oferta) também passam pelo carrinho. Com as Server Actions do Next.js, estas chamadas ficam do lado do servidor e o token nunca é exposto desnecessariamente.

Criar a encomenda

A via padrão: o checkout Shopify

Cada carrinho tem um endereço checkoutUrl. No momento de pagar, o cliente é redirecionado para o checkout Shopify, que gere moradas, portes, impostos, pagamento (Shop Pay, Apple Pay, cartões), deteção de fraude e criação da encomenda. É a solução que recomendamos na maioria dos casos: o checkout Shopify é um dos mais eficazes do mercado, e não tem de gerir dados bancários. Personaliza-se com as cores da sua marca.

A criação de encomendas pela Admin API

Em certos casos, a encomenda tem de ser criada diretamente pela API, do lado do servidor, com a Admin API da Shopify:

• Encomendas profissionais: um revendedor faz uma encomenda no seu portal, e a encomenda é criada com as suas condições (preços dedicados, pagamento a 30 dias) através de uma encomenda em rascunho, depois finalizada. Veja o nosso artigo sobre o portal B2B Shopify.
• Pagamento gerido noutro lado: marketplace, orçamento assinado, pagamento contra fatura ou por um prestador externo. A encomenda é então registada na Shopify para centralizar stocks, envios e contabilidade.
• Orçamentos: uma encomenda em rascunho é preparada pela sua equipa e depois enviada ao cliente com um link de pagamento.

Contas de cliente, mercados e línguas

A Customer Account API permite mostrar o histórico de encomendas e as moradas do cliente na sua própria interface. O Shopify Markets continua utilizável: a diretiva @inContext da Storefront API devolve os preços na moeda e na língua do país visado. Para o SEO internacional, as etiquetas hreflang têm de ser geradas do lado do Next.js, como explicado no nosso artigo sobre os sites multilingues.

O SEO: uma vantagem, e uma responsabilidade

Uma loja headless bem feita é extremamente rápida: páginas estáticas servidas a partir de uma CDN, imagens otimizadas, quase nenhum JavaScript inútil, nenhuma aplicação a injetar os seus scripts por todo o lado. É um trunfo importante para os Core Web Vitals e para a conversão. Mas tudo o que o tema Shopify fazia automaticamente passa a ser da sua responsabilidade:

• a renderização das páginas de produto no servidor ou em estático (veja SSR, SSG ou CSR);
• o sitemap, as etiquetas canónicas e as etiquetas title e description;
• os dados estruturados Product, com preço e disponibilidade;
• os redirecionamentos, nomeadamente se migrar a partir de um tema Shopify existente;
• a gestão dos produtos esgotados ou eliminados.

Vantagens e limites

As vantagens

• Uma liberdade total de design e de experiência, sem as restrições do tema.
• Um desempenho de primeira linha, mesmo com um catálogo importante.
• Um único site para o conteúdo e a loja, com uma única identidade.
• A possibilidade de ligar outras fontes: CMS, configurador, PIM, ERP, CRM.

Os limites

• Um custo de desenvolvimento claramente mais elevado do que um tema.
• Uma parte das aplicações Shopify não funciona sem tema (widgets de avaliações, upsells, programas de fidelização): é preciso usar a sua API ou substituí-las.
• Uma manutenção técnica a prever, como para qualquer site à medida. Veja o nosso artigo sobre a manutenção de um site.
• A sua equipa mantém o back-office Shopify, mas já não pode alterar a paginação com o editor de temas: é o CMS que assume esse papel.

Next.js ou Hydrogen?

A Shopify propõe o seu próprio framework headless, o Hydrogen, com um alojamento integrado, o Oxygen. É uma excelente opção se a loja for o coração do projeto. O Next.js é mais pertinente quando o site mistura muito conteúdo, outras fontes de dados ou funcionalidades de negócio, e quando a sua equipa ou a sua agência já trabalha com ele. Em ambos os casos, a Storefront API é a mesma.

Para quem?

O headless não é para uma loja que está a começar: um bom tema Shopify bem otimizado continua a ser mais rentável, como explicamos no nosso guia para criar uma loja Shopify. Torna-se interessante para as marcas estabelecidas que querem uma experiência distintiva, as lojas para as quais o desempenho é um desafio forte e os projetos que combinam e-commerce, conteúdo e ferramentas de gestão.

É exatamente o tipo de projeto de que gostamos. A nossa agência Shopify em Marselha desenvolve lojas headless em Next.js, e as nossas integrações API ligam a Shopify às suas outras ferramentas. Falemos do seu projeto: dir-lhe-emos com franqueza se o headless é a escolha certa para si.