API Headless: O que é? MACH, Comércio Composable e a Camada de Contrato

Se você já comprou em uma loja virtual personalizada que não parecia um tema padrão, provavelmente havia uma API de comércio headless por trás. Uma API de comércio headless é o contrato que um backend de comércio expõe para que qualquer frontend consiga ler produtos, montar carrinhos e criar pedidos sem depender de um tema acoplado. Na prática, ela define como sua loja, app mobile, parceiros e integrações acessam catálogo, preços, estoque e checkout. Este guia mostra como isso funciona, como se relaciona com comércio composable e MACH, e por que esse contrato de API precisa ser tratado como produto, seguindo a ideia de que o software está se tornando headless e sua API agora é o produto.

Experimente o Apidog hoje

O que “headless” significa no comércio

Em uma plataforma de comércio tradicional, catálogo, carrinho, checkout e renderização HTML vivem no mesmo sistema. Você escolhe um tema, customiza páginas e publica a loja.

No comércio headless, isso é separado:

• Backend de comércio: mantém produtos, variantes, preços, estoque, carrinho, descontos e pedidos.
• Frontend: renderiza a experiência da loja em React, Vue, mobile nativo, quiosque, assistente de voz ou qualquer outro canal.
• API: conecta os dois lados.

A “cabeça” é a camada de apresentação. Tornar o comércio headless significa remover essa cabeça fixa e expor a lógica de comércio por API.

Um fluxo típico fica assim:

Frontend da loja
  -> GET /products
  -> POST /cart/items
  -> POST /checkout
Backend de comércio
  -> catálogo
  -> preços
  -> estoque
  -> pedidos

Esse desacoplamento dá liberdade para o time de frontend escolher framework, arquitetura de renderização e ciclo de deploy. O backend continua responsável pelas regras de comércio. A API é a fronteira entre os times.

A troca é clara: você ganha flexibilidade, mas assume mais trabalho de engenharia. Uma plataforma tradicional entrega uma loja pronta para uso. No headless, você constrói, hospeda, testa e mantém a experiência de frontend.

Use headless quando:

• um tema padrão não atende à experiência desejada;
• você precisa publicar em vários canais a partir do mesmo backend;
• times de frontend e backend precisam evoluir de forma independente;
• parceiros ou apps externos precisam consumir a mesma lógica de comércio.

Headless vs. composable vs. MACH

Esses termos aparecem juntos, mas não significam a mesma coisa.

Termo	O que descreve	Escopo
Comércio headless	Frontend desacoplado de um backend de comércio, conectado por API	Um backend, uma ou muitas interfaces
Comércio composable	Stack dividido em serviços intercambiáveis “best-of-breed”, como catálogo, busca, pagamentos, PIM e OMS	Muitos serviços independentes montados juntos
MACH	Princípios arquitetônicos usados em stacks composable	Uma filosofia, não um produto

Headless é o caso mais restrito. Você pode ter uma arquitetura headless mesmo com um backend monolítico, desde que a loja se comunique com ele por API.

Composable vai além. Em vez de um único backend, você combina vários serviços especializados:

Frontend
  -> API de catálogo
  -> API de busca
  -> API de pagamento
  -> API de estoque
  -> API de OMS

MACH é o conjunto de princípios por trás de muitos stacks composable. De acordo com a MACH Alliance, formada em 2020, MACH significa:

• Microserviços
• API-first
• SaaS nativo da nuvem
• Headless

O ponto central para desenvolvedores é o “API-first”. Em uma arquitetura MACH, a API não é um detalhe interno. Ela é o principal meio de comunicação entre serviços, canais e parceiros. É o mesmo raciocínio por trás de tratar sua API como um produto.

O que uma API de comércio headless expõe

A implementação muda entre plataformas, mas a maioria das APIs de comércio headless cobre estes domínios:

• Catálogo e produtos: produtos, variantes, coleções, categorias, descrições, imagens e mídia.
• Busca e navegação: consulta, filtros, ordenação e paginação.
• Carrinho e checkout: criar carrinho, adicionar/remover itens, aplicar cupons, calcular totais e avançar para pagamento.
• Clientes: login, contas, endereços e histórico de pedidos.
• Estoque e preços: disponibilidade, preço por região, moeda, canal ou segmento.
• Pedidos: criação, consulta de status e integração com fulfillment.

Um exemplo simples de endpoint REST para página de produto:

GET /storefront/products/sku-123
Accept: application/json

Resposta esperada:

{
  "id": "prod_123",
  "sku": "sku-123",
  "name": "Tênis Runner",
  "description": "Tênis para corrida urbana",
  "price": {
    "amount": 29990,
    "currency": "BRL"
  },
  "inventory": {
    "available": true,
    "quantity": 12
  },
  "images": [
    {
      "url": "https://cdn.example.com/products/sku-123.png",
      "alt": "Tênis Runner"
    }
  ]
}

Em GraphQL, a mesma tela poderia solicitar apenas os campos necessários:

query ProductPage($slug: String!) {
  product(slug: $slug) {
    id
    name
    description
    price {
      amount
      currency
    }
    variants {
      id
      sku
      available
    }
    images {
      url
      alt
    }
  }
}

Muitas plataformas separam as APIs em dois grupos:

• Storefront API: voltada para o cliente final, otimizada para leitura e interações da loja.
• Admin API: usada para back-office, edição de catálogo, pedidos, regras de preço e configuração.

O protocolo também importa. GraphQL é comum porque permite buscar exatamente os campos necessários em uma chamada. REST continua sendo uma boa escolha quando você quer endpoints previsíveis, cache simples e semântica HTTP direta. Para comparar os dois modelos, veja REST vs. GraphQL.

Principais plataformas de comércio headless

O mercado se divide entre motores SaaS e motores de código aberto. Alguns nomes comuns:

• 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 com a Storefront API e o framework React Hydrogen. Se você já usa Shopify, este tutorial da API Shopify é um bom ponto de partida.
• BigCommerce: suporta headless com APIs GraphQL Storefront e Checkout, além de APIs de catálogo. Veja o guia sobre como usar as APIs do BigCommerce.
• Saleor: motor open source, GraphQL-first, construído em Python e Django.
• Medusa: motor open source construído em Node.js e TypeScript, comum entre equipes JavaScript que querem controle maior do backend.

Antes de escolher, valide:

• cobertura da API para catálogo, carrinho, checkout e pedidos;
• limites de uso e custos;
• modelo de hospedagem;
• suporte a webhooks;
• estratégia de versionamento;
• documentação e SDKs;
• maturidade dos recursos de teste e sandbox.

O padrão é o mesmo em todas: o motor expõe lógica de comércio por API, e você constrói a interface.

Como modelar uma API de comércio headless

Antes de implementar endpoints, defina o contrato. Um contrato mínimo de loja virtual geralmente precisa responder a estas perguntas:

1. Como listar produtos?
2. Como buscar um produto por slug ou SKU?
3. Como criar um carrinho?
4. Como adicionar, atualizar e remover itens?
5. Como calcular frete, descontos e impostos?
6. Como iniciar o checkout?
7. Como consultar o pedido criado?

Um exemplo inicial de contrato OpenAPI para produto:

openapi: 3.0.3
info:
  title: Storefront Commerce API
  version: 1.0.0

paths:
  /products/{slug}:
    get:
      summary: Retorna os dados de um produto para a loja
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Produto encontrado
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Product"

components:
  schemas:
    Product:
      type: object
      required:
        - id
        - slug
        - name
        - price
      properties:
        id:
          type: string
          example: prod_123
        slug:
          type: string
          example: tenis-runner
        name:
          type: string
          example: Tênis Runner
        price:
          type: object
          required:
            - amount
            - currency
          properties:
            amount:
              type: integer
              example: 29990
            currency:
              type: string
              example: BRL

Esse contrato permite que frontend, backend e QA trabalhem com a mesma definição antes da implementação final.

Por que as equipes dependem do contrato da API

Quando a loja é desacoplada, a API deixa de ser “encanamento” e passa a ser o acordo que todos seguem.

O time de frontend não consegue implementar uma página de produto sem saber:

• quais campos existem;
• quais campos são obrigatórios;
• como erros são retornados;
• como paginação funciona;
• como preços e estoque são representados;
• quais mudanças podem quebrar consumidores existentes.

Parceiros também dependem disso. Um app de fidelidade, um serviço de impostos, um feed de marketplace e um app mobile podem consumir os mesmos endpoints. Se a resposta muda sem aviso, vários consumidores podem quebrar ao mesmo tempo.

Por isso, trate o contrato como produto:

• prefira mudanças aditivas;
• evite renomear campos sem versionamento;
• documente campos obrigatórios e opcionais;
• defina códigos de erro padronizados;
• use ambientes de sandbox;
• execute testes de contrato antes do deploy.

Um exemplo de mudança segura:

{
  "id": "prod_123",
  "name": "Tênis Runner",
  "price": {
    "amount": 29990,
    "currency": "BRL"
  },
  "rating": 4.8
}

Adicionar rating tende a ser seguro porque consumidores antigos podem ignorar o campo.

Uma mudança arriscada:

{
  "id": "prod_123",
- "name": "Tênis Runner"
+ "title": "Tênis Runner"
}

Renomear name para title quebra qualquer frontend que leia name.

Onde o Apidog se encaixa

O Apidog não é motor de comércio, CMS, gateway de pagamento ou plataforma headless. Ele atua na camada API-first: onde você projeta, testa, simula e documenta o contrato do qual a arquitetura headless depende.

Em um projeto de comércio headless, você pode usar o Apidog para:

• Projetar o contrato primeiro: modele a Storefront API ou Admin API como OpenAPI no Apidog antes de escrever o backend.
• Simular endpoints: gere um servidor mock para que o frontend consuma respostas realistas de produtos, carrinhos e checkout enquanto o backend ainda está em construção. Veja o explicador sobre API de simulação.
• Testar na CI: execute testes de API sem interface gráfica com o Apidog CLI em pipelines automatizados.
• Documentar para times e parceiros: publique documentação interativa como fonte única de verdade para quem consome a API.

Um fluxo prático:

1. Defina o contrato OpenAPI
2. Revise campos com frontend, backend e QA
3. Gere mocks para o frontend
4. Implemente o backend contra o contrato
5. Execute testes de contrato na CI
6. Publique documentação para parceiros

Para entender por que isso importa quando a API se torna a interface principal, leia o software está se tornando headless e sua API agora é o produto. Se quiser testar o fluxo, baixe o Apidog e importe uma especificação existente.

Perguntas frequentes

Comércio headless é o mesmo que comércio composable?

Não. Comércio headless desacopla a loja virtual de um backend de comércio por API. Comércio composable combina vários serviços independentes “best-of-breed”, cada um com sua própria API, em uma única experiência. Um stack composable normalmente é headless, mas uma arquitetura 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 buscar exatamente os campos necessários em uma chamada, o que ajuda em páginas de produto, listagens e carrinhos. Mas REST também é muito usado. O protocolo importa menos do que ter um contrato estável, testado e bem documentado.

Posso testar uma API de comércio headless antes que o backend esteja pronto?

Sim. Se você modelar o contrato como uma especificação, pode gerar um servidor de simulação com respostas realistas. O frontend desenvolve contra o mock e depois troca para os endpoints reais quando o backend estiver disponível.

O que é a MACH Alliance?

A MACH Alliance é um grupo da indústria formado em 2020 para promover stacks abertos e “best-of-breed” baseados em 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 produto único.

O contrato é a loja

O comércio headless transfere parte importante do valor do tema para a API. Depois que a loja é desacoplada, a API de comércio é o que frontend, mobile, parceiros e integrações realmente usam para construir experiências.

Composable e MACH levam essa ideia adiante ao tornar API-first um princípio central da arquitetura. Isso não depende de uma ferramenta específica, mas a qualidade do contrato melhora quando existe um lugar para projetar, simular, testar e documentar a API.

Se seu projeto está indo nessa direção, o Apidog pode ajudar nessa camada sem tentar substituir o motor de comércio por baixo.