Headless WooCommerce API

Headless WooCommerce API (headless-woocommerce-api)

Orchestrierungsleitfaden zum Konfigurieren, Abfragen und Sichern von WooCommerce-Backend-APIs (WPGraphQL und REST) für entkoppelte Frontend-Anwendungen (Next.js, Remix, Mobile).

---

Voraussetzungen & Bedingungen

• WordPress installiert mit aktivem WooCommerce-Plugin.
• Erreichbarer GraphQL-Endpunkt (Standard: https://your-store.com/graphql).
• Für tiefgehende Abfragen und technische Beispiele, siehe headless-api-reference.md.
• Für das Frontend-Client-Setup, siehe storefront-client.ts.

---

Schritt-für-Schritt-Ausführungs-Checkliste

flowchart TD
    S1["1. Installiere WPGraphQL & WooGraphQL"] --> S2["2. Seed Mock-/Live-Katalogdaten"]
    S2 --> S3["3. Konfiguriere Authentifizierung (JWT / OAuth)"]
    S3 --> S4["4. Überprüfe Schema mit GraphiQL"]
    S4 --> S5["5. Binde Client-Abfragen in Next.js ein"]

Stufe 1: Backend-Plugin-Bereitstellung

• WPGraphQL Core installieren:
  • Installiere und aktiviere wp-graphql aus dem WordPress-Plugin-Verzeichnis.
  • Überprüfe, ob der Endpunkt live ist: GET/POST /graphql.
• WooGraphQL-Erweiterung installieren:
  • Lade wp-graphql-woocommerce herunter und installiere es.
  • Validiere, dass die Typen (Product, ProductCategory, Cart, Customer) im GraphQL-Schema erscheinen.
• Testdaten einspeisen:
  • Führe den CSV-Import über Tools → Import → WooCommerce products (CSV) mit sample-data/sample_products.csv aus.

Stufe 2: Headless-Authentifizierung konfigurieren

• Option A: JWT Auth (wp-graphql-jwt-authentication) :
  • Lade wp-graphql-jwt-authentication hoch und aktiviere es.
  • Generiere ein 64-stelliges Geheimnis (openssl rand -base64 48 | tr -dc 'A-Za-z0-9_#%+=@!' | head -c 64 oder PowerShell-Äquivalent).
  • Füge es in den Container ein (docker exec -it <container> sed -i ... /var/www/html/wp-config.php), füge es zur .env hinzu (GRAPHQL_JWT_AUTH_SECRET_KEY) oder füge es direkt in wp-config.php ein:

    define( 'GRAPHQL_JWT_AUTH_SECRET_KEY', 'your-strong-random-secret' );
    

• Option B: Headless Login (wp-graphql-headless-login) :
  • Verwende diese Option, wenn externes OAuth 2.0 / Social Login (Google, GitHub) erforderlich ist.
  • Konfiguriere die Anbieter über Filter oder Admin-Einstellungen.

Stufe 3: Shop-Daten abfragen

• Öffentlicher Katalog: Frage Kategorien und Produkte mit Union-Fragmenten ab (... on SimpleProduct, ... on VariableProduct).
• Kunden-Session: Erfasse den woocommerce-session-Header bei Warenkorb-Mutationen und sende ihn bei nachfolgenden Anfragen mit.
• Geschütztes Profil: Sende Authorization: Bearer <authToken> für Kundenbestellungen und Adressaktualisierungen.

Stufe 4: Frontend-Integration (Next.js)

• Implementiere SSG/ISR für statische Produktseiten mit öffentlichen GraphQL-Abfragen.
• Verwalte Warenkorb-Tokens im Client-State (Zustand / LocalStorage), um Next.js-Seiten cachebar zu halten.
• Implementiere eine Native-Checkout-Brücke: Leite zu WordPress /checkout weiter, um lokale Zahlungs-Gateways und E-Namad-Konformität zu nutzen.

---

Randfälle & bekannte KI-Fallstricke

1. Unions in Produktabfragen: WooCommerce-Produkte sind polymorph. Frage price niemals direkt auf products { nodes { price } } ab; du musst Typbedingungen verwenden (... on SimpleProduct { price }, ... on VariableProduct { price }).
2. Fehlender Session-Header: Warenkorb-Artikel verschwinden bei der nächsten Anfrage, wenn der vom Server zurückgegebene woocommerce-session-Token nicht gespeichert und vom Frontend-Client erneut gesendet wird.
3. Admin-React-Inkompatibilität: Vermeide Plugins mit veralteten Gutenberg-Admin-Bundles (wie die Einstellungsseiten von wp-graphql-headless-login), wenn du striktes Core-WordPress ohne benutzerdefinierte Build-Schritte verwendest; bleibe bei konstantengesteuerten Plugins wie wp-graphql-jwt-authentication.
4. CORS-Header: Stelle sicher, dass WordPress Anfragen von deiner Frontend-Origin erlaubt, indem du Header oder einen Reverse-Proxy konfigurierst.

---

Überprüfung & Selbsttest

• Führe eine Testabfrage gegen /graphql aus, die bestätigt, dass productCategories und products Knoten zurückgeben.
• Führe die login-Mutation aus, die bestätigt, dass ein gültiger authToken generiert wird.
• Bestätige, dass der woocommerce-session-Header zurückgegeben wird, wenn ein Artikel zum Warenkorb hinzugefügt wird.