WooCommerce Headless API (headless-woocommerce-api)

Headless WooCommerce API (headless-woocommerce-api)

Guia de orquestração para configurar, consultar e proteger APIs back-end WooCommerce (WPGraphQL e REST) para alimentar aplicações frontend desacopladas (Next.js, Remix, mobile).

---

Pré-requisitos e Pré-condições

• WordPress instalado com o plugin WooCommerce ativo.
• Endpoint GraphQL acessível (padrão: https://your-store.com/graphql).
• Para consultas aprofundadas e exemplos técnicos, veja headless-api-reference.md.
• Para configuração do cliente frontend, inspecione storefront-client.ts.

---

Lista de Verificação Passo a Passo

flowchart TD
    S1["1. Instalar WPGraphQL & WooGraphQL"] --> S2["2. Semear Catálogo de Dados Simulados / Reais"]
    S2 --> S3["3. Configurar Autenticação (JWT / OAuth)"]
    S3 --> S4["4. Verificar Schema com GraphiQL"]
    S4 --> S5["5. Conectar Consultas de Cliente no Next.js"]

Estágio 1: Implantação de Plugins Back-end

• Instalar WPGraphQL Core:
  • Instale e ative wp-graphql a partir do diretório de plugins do WordPress.
  • Verifique se o endpoint está ativo: GET/POST /graphql.
• Instalar Extensão WooGraphQL:
  • Baixe e instale wp-graphql-woocommerce.
  • Valida que os tipos (Product, ProductCategory, Cart, Customer) aparecem no schema GraphQL.
• Semear Dados de Teste:
  • Execute o importador CSV via Ferramentas → Importar → Produtos WooCommerce (CSV) usando sample-data/sample_products.csv.

Estágio 2: Configurar Autenticação Headless

• Opção A: JWT Auth (wp-graphql-jwt-authentication):
  • Faça upload e ative wp-graphql-jwt-authentication.
  • Gere um segredo de 64 caracteres (openssl rand -base64 48 | tr -dc 'A-Za-z0-9_#%+=@!' | head -c 64 ou equivalente no PowerShell).
  • Injete no contêiner (docker exec -it <container> sed -i ... /var/www/html/wp-config.php), adicione ao .env (GRAPHQL_JWT_AUTH_SECRET_KEY), ou adicione diretamente ao wp-config.php:

    define( 'GRAPHQL_JWT_AUTH_SECRET_KEY', 'seu-segredo-forte-aleatorio' );
    

• Opção B: Headless Login (wp-graphql-headless-login):
  • Use se for necessário OAuth 2.0 externo / login social (Google, GitHub).
  • Configure provedores via filtro ou configurações administrativas.

Estágio 3: Consultar Dados da Loja

• Catálogo Público: Consulte categorias e produtos usando fragments de união (... on SimpleProduct, ... on VariableProduct).
• Sessão do Cliente: Capture o cabeçalho woocommerce-session em mutações de carrinho e passe-o em requisições subsequentes.
• Perfil Protegido: Passe Authorization: Bearer <authToken> para atualizações de pedidos e endereços do cliente.

Estágio 4: Integração Frontend (Next.js)

• Implemente SSG/ISR para páginas de produtos estáticas usando consultas GraphQL públicas.
• Mantenha tokens de carrinho no estado do lado do cliente (Zustand / LocalStorage) para manter as páginas Next.js cacheáveis.
• Implemente Ponte de Checkout Nativo: redirecione para /checkout do WordPress para utilizar gateways de pagamento locais e conformidade com e-Namad.

---

Casos Limite & Armadilhas Conhecidas de IA

1. Uniões em Consultas de Produto: Produtos WooCommerce são polimórficos. Nunca consulte price diretamente em products { nodes { price } }; você deve usar condições de tipo (... on SimpleProduct { price }, ... on VariableProduct { price }).
2. Cabeçalho de Sessão Ausente: Itens do carrinho desaparecerão na próxima requisição se o token woocommerce-session retornado pelo servidor não for armazenado e reenviado pelo cliente frontend.
3. Incompatibilidade com React do Admin: Evite plugins com bundles Gutenberg antigos (como painéis de configuração de wp-graphql-headless-login) se estiver usando WordPress core estrito sem etapas de construção personalizadas; opte por plugins baseados em constantes como wp-graphql-jwt-authentication.
4. Cabeçalhos CORS: Certifique-se de que o WordPress permite requisições da sua origem frontend configurando cabeçalhos ou proxy reverso.

---

Verificação & Autoavaliação

• Execute uma consulta de teste contra /graphql confirmando que productCategories e products retornam nós.
• Execute a mutação login confirmando que um authToken válido é gerado.
• Confirme que o cabeçalho woocommerce-session é retornado ao adicionar um item ao carrinho.