Se você já comprou em uma loja virtual personalizada que não parecia um modelo padrão, é bem provável que uma API de comércio headless estivesse fazendo o trabalho por trás dela. Uma API de comércio headless é a interface que um backend de comércio expõe para que qualquer loja virtual possa ler produtos, montar carrinhos e fazer pedidos sem estar vinculada a um tema embutido. Este artigo explica o que isso significa, como se relaciona com comércio composable e MACH, e por que suas equipes de loja virtual e parceiros dependem desse contrato de API. Ele se baseia na ideia de que o software está se tornando headless e sua API agora é o produto.
O que “headless” significa no comércio
As plataformas de comércio tradicionais vêm como uma peça única. O catálogo de produtos, o carrinho, o checkout e as páginas HTML que os renderizam vivem todos no mesmo sistema. Você o tematiza, o ajusta e o coloca em produção.
O comércio headless divide isso em dois. O backend, frequentemente chamado de motor de comércio, mantém o catálogo, preços, estoque, carrinho e lógica de pedidos. O frontend, sua loja virtual, torna-se um aplicativo separado que você constrói como quiser. A única coisa que os conecta é uma API.
Assim, a “cabeça” é a camada de apresentação. Tornar-se headless significa remover a cabeça fixa e expor o corpo, a lógica de comércio, através de uma API. Um site React, um aplicativo móvel nativo, a tela de uma geladeira inteligente ou um assistente de voz podem se comunicar com o mesmo backend porque todos falam a mesma API.
Esse desacoplamento é o objetivo principal. Sua equipe de frontend escolhe seu próprio framework e entrega em sua própria programação. A equipe de backend é responsável pelas regras de comércio. A API é a linha entre eles.
A desvantagem é que você assume mais trabalho. Uma plataforma tradicional entrega uma loja funcionando pronta para uso. O comércio headless significa que você constrói e hospeda a loja virtual, então a flexibilidade vem com um custo de engenharia. As equipes escolhem o headless quando um tema padrão não pode fornecer a experiência de que precisam, ou quando querem atender vários canais a partir de um único backend.
Headless vs. composable vs. MACH
Esses três termos são usados de forma intercambiável, mas descrevem escopos diferentes. Aqui está a explicação honesta.
| Termo | O que descreve | Escopo |
|---|---|---|
| Comércio Headless | Frontend desacoplado de um único backend de comércio, conectado por uma API | Um backend, uma ou muitas interfaces |
| Comércio Composable | Todo o stack dividido em serviços intercambiáveis "best-of-breed" (catálogo, busca, pagamentos, PIM, OMS) | Muitos serviços independentes montados juntos |
| MACH | Um conjunto de princípios arquitetônicos que os stacks composable tendem a seguir | Uma filosofia, não um produto |
Headless é o caso restrito. Você pode ser headless com um backend monolítico, desde que a loja virtual se comunique com ele por uma API.
O comércio composable vai além. Em vez de um único backend, você monta serviços independentes e escolhe a melhor ferramenta para cada tarefa. Busca de um fornecedor, pagamentos de outro, um gerenciador de informações de produto separado. Cada um é seu próprio serviço com sua própria API, e você os compõe em uma única experiência.
MACH é o conjunto de princípios por trás da maioria dos stacks composable. De acordo com a MACH Alliance, um grupo da indústria formado em 2020, MACH significa Microserviços, API-first (API em primeiro lugar), SaaS nativo da Nuvem e Headless. Observe que "API-first" está bem no centro. Em um mundo MACH, a API não é um recurso secundário. É a única maneira pela qual as peças se comunicam, o que é o mesmo raciocínio por trás de tratar sua API como um produto.
O que uma API de comércio headless realmente expõe
A forma exata varia de plataforma para plataforma, mas a maioria das APIs de comércio headless cobrem as mesmas tarefas centrais:
- Catálogo e produtos. Ler produtos, variantes, coleções e mídias para que a loja virtual possa renderizar listagens e páginas de detalhes.
- Busca e navegação. Consultar, filtrar e classificar o catálogo.
- Carrinho e checkout. Criar um carrinho, adicionar e remover itens, aplicar descontos e prosseguir para o pagamento.
- Clientes. Fazer login, gerenciar contas e rastrear histórico de pedidos.
- Estoque e preços. Exibir níveis de estoque e o preço correto para o contexto certo.
Algumas plataformas dividem isso em uma API de loja virtual voltada para o público e uma API de administração separada para o trabalho de back-office. A API da loja virtual é intensiva em leitura e voltada para o cliente. A API de administração lida com edições de catálogo, gerenciamento de pedidos e configuração.
O protocolo também importa. Muitas APIs de comércio headless são GraphQL, o que permite que a loja virtual solicite exatamente os campos de que precisa em uma única viagem. Outras são REST, e algumas plataformas oferecem ambas. Se você estiver avaliando as vantagens e desvantagens, veja REST vs. GraphQL.
As principais plataformas
O espaço do comércio headless se divide aproximadamente em motores SaaS e motores de código aberto. Alguns nomes que você encontrará:
- commercetools. Membro fundador da MACH Alliance e uma das plataformas de comércio composable mais citadas. API-first e nativa da nuvem por design.
- Shopify. Oferece construções headless através de sua API Storefront, com Hydrogen como um framework React para consumi-la. Se você já está no mundo Shopify, nosso tutorial da API Shopify é um bom ponto de partida.
- BigCommerce. Suporta o modo headless com APIs GraphQL Storefront e Checkout além de seu catálogo. Veja nosso guia sobre como usar as APIs do BigCommerce.
- Saleor. Um motor de código aberto, GraphQL-first construído em Python e Django.
- Medusa. Um motor de código aberto construído em Node.js e TypeScript, popular entre equipes JavaScript que desejam controle total do backend.
Verifique as especificidades da plataforma antes de se comprometer, pois os preços, modelos de hospedagem e cobertura da API mudam. O padrão em todas elas é o mesmo: o motor expõe a lógica de comércio através de uma API, e você constrói a interface.
Por que as equipes dependem do contrato da API de comércio
Uma vez que a loja virtual é desacoplada, a API deixa de ser um mero encanamento e se torna o acordo com o qual todos constroem. É aqui que o headless se torna real.
Sua equipe de frontend não pode lançar uma página de produto até que saiba a forma exata de uma resposta de produto. Suas integrações de parceiros, um aplicativo de fidelidade, um serviço de impostos, um feed de marketplace, todos se conectam aos mesmos endpoints. Uma equipe móvel consome o mesmo contrato que a equipe web. Se a forma da resposta mudar sem aviso, cada um desses consumidores pode quebrar de uma só vez.
Esse é o risco e a oportunidade. Um contrato de API de comércio claro, estável e bem documentado permite que equipes independentes se movam rapidamente sem pisar umas nas outras. Um contrato vago ou instável transforma cada lançamento em uma corrida de coordenação. O contrato é o produto, por isso merece o mesmo cuidado que a própria loja virtual, incluindo testes de contrato para capturar alterações disruptivas antes que sejam lançadas.
O versionamento também faz parte do acordo. Quando você precisa alterar uma resposta de produto ou renomear um campo, não pode simplesmente editar o endpoint e esperar. Consumidores que você não controla estão lendo-o. Então, as equipes headless tratam o contrato como um compromisso público: mudanças aditivas sempre que possível, janelas claras de descontinuação e testes que sinalizam qualquer coisa que possa quebrar antes que chegue à integração de um parceiro.
Onde o Apidog se encaixa
O Apidog não gerencia sua loja. Não é um motor de comércio, um CMS ou um gateway, e não torna seu stack headless ou composable. O que ele faz é possuir o pilar API-first de tudo isso: a camada onde você projeta, testa, simula e documenta o contrato do qual tudo o mais depende.
Isso se alinha perfeitamente com o trabalho de comércio headless:
- Projete o contrato primeiro. Modele a API da loja virtual ou de administração como uma especificação OpenAPI no Apidog antes que o código exista, para que frontend e backend concordem sobre a forma desde o início.
- Simule antes que o backend esteja pronto. Crie um servidor de simulação a partir da especificação para que sua equipe de loja virtual construa e teste com respostas realistas de produtos e carrinhos enquanto o motor de comércio ainda está sendo configurado. Essa é a promessa de desacoplamento tornada prática, e você pode ler mais em nosso explicador de API de simulação.
- Teste o contrato na CI. O Apidog CLI executa seus testes de API sem GUI, com execução de teste headless que se encaixa em um pipeline. É uma verdadeira rima conceitual com o comércio headless: sem frontend necessário, apenas o contrato sendo verificado.
- Documente para parceiros. Documentos interativos gerados automaticamente fornecem às suas equipes de loja virtual e parceiros uma única fonte de verdade para a API com a qual estão se integrando.
Para uma análise mais aprofundada de por que isso importa uma vez que a API se torna a única interface, veja o software está se tornando headless e sua API agora é o produto. Se você quiser experimentar o fluxo de trabalho, baixe o Apidog e importe uma especificação existente.
Perguntas Frequentes
O comércio headless é o mesmo que comércio composable?
Não. O comércio headless desacopla a loja virtual de um backend de comércio por meio de uma API. O comércio composable vai além e reúne muitos serviços independentes "best-of-breed", cada um com sua própria API, em uma única experiência. Todo stack composable é headless, mas uma configuração headless com um único backend monolítico não é necessariamente composable.
Preciso de GraphQL para uma API de comércio headless?
Não. GraphQL é comum porque permite que a loja virtual solicite exatamente os campos de que precisa em uma única chamada, o que é adequado para a renderização de produtos e carrinhos. Mas muitas APIs de comércio headless usam REST, e algumas plataformas oferecem ambos. O protocolo importa menos do que o contrato ser estável e documentado.
Posso testar uma API de comércio headless antes que o backend seja construído?
Sim, e essa é uma das principais razões para adotar uma abordagem design-first. Se você modelar o contrato da API como uma especificação, pode gerar um servidor de simulação que retorna respostas realistas. Sua equipe de loja virtual constrói e testa contra a simulação enquanto o motor de comércio ainda está em andamento, e depois troca para os endpoints reais.
O que é a MACH Alliance?
A MACH Alliance é um grupo da indústria formado em 2020 para promover stacks de tecnologia abertos e "best-of-breed" construídos sobre os princípios de Microserviços, API-first, SaaS nativo da Nuvem e Headless. Fornecedores como commercetools são membros fundadores. MACH é um conjunto de princípios arquitetônicos, não um único produto que você compra.
O contrato é a loja
O comércio headless transfere o valor do tema para a API. Uma vez que a loja virtual é desacoplada, a API de comércio é o que suas equipes de frontend, mobile e parceiros realmente usam para construir. O comércio composable e o MACH levam isso adiante, tornando o "API-first" um princípio central, em vez de um recurso agradável de se ter.
Nada disso depende do Apidog, mas a qualidade do contrato se beneficia de um local para projetá-lo, simulá-lo, testá-lo e documentá-lo. Se é para onde seu projeto headless está indo, o Apidog oferece essa camada sem pretender ser o motor de comércio por baixo.