Empiece a vender con WebBlocks Commerce

Commerce incorpora tres partes conectadas al CMS:

• Productos: títulos, descripciones, precios, monedas, existencias y una clase fiscal por producto.
• Un proceso de compra para visitantes: un bloque nativo Commerce Buy Button, un carrito con controles de cantidad y un formulario de pago independiente para los datos de contacto y entrega.
• Pedidos y pagos: líneas de pedido guardadas, información del cliente y de entrega, totales fiscales e intentos de pago. PayPal y SumUp cobran en sus propias páginas alojadas; el visitante no introduce los datos de tarjeta en un bloque de contenido del CMS.

Seguirá utilizando páginas normales del CMS para presentar el producto, sus fotografías, preguntas frecuentes y navegación. El bloque Commerce conecta esa página editorial con un producto real. Editar un párrafo de la página de venta no cambia su precio ni sus existencias; se gestionan en Commerce → Products.

Es un buen punto de partida para un catálogo pequeño o unos pocos productos vendidos desde páginas existentes. No incluye un motor de tarifas de envío, cupones, un flujo de preparación de almacén ni un botón de reembolso en la pantalla del pedido. Recoger una dirección no organiza el envío automáticamente. Las membresías recurrentes utilizan el complemento independiente Memberships y su propia configuración; no lo necesita para los pedidos únicos de esta guía.

Para los nombres de endpoints, la integración de desarrolladores y el contrato detallado de pagos, tenga a mano la referencia técnica de Commerce. Esta guía sigue el trabajo que realiza en el panel.

Utilice una instalación de prueba o una tienda que todavía no esté abierta al público. Cambiar la pasarela activa afecta al proceso de pago de Commerce de la instalación; no ponga una tienda operativa en modo de prueba mientras los clientes compran.

Necesitará:

• Una instalación funcional de WebBlocks CMS y una cuenta Super admin para instalar y configurar los pagos.
• Una versión de CMS compatible con la versión elegida del catálogo. Commerce 0.16.0 declara CMS ^1.100.0; el catálogo también indica Laravel 13. Compruebe la compatibilidad con su instalación antes de instalar.
• La extensión intl de PHP tanto en el entorno web como en la línea de comandos. Solicite su activación al administrador del alojamiento si Commerce avisa de un problema de formato de moneda.
• Un sitio en el CMS y permiso para editar y previsualizar una página en él.
• Más adelante, una cuenta comercial adecuada de PayPal o SumUp, credenciales de prueba correspondientes y un sitio HTTPS accesible públicamente para las notificaciones del proveedor.

Un Site Admin puede gestionar productos y consultar pedidos de los sitios asignados. La instalación de complementos, los ajustes de Commerce y las credenciales de pago corresponden a Super admin. Si falta una pantalla, pida que revisen su rol y asignación de sitio; crear otra cuenta no forma parte de la configuración.

El complemento figura como gratuito en el catálogo de complementos WebBlocks. La cuenta del proveedor de pagos es un servicio separado; instalar Commerce no crea ni conecta una cuenta por usted.

1. Inicie sesión en su CMS y abra System → Plugins.
2. Seleccione Browse Plugin Catalog y abra WebBlocks Commerce.
3. Lea el resultado de compatibilidad y las notas de versión. Seleccione Install from Catalog cuando haya una versión compatible.
4. Vuelva a los detalles del complemento instalado. Los paquetes nuevos empiezan disabled para permitir su revisión.
5. Seleccione Enable Plugin. Confirme que está activo y revise el resultado de salud.

En las versiones actuales del CMS, los cambios de base de datos del complemento se aplican automáticamente al instalar, actualizar y activar. Migrations Up to Date significa que no necesita ejecutar migraciones manualmente. Si falla la preparación de la base de datos, resuelva la causa indicada antes de continuar; activar repetidamente no corrige la falta de permisos de base de datos.

La captura muestra la instalación terminada. Si su administrador facilita un ZIP de una versión fiable, utilice Plugin ZIP → Upload Plugin ZIP en la misma pantalla, revíselo y actívelo. Ninguna de estas rutas del panel exige al propietario de la tienda un repositorio de código del complemento ni un comando de compilación de Composer.

Al activarlo aparece Commerce → Products, Orders, Settings en la barra lateral. Abra Settings para continuar. La salud del complemento confirma que el paquete puede ejecutarse; la preparación del pago se comprueba aparte en Commerce Settings.

1. Abra Commerce → Settings → General.
2. Establezca Gateway en Test order (no payment).
3. Seleccione EUR en Default Currency para este ejemplo.
4. Mantenga PayPal Mode y SumUp Mode en Sandbox para las pruebas posteriores.
5. Seleccione Save Commerce Settings y vuelva a Overview.

La moneda predeterminada es el valor inicial de los productos nuevos. No convierte el precio de un producto existente. Cada producto conserva su moneda y todos los artículos del carrito deben utilizar la misma.

En este ejercicio, las comprobaciones útiles son Schema: Ready y Gateway: Ready. PayPal y SumUp pueden indicar Needs config mientras estén inactivos. No necesita credenciales de proveedor para realizar un pedido de prueba sin pago.

La vista general puede identificar la pasarela de prueba como fake, el nombre interno de Test order (no payment). Registra un pedido sin pagar, reserva existencias y nunca contacta con un proveedor. No simula un pago correcto ni marca el pedido como Paid.

Abra Commerce → Products → New Product. Introduzca estos valores y sustituya Northstar Studio por su propio sitio:

Price Amount utiliza unidades menores enteras, no un precio de venta decimal. Para un producto de €18.00 introduzca 1800, no 18 ni 18.00. Algunas monedas tienen otro número de unidades menores; no presuponga que todas usan céntimos. Compruebe el precio formateado al guardar.

Deje Inventory vacío solo si desea deliberadamente no controlar existencias. Vacío significa disponibilidad ilimitada, no agotado. Elija un sitio concreto para este recorrido. Install-wide es un ámbito separado para Super admin y no equivale a seleccionar el sitio actual.

Seleccione Save Product y compruebe Active, €18.00, Inventory 24 y Product Available en los detalles. Allí también aparece una Public Buy URL. Si necesita un enlace directo, copie la URL de su instalación; no la dirección localhost de una captura.

Si el sitio tiene otros idiomas activos, el formulario ofrece títulos y descripciones traducidos. Una traducción vacía utiliza el contenido base. Traducir la página de venta del CMS y traducir el producto Commerce son tareas separadas; revise ambas al añadir otro idioma a la tienda.

Cree un borrador de página para el cuaderno o prepare una actualización por etapas de una página de venta publicada. Seleccione el mismo sitio que el producto. Añada un título, una descripción útil y, si dispone de ella, una fotografía mediante Media Library y el bloque Image habituales.

Después conecte la página con Commerce:

1. Abra el área Main de la página y seleccione Add Block donde corresponda.
2. Elija Commerce Buy Button.
3. En Block Fields, seleccione Studio notebook en Product.
4. Establezca Button Label en Add to Cart.
5. Elija alineación Start y active Show price beside the button.
6. Seleccione Save Block y abra Preview de la página guardada.

El bloque nativo añade el producto seleccionado al carrito de Commerce. No necesita un bloque Trusted HTML, un formulario de pago pegado ni un script del proveedor dentro del contenido.

La vista previa permite probar la página antes de publicarla. El aviso de vista previa no convierte las acciones del carrito en una simulación sin efectos. Pulsar el botón modifica el carrito de su sesión; completar el checkout crea un pedido. Por eso este recorrido eligió primero la pasarela sin pago.

Para un enlace permanente al carrito en la cabecera, añada un elemento de navegación a /plugins/webblocks-commerce/cart, con etiqueta Cart e icono shopping-cart. Commerce puede mostrar la cantidad del carrito en esa acción de icono. La guía de menús de navegación explica cómo añadir y ordenar el elemento.

En la vista previa seleccione Add to Cart. Commerce abre el carrito con un cuaderno. Pulse una vez el control + para que contenga dos.

Confirme nombre, cantidad y precio formateado. Con los precios EUR y datos de ejemplo con impuestos incluidos de esta guía, dos cuadernos de €18.00 suman €36.00. También puede reducir cantidades o eliminar líneas. Añadir de nuevo el mismo producto combina cantidades; añadir productos con otra moneda se rechaza.

Seleccione Go to checkout. Los datos de contacto y entrega están en esta pantalla separada. Introduzca datos ficticios propios, como Example customer y customer@example.test, en lugar de información de clientes reales.

El formulario exige nombre completo, correo electrónico, calle y número, código postal, ciudad y un código de país de dos letras como DE. El teléfono y la segunda línea de dirección son opcionales. Revise el total y seleccione Place test order.

Actualmente se recogen datos de entrega aunque venda un pase de taller u otro artículo que no se enviará. No lo considere un servicio de transporte: en esta versión Commerce no calcula tarifas ni reserva un transportista. El texto de envío del resumen no demuestra que haya configurado un cargo o un flujo de preparación y entrega.

Un resultado correcto muestra Test Order Received y explica que no se ha cobrado. Pending es el estado esperado. Conserve el número de pedido para el siguiente paso; no necesita compartir el enlace privado de estado.

Abra Commerce → Orders, localice el número de la pantalla de resultado y ábralo. Compruebe:

• Status: Pending, porque es un pedido de prueba sin pagar.
• Items: Studio notebook, cantidad 2, €18.00 por unidad y €36.00 en total.
• Customer y Delivery: los datos ficticios introducidos.
• Gateway: fake, el modo sin pago.
• Payment Attempts: el intento registrado y su estado.
• Desglose fiscal: subtotal neto, IVA y total bruto utilizados al comprar.

Abra otra vez el producto. Inventory debería ser ahora 22: se reservaron dos unidades al iniciar el checkout. Añadir un artículo al carrito por sí solo no reserva existencias. Tanto los pedidos pendientes de proveedores reales como las pruebas sin pago pueden mantener reservas.

La pantalla del pedido es de solo lectura. No puede convertir una prueba en un pedido pagado editando aquí su estado, y volver correctamente en el navegador desde PayPal o SumUp no demuestra el pago. El estado real cambia solo cuando Commerce verifica la notificación y los detalles del proveedor.

Los precios y totales fiscales se guardan en el pedido durante el checkout. Cambiar después el precio de un producto afecta a futuras compras; no reescribe los importes de pedidos existentes.

Moneda: el proveedor debe admitir la moneda predeterminada y las de los productos existentes no archivados. Puede rechazarse un cambio de pasarela si un producto utiliza una moneda no admitida. Corrija la moneda del producto o archívelo deliberadamente; cambiar solo la predeterminada no convierte monedas.

Impuestos: la clase fiscal del producto se combina con tasas configuradas en el servidor para el país fiscal de la tienda. El complemento no elige automáticamente otra jurisdicción por cada dirección de entrega. Pida al administrador del alojamiento que confirme la configuración fiscal antes de aceptar pedidos.

Los ajustes relevantes del servidor son WEBBLOCKS_COMMERCE_TAX_ENABLED, WEBBLOCKS_COMMERCE_PRICES_INCLUDE_TAX y WEBBLOCKS_COMMERCE_TAX_COUNTRY. Con impuestos incluidos, el IVA se desglosa del precio; con impuestos excluidos, se suma. Esta prueba utiliza una tasa estándar configurada del 19% y precios EUR con impuestos: €36.00 contienen €5.75 de IVA y €30.25 netos. Ilustra el cálculo de estos datos de ejemplo, no una tasa aplicable a todas las tiendas.

Existencias: las unidades controladas se reservan al comprar y se liberan cuando el pedido falla, se cancela, caduca o se reembolsa mediante el ciclo compatible. Los productos sin control no se decrementan. Antes de crear el pedido, el carrito vuelve a comprobar precio y disponibilidad; un carrito guardado no garantiza precio fijo ni stock reservado.

Pida al administrador que programe la limpieza de pedidos abandonados. El complemento ofrece:

Por ejemplo, puede ejecutarlo cada quince minutos mediante el programador Laravel de la aplicación anfitriona. Elija un plazo adecuado para la tienda y su flujo de pago; el comando hace caducar todos los pedidos pendientes anteriores al umbral, no solo las pruebas. Libera las existencias retenidas por compras abandonadas. Esperar más no convierte un pedido de prueba en pagado.

Para esta parte utilice un sitio de prueba HTTPS accesible públicamente. El proveedor no puede enviar su notificación de servidor a la dirección 127.0.0.1 de las capturas locales.

1. Abra Apps & Credentials en PayPal Developer Dashboard y obtenga el client ID y client secret de sandbox de su aplicación. Utilice la aplicación y cuenta comercial previstas para esta tienda.
2. En Commerce → Settings → General, elija PayPal, seleccione Sandbox para PayPal Mode, elija una moneda predeterminada compatible y guarde.
3. Abra la pestaña PayPal e introduzca Client ID y Client Secret.
4. Copie la Webhook URL generada por su instalación. Registre en PayPal ese endpoint HTTPS para la misma aplicación y modo, incluido el evento CHECKOUT.ORDER.APPROVED utilizado por esta integración. Copie la Webhook ID resultante en Commerce.
5. Guarde y compruebe en Overview y en PayPal la preparación del checkout y del webhook.
6. Inicie un pedido nuevo y apruébelo con una cuenta compradora de sandbox adecuada. Verifique que pasa a Paid después de la notificación verificada, sin depender solo de la página de regreso del navegador.

El endpoint público tiene la ruta /plugins/webblocks-commerce/webhooks/paypal. Cópielo del panel para que dominio y protocolo coincidan con la instalación real. Client ID, secreto y webhook ID deben pertenecer a la misma aplicación y entorno PayPal.

Las instrucciones REST de PayPal explican las credenciales y cuentas sandbox; la referencia Webhooks describe las suscripciones. No necesita implementar esas API para utilizar el panel.

En General se elige una pasarela de pedidos activa. Configurar ambos proveedores no añade al checkout un selector para visitantes.

1. Prepare una cuenta comercial de prueba SumUp con su clave API y código de comercio correspondientes. Si no sabe dónde obtenerlos, siga el recorrido de conexión SumUp.
2. En Commerce → Settings → General, seleccione SumUp, elija Sandbox para SumUp Mode, seleccione una moneda compatible y guarde.
3. Abra SumUp, introduzca API Key y Merchant Code, y guarde.
4. Compruebe la preparación y la URL de webhook generada. Asegúrese de que la ruta HTTPS pública /plugins/webblocks-commerce/webhooks/sumup es accesible.
5. Inicie un checkout nuevo desde el carrito. Commerce crea el pago alojado y envía al cliente a la página SumUp. Complete allí la prueba, vuelva al sitio e inspeccione el pedido guardado.
6. Confirme que pasa a Paid solo después de que Commerce consulte y verifique el resultado del pago del proveedor.

Commerce proporciona la URL de notificación de SumUp al crear cada checkout. No solicita una SumUp Webhook ID independiente. Elegir Sandbox no convierte una clave comercial real en una clave de prueba: cuenta, código y clave deben pertenecer al entorno previsto.

El resumen de pagos en línea de SumUp describe el cobro alojado, y su referencia Checkouts API explica el checkout y la notificación al servidor. El CMS utiliza ese flujo por usted; los datos de tarjeta permanecen en la superficie alojada por SumUp.

Los campos de credenciales son de solo escritura. Tras guardar, el formulario vuelve a estar vacío e indica si existe un valor configurado. Un campo vacío no significa necesariamente que se haya perdido. Dejarlo vacío conserva el valor guardado; utilice Clear saved value solo cuando quiera eliminarlo.

Los valores guardados en Commerce Settings se cifran en reposo. El administrador puede gestionar en su lugar las variables correspondientes del entorno del servidor. Tienen prioridad y aparecen como Managed by environment; el campo queda de solo lectura en el panel. La pestaña System enumera los nombres de variables compatibles sin mostrar sus valores.

Si un reemplazo guardado parece no surtir efecto, compruebe la etiqueta de origen antes de introducirlo otra vez. Coordine los cambios del entorno con el administrador del alojamiento. No incluya claves ni secretos en páginas, bloques HTML, capturas o mensajes de soporte.

Los ajustes de pago se comparten en toda la instalación. Los productos por sitio y los permisos Site Admin no crean una configuración comercial independiente para cada sitio.

Complete primero el ejercicio sin pago y luego realice otra prueba de principio a fin con el sandbox del proveedor elegido. Las capturas solo muestran el ejercicio sin pago; no prueban que su cuenta comercial ni sus notificaciones públicas funcionen.

Antes de abrir la página de venta, confirme:

• El proveedor, modo, credenciales comerciales y configuración webhook corresponden entre sí.
• El sitio y las URL de notificación usan el dominio HTTPS público correcto y siguen accesibles.
• Todos los productos que venderá están Active, asignados al sitio correcto, con precio correcto y moneda compatible.
• La configuración fiscal y el proceso real de entrega cumplen lo prometido en la página.
• Un pago sandbox pasa a Paid en Commerce → Orders tras verificarse con el proveedor. Pruebe también la cancelación y los fallos pertinentes.
• La limpieza de pendientes está programada y se ha revisado su plazo.
• Se han previsualizado la página, navegación, datos de contacto y versiones lingüísticas activas.

Cuando pase deliberadamente a cobros reales, utilice las credenciales live del comerciante real, el modo correspondiente y la configuración webhook de producción correcta. Las credenciales o webhook ID de sandbox y producción no son intercambiables. Confirme otra vez la pasarela y su preparación y siga la revisión y el flujo de publicación habituales.

Publicar una página no configura una cuenta comercial. Cambiar la pasarela también es independiente de publicar y afecta inmediatamente al checkout.

Utilice Draft al preparar un producto y Active cuando esté listo para comprar. Archívelo cuando quiera detener nuevas compras y revise páginas o enlaces que sigan mostrándolo. Las líneas históricas conservan sus nombres e importes guardados.

Antes de actualizar, lea las notas y compatibilidad de la versión, haga una copia de seguridad con su procedimiento habitual y repita una prueba de carrito y checkout después. Las versiones actuales del CMS aplican los cambios de base de datos del complemento al actualizar y activar.

Desactivar Commerce deja inactivas sus rutas, menús, ajustes y aportaciones. Antes de hacerlo en una tienda operativa, tenga en cuenta visitantes, bloques Commerce colocados y notificaciones del proveedor. Desinstalar un paquete subido y desactivado conserva las tablas de base de datos; no es una operación de limpieza de pedidos.

Ya dispone del proceso principal: producto → página CMS → carrito → checkout → revisión de pedido. Consulte la documentación de referencia Commerce para automatización y diagnóstico avanzado, o vuelva a todas las guías para las tareas habituales de páginas, medios y equipos.