WooCommerce Headless API (headless-woocommerce-api)

API WooCommerce Headless (headless-woocommerce-api)

Guía de orquestación para configurar, consultar y asegurar las APIs backend de WooCommerce (WPGraphQL y REST) para impulsar aplicaciones frontend desacopladas (Next.js, Remix, móviles).

---

Requisitos y Precondiciones

• WordPress instalado con el plugin WooCommerce activo.
• Endpoint GraphQL accesible (por defecto: https://tu-tienda.com/graphql).
• Para consultas profundas y ejemplos técnicos, revisa headless-api-reference.md.
• Para la configuración del cliente frontend, inspecciona storefront-client.ts.

---

Lista de Verificación de Ejecución Paso a Paso

flowchart TD
    S1["1. Instalar WPGraphQL y WooGraphQL"] --> S2["2. Sembrar datos de catálogo (mock / real)"]
    S2 --> S3["3. Configurar autenticación (JWT / OAuth)"]
    S3 --> S4["4. Verificar esquema con GraphiQL"]
    S4 --> S5["5. Conectar consultas de cliente en Next.js"]

Etapa 1: Despliegue de Plugins Backend

• Instalar WPGraphQL Core:
  • Instala y activa wp-graphql desde el directorio de plugins de WordPress.
  • Verifica que el endpoint esté activo: GET/POST /graphql.
• Instalar la Extensión WooGraphQL:
  • Descarga e instala wp-graphql-woocommerce.
  • Valida que los tipos (Product, ProductCategory, Cart, Customer) aparezcan en el esquema GraphQL.
• Sembrar Datos de Prueba:
  • Ejecuta el importador CSV mediante Herramientas → Importar → Productos WooCommerce (CSV) usando sample-data/sample_products.csv.

Etapa 2: Configurar Autenticación Headless

• Opción A: JWT Auth (wp-graphql-jwt-authentication):
  • Sube y activa wp-graphql-jwt-authentication.
  • Genera un secreto de 64 caracteres (openssl rand -base64 48 | tr -dc 'A-Za-z0-9_#%+=@!' | head -c 64 o equivalente en PowerShell).
  • Inyéctalo al contenedor (docker exec -it <contenedor> sed -i ... /var/www/html/wp-config.php), agrégalo a .env (GRAPHQL_JWT_AUTH_SECRET_KEY), o directamente a wp-config.php:

    define( 'GRAPHQL_JWT_AUTH_SECRET_KEY', 'tu-secreto-fuerte-aleatorio' );
    

• Opción B: Login Headless (wp-graphql-headless-login):
  • Úsalo si se requiere OAuth 2.0 externo / inicio de sesión social (Google, GitHub).
  • Configura los proveedores mediante filtro o ajustes de administración.

Etapa 3: Consultar Datos de la Tienda

• Catálogo Público: Consulta categorías y productos usando fragmentos de unión (... on SimpleProduct, ... on VariableProduct).
• Sesión del Cliente: Captura el encabezado woocommerce-session en las mutaciones del carrito y pásalo en solicitudes posteriores.
• Perfil Protegido: Pasa Authorization: Bearer <authToken> para pedidos de clientes y actualizaciones de dirección.

Etapa 4: Integración Frontend (Next.js)

• Implementa SSG/ISR para páginas de productos estáticos usando consultas GraphQL públicas.
• Mantén los tokens del carrito en el estado del lado del cliente (Zustand / LocalStorage) para mantener las páginas de Next.js cacheables.
• Implementa un puente de checkout nativo: redirige a /checkout de WordPress para utilizar pasarelas de pago locales y cumplimiento con e-Namad.

---

Casos Límite y Errores Conocidos de IA

1. Uniones en Consultas de Productos: Los productos de WooCommerce son polimórficos. Nunca consultes price directamente en products { nodes { price } }; debes usar condiciones de tipo (... on SimpleProduct { price }, ... on VariableProduct { price }).
2. Encabezado de Sesión Faltante: Los elementos del carrito desaparecerán en la siguiente solicitud si el token woocommerce-session devuelto por el servidor no es almacenado y reenviado por el cliente frontend.
3. Incompatibilidad con React de Administración: Evita plugins con paquetes Gutenberg heredados (como los paneles de configuración de wp-graphql-headless-login) si usas WordPress estricto sin pasos de compilación personalizados; opta por plugins basados en constantes como wp-graphql-jwt-authentication.
4. Encabezados CORS: Asegúrate de que WordPress permita solicitudes desde el origen de tu frontend configurando encabezados o un proxy inverso.

---

Verificación y Autocomprobación

• Ejecuta una consulta de prueba contra /graphql confirmando que productCategories y products devuelvan nodos.
• Ejecuta la mutación login confirmando que se genere un authToken válido.
• Confirma que se devuelva el encabezado woocommerce-session al agregar un artículo al carrito.