Guía del operador de WebBlocks Commerce

Instala, configura, prueba y opera el plugin WebBlocks Commerce.

Guía del operador de WebBlocks Commerce

Esta guía explica cómo instalar, configurar y probar el primer plugin MVP de WebBlocks Commerce. El plugin actual admite el pago alojado de un solo producto a través de PayPal. Es deliberadamente pequeño: administración de productos, administración de pedidos en solo lectura, diagnósticos de preparación que no exponen secretos, URLs públicas de compra, un bloque Commerce Buy Button propiedad del plugin, redirecciones de pago de PayPal y confirmación de captura mediante webhook de PayPal.

El plugin se desarrolla en plugins/webblocks-commerce. Sigue siendo un paquete de plugin de instalación manual y no debe trasladarse al núcleo del CMS.

Flujo de usuario actual

Un operador del CMS instala y activa WebBlocks Commerce.
El operador ejecuta las migraciones del plugin desde la pantalla de detalle del plugin.
El operador configura las credenciales de PayPal en el entorno de la instalación.
El operador abre Commerce Settings para confirmar que el pago y el webhook están listos.
El operador crea un producto de comercio.
La pantalla de detalle del producto muestra una URL pública de compra.
El operador añade un bloque Commerce Buy Button a una página y selecciona el producto.
Un visitante inicia el pago, lo aprueba en PayPal y vuelve al sitio.
El pedido queda pendiente hasta que el webhook de PayPal verifica y captura el pago.
El operador revisa el pedido pagado en Commerce Orders.

Instalar el plugin

Genera el ZIP del plugin desde el repositorio del CMS:

php plugins/webblocks-commerce/build-plugin.php

Después completa el ciclo de vida manual del plugin:

Abre System -> Plugins.
Sube el ZIP generado de WebBlocks Commerce.
Revisa la pantalla de detalle del plugin.
Activa el plugin.
Ejecuta la instalación/migraciones del plugin si este informa Setup required.
Confirma que el estado pasa de «setup required» a «ready».

El plugin es propietario de las tablas webblocks_commerce_*. Desactivar el plugin deja inertes sus rutas, menús, ajustes y comportamiento. Desinstalar un plugin desactivado que se subió manualmente elimina el paquete subido, pero conserva las tablas propiedad del plugin.

Automatización por API

Las herramientas de operador de confianza pueden ejecutar el flujo de configuración y de construcción de páginas a través de /webadmin/api cuando el token de API del CMS tiene capacidades explícitas de plugin, comercio y contenido.

Ciclo de vida del plugin:

GET /webadmin/api/plugins POST /webadmin/api/plugins/install POST /webadmin/api/plugins/webblocks-commerce/enable POST /webadmin/api/plugins/webblocks-commerce/setup POST /webadmin/api/plugins/webblocks-commerce/disable DELETE /webadmin/api/plugins/webblocks-commerce

Recursos de comercio:

GET /webadmin/api/commerce/products POST /webadmin/api/commerce/products PATCH /webadmin/api/commerce/products/{product} GET /webadmin/api/commerce/orders GET /webadmin/api/commerce/orders/{order}

Las capacidades necesarias del token están separadas a propósito:

ciclo de vida del plugin: plugins.read, plugins.install, plugins.manage, plugins.setup y, solo cuando haga falta, plugins.uninstall
trabajo con productos: commerce.read y commerce.products.write
revisión de pedidos: commerce.orders.read
colocación en páginas: content.validate y content.apply

El flujo de API para añadir un botón de compra es:

Instala, activa y prepara webblocks-commerce.
Crea un producto activo con POST /webadmin/api/commerce/products.
Lee GET /webadmin/api/block-types o GET /webadmin/api/content-contract.
Añade un bloque webblocks-commerce-buy-button mediante content validate/apply.
Asigna a settings.commerce_product_id el id de producto devuelto por la API de Commerce.

El bloque Commerce Buy Button es propiedad del plugin. Queda oculto en el descubrimiento de bloques mientras el plugin está desactivado, y content validate/apply rechaza ids de producto ausentes, desconocidos o inactivos. La API no recoge datos de tarjeta; los visitantes siguen completando el pago mediante el flujo público de Commerce/PayPal.

Configuración de PayPal

WebBlocks Commerce usa las APIs REST de PayPal. PayPal documenta que sus APIs REST utilizan tokens de acceso OAuth 2.0 y que las llamadas a la API intercambian un client ID y un client secret por un token de acceso. Mantén el client secret en privado y no lo pegues nunca en contenido del CMS, páginas de documentación, capturas de pantalla ni registros de soporte.

Referencias oficiales de PayPal:

Define estas variables de entorno en la instalación del CMS:

WEBBLOCKS_COMMERCE_GATEWAY=paypal WEBBLOCKS_COMMERCE_PAYPAL_MODE=sandbox WEBBLOCKS_COMMERCE_PAYPAL_CLIENT_ID=your-paypal-client-id WEBBLOCKS_COMMERCE_PAYPAL_CLIENT_SECRET=your-paypal-client-secret WEBBLOCKS_COMMERCE_PAYPAL_WEBHOOK_ID=your-paypal-webhook-id

Usa WEBBLOCKS_COMMERCE_PAYPAL_MODE=live solo después de haber probado el pago en sandbox y la verificación del webhook.

Configuración del sandbox de PayPal

En el PayPal Developer Dashboard:

Abre Apps & Credentials.
Usa la app REST API por defecto o crea una nueva.
Copia el client ID y el client secret de sandbox al entorno de la instalación.
Crea o abre los ajustes de webhook de la app.
Añade esta URL de webhook:

https://your-site.example/commerce/webhooks/paypal

Suscríbete como mínimo a:

CHECKOUT.ORDER.APPROVED PAYMENT.CAPTURE.COMPLETED

Copia el webhook ID de PayPal en WEBBLOCKS_COMMERCE_PAYPAL_WEBHOOK_ID.
Usa cuentas de comprador y vendedor del sandbox de PayPal para probar el pago.

Para túneles HTTPS locales, usa la URL HTTPS del túnel como URL de webhook. En producción, usa la URL HTTPS pública definitiva del sitio.

Diagnósticos de preparación

Abre:

/webadmin/plugins/webblocks-commerce/settings

La pantalla de ajustes muestra a propósito solo diagnósticos seguros:

pasarela activa
modo de PayPal
client ID configurado o ausente
client secret configurado o ausente
webhook ID configurado o ausente
preparación del pago
preparación del webhook
URL de webhook esperada
preparación del esquema del plugin

No debe mostrar client secrets de PayPal en claro, tokens, firmas de payloads de webhook ni credenciales de pago.

Crear un producto

Abre:

/webadmin/plugins/webblocks-commerce/products

Crea un producto con:

título
slug
descripción
estado
importe del precio
moneda
cantidad de inventario (opcional)
SKU (opcional)
ámbito de sitio (opcional)

Pon el estado del producto en Active cuando deba estar disponible para la compra. Los productos en borrador o archivados no inician el pago público.

La pantalla de detalle del producto muestra su URL pública de compra:

/commerce/products/{slug}/buy

Añadir un botón de compra a una página

Una vez activado el plugin y completada su preparación, el selector de bloques del constructor de páginas muestra un bloque Commerce Buy Button propiedad del plugin.

Flujo recomendado:

Abre en el constructor de páginas la página de obra, portafolio o «Works».
Añade Commerce Buy Button al slot deseado.
Selecciona un producto de comercio activo.
Si quieres, cambia la etiqueta del botón, la alineación y la visualización del precio.
Publica la página cuando el contenido que la rodea esté listo.

El bloque renderiza un botón público que enlaza a:

/commerce/products/{slug}/buy

La URL de compra del producto sigue siendo útil como alternativa para elementos de navegación manuales o campos de enlace existentes.

No pegues URLs de pago alojado de PayPal en el contenido del CMS. Las URLs de aprobación de PayPal se generan por pedido y deben proceder únicamente del flujo de inicio de pago.

Comportamiento del pago

Cuando un visitante pulsa la URL de compra:

La página de compra comprueba que el plugin esté activado, la preparación completada, el producto activo y la pasarela configurada.
El visitante inicia el pago.
WebBlocks Commerce crea un pedido pendiente, una línea de pedido y un intento de pago pendiente.
El adaptador de PayPal crea un PayPal Order.
Se redirige al visitante a la aprobación de PayPal.
El visitante vuelve a una página firmada de éxito o de cancelación.
La página de éxito no marca el pedido como pagado.
PayPal envía un webhook a /commerce/webhooks/paypal.
WebBlocks Commerce verifica con PayPal la firma del webhook.
Para CHECKOUT.ORDER.APPROVED, WebBlocks Commerce captura el pedido de PayPal.
Si la captura se completa, el pedido se marca como paid y el intento de pago como succeeded.

Los eventos de webhook se almacenan por pasarela e ID de evento, de modo que las entregas repetidas son idempotentes.

Revisar pedidos

Abre:

/webadmin/plugins/webblocks-commerce/orders

En el MVP los pedidos son de solo lectura. La pantalla de detalle del pedido muestra:

número de pedido
correo del cliente cuando PayPal lo devuelve
estado del pedido
líneas del pedido
intentos de pago
referencias de pago y de checkout de la pasarela
marcas de tiempo

La edición manual de estados, las devoluciones, los envíos, los impuestos y los flujos de preparación de pedidos se han pospuesto a propósito.

Lista de verificación en sandbox

Usa esta lista antes de pasar al modo live:

WebBlocks Commerce está instalado, activado y preparado.
Commerce Settings muestra el esquema listo.
Commerce Settings muestra la pasarela paypal.
El client ID de PayPal está configurado.
El client secret de PayPal está configurado.
El webhook ID de PayPal está configurado.
La URL del webhook usa HTTPS y apunta a /commerce/webhooks/paypal.
Hay un producto activo con el precio y la moneda esperados.
La URL de compra del producto se abre públicamente.
Una página con un bloque Commerce Buy Button muestra la etiqueta de producto y el enlace de compra esperados.
Iniciar el pago redirige a PayPal.
Un comprador de sandbox puede aprobar el pago.
El visitante vuelve a la página firmada de éxito.
El pedido sigue pendiente antes de la confirmación por webhook.
PayPal entrega CHECKOUT.ORDER.APPROVED.
El webhook se verifica correctamente.
La captura del pedido de PayPal se completa.
El pedido del CMS pasa a paid.
El intento de pago pasa a succeeded.
Reenviar el mismo webhook no duplica intentos de pago.
Las firmas de webhook inválidas se rechazan y no marcan pedidos como pagados.
Ningún secreto de PayPal aparece en pantallas de administración, páginas públicas, registros, capturas ni documentación.

Lista de verificación para el modo live

Antes de cambiar a WEBBLOCKS_COMMERCE_PAYPAL_MODE=live:

Confirma que el operador dispone de una cuenta PayPal Business donde PayPal lo exija.
Crea o selecciona la app REST live en el PayPal Developer Dashboard.
Sustituye el client ID, el client secret y el webhook ID de sandbox por los valores live.
Configura la URL de webhook live con el dominio HTTPS de producción.
Confirma que el sitio de producción puede recibir peticiones públicas de webhook de PayPal.
Realiza un pago live de importe bajo si al operador le parece aceptable.
Revisa el pedido en el admin del CMS.

Mantén separadas las credenciales de sandbox y de live. No reutilices webhook IDs de sandbox en modo live.

Resolución de problemas

Si la página de compra dice que el pago no está listo:

Abre Commerce Settings.
Confirma que la pasarela es paypal.
Confirma que el client ID y el client secret están configurados.
Confirma que el producto está activo y tiene un precio válido.
Confirma que se han ejecutado las migraciones del plugin.

Si el pago redirige a PayPal pero el pedido sigue pendiente:

Confirma que la URL de webhook de PayPal es correcta.
Confirma que WEBBLOCKS_COMMERCE_PAYPAL_WEBHOOK_ID coincide con el webhook configurado en PayPal.
Confirma que PayPal envía CHECKOUT.ORDER.APPROVED.
Confirma que PayPal puede alcanzar el sitio por HTTPS.
Confirma que la verificación de la firma del webhook no está fallando.

Si se rechaza un webhook:

Comprueba que el evento provenga del modo de PayPal correspondiente.
Comprueba que no se mezclen credenciales de sandbox con webhook IDs de live.
Comprueba que el webhook ID pertenezca a la misma app REST de PayPal que las credenciales de cliente.

Limitaciones actuales

El MVP todavía no incluye:

carrito ni pago de varios productos
impuestos
envíos
cupones
suscripciones
devoluciones desde el CMS
cuentas de cliente
reserva de inventario
flujos de preparación de pedidos
interfaz de alta live de PayPal dentro del CMS

Se han pospuesto a propósito para que la primera porción del plugin siga siendo pequeña, segura y revisable.