Guía del operador WebBlocks Commerce

Esta guía explica cómo instalar, configurar y probar WebBlocks Commerce. El complemento admite un carrito público respaldado por sesión, recopilación de direcciones de cliente y entrega, un modo de pedido de prueba sin pago, pago alojado en varias líneas a través de PayPal o SumUp, administrador de pedidos de productos y de solo lectura, configuración de proveedor cifrada de solo escritura, diagnósticos seguros, páginas públicas de productos y un bloque de botón de compra de comercio propiedad del complemento. Los datos de la tarjeta de pago permanecen en la superficie de pago alojada del proveedor seleccionado.

Los propietarios de tiendas que quieran conectarse a SumUp deben comenzar con la opción centrada en tareas. Inicio rápido de SumUp. Esta guía del operador es la guía técnica referencia para arquitectura, API, verificación y solución de problemas avanzada.

El complemento se desarrolla en su propio repositorio, webblocks-commerce-plugin, junto con los demás complementos del catálogo. Sigue siendo un paquete de complementos instalado manualmente y no debe trasladarse al núcleo de CMS.

Versión del paquete documentado: 0.14.0. WebBlocks CMS ^1.61.0; PHP >=8.3.

PHP se requiere ext-intl en los tiempos de ejecución web y CLI para el formato de moneda.

1. A El operador de CMS instala y habilita WebBlocks Commerce.
2. El operador ejecuta las migraciones de complementos desde la pantalla de detalles del complemento.
3. El operador selecciona PayPal, SumUp o Test order (no payment) y una moneda predeterminada compatible en Commerce Settings. Los proveedores reales requieren credenciales; En su lugar, los valores del entorno administrado por hosting se pueden usar como anulaciones.
4. El operador abre Commerce Settings para confirmar el pago y la preparación del webhook.
5. El operador crea un producto comercial.
6. La pantalla de detalles del producto muestra una URL de compra pública.
7. El operador agrega un bloque Commerce Buy Button a una página y selecciona el producto.
8. El bloque agrega el producto a /plugins/webblocks-commerce/cart; el visitante actualiza las cantidades e ingresa los detalles de contacto y entrega requeridos.
9. En el modo de pedido de prueba, Commerce registra un pedido pendiente impago y regresa directamente a la página de estado del pedido sin comunicarse con un proveedor.
10. Con PayPal o SumUp, el visitante aprueba el pago en la página alojada del proveedor seleccionado y regresa al sitio.
11. Los pedidos de proveedores reales permanecen pendientes hasta que un webhook verificado por el proveedor confirme el pago.
12. El operador revisa los detalles del cliente, la entrega, el artículo, los impuestos y el pago en Commerce Orders.

Construya el complemento ZIP desde el repositorio de complementos:

El artefacto está escrito en build/webblocks-commerce-{version}.zip con su SHA-256 al lado.

Luego complete el ciclo de vida del complemento manual:

1. Abra System -> Plugins.
2. Cargue el ZIP WebBlocks Commerce generado.
3. Revise la pantalla de detalles del complemento.
4. Habilite el complemento.
5. Ejecute la configuración/migración del complemento si el complemento informa Setup required.
6. Confirme que el estado cambie de configuración requerida a listo.

El complemento posee tablas webblocks_commerce_*. Deshabilitar el complemento hace que las rutas, los menús, las configuraciones y el comportamiento sean inertes. La desinstalación de un complemento cargado manualmente deshabilitado elimina el paquete cargado, pero conserva las tablas propiedad del complemento.

Las herramientas de operador confiables pueden realizar el flujo de trabajo de configuración y creación de páginas a través de /webadmin/api cuando el token API de CMS tiene capacidades explícitas de complemento, comercio y contenido.

Ciclo de vida del complemento:

Recursos comerciales:

Las capacidades de token requeridas están divididas intencionalmente:

• ciclo de vida del complemento: plugins.read, plugins.install, plugins.manage, plugins.setup, y solo cuando sea necesario plugins.uninstall
• Trabajo del producto: commerce.read y commerce.products.write.
• revisión de pedido: commerce.orders.read
• Colocación de página: content.validate y content.apply.

El flujo API para agregar un botón de compra es:

1. Instalar, habilitar y configurar webblocks-commerce.
2. Crear un producto activo con POST /webadmin/api/commerce/products.
3. Lea GET /webadmin/api/block-types o GET /webadmin/api/content-contract.
4. Agregue un bloque webblocks-commerce-buy-button mediante validación/aplicación de contenido.
5. Establezca settings.commerce_product_id en la identificación del producto devuelta por la API de comercio.

El bloque del botón de compra de Commerce es propiedad del complemento. Está oculto para el descubrimiento de bloques mientras el complemento está deshabilitado, y la validación/aplicación de contenido rechaza los identificadores de productos faltantes, desconocidos o inactivos. Su renderizador público publica en el carrito propiedad del complemento; no se requiere ningún bloque Trusted HTML. La API no recopila datos de la tarjeta; los visitantes completan el pago en el proceso de pago alojado en PayPal o SumUp configurado.

WebBlocks Commerce utiliza las API REST de PayPal. PayPal documenta que las API REST utilizan tokens de acceso de OAuth 2.0 y que las llamadas API intercambian un ID de cliente y un secreto de cliente por un token de acceso. Mantenga el secreto del cliente en privado y nunca lo pegue en contenido de CMS, páginas de documentos, capturas de pantalla o registros de soporte.

Referencias oficiales de PayPal:

• Comenzar con las API REST de PayPal
• Códigos de moneda admitidos por PayPal y precisión
• API de webhooks de PayPal
• Verificar firma de webhook

Obra Commerce Settings, seleccione PayPal, seleccione Sandbox e ingrese el ID del cliente, el secreto del cliente, e ID de webhook. Los campos son de solo escritura: los valores guardados están cifrados en la tabla de configuración del complemento y nunca se muestran nuevamente en el navegador. Dejar un campo en blanco conserva su valor actual; use la casilla de verificación clara explícita para eliminarlo.

Para la configuración administrada por hosting, las siguientes variables de entorno siguen siendo compatibles y toman prioridad sobre la configuración de administrador cifrada:

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

En el panel de desarrollador de PayPal:

1. Obrir Apps & Credentials.
2. Utilice la aplicación API REST predeterminada o cree una nueva aplicación.
3. Copie el ID del cliente de sandbox y el secreto del cliente en el formulario de configuración de comercio seguro (o en el entorno de instalación cuando se utilizan anulaciones administradas por hosting).
4. Cree o abra la configuración del webhook de la aplicación.
5. Agregue esta URL de webhook:

1. Suscríbete como mínimo a:

1. Copie el ID del webhook de PayPal en el formulario de Configuración de comercio (o WEBBLOCKS_COMMERCE_PAYPAL_WEBHOOK_ID cuando utilice una anulación de entorno).
2. Utilice cuentas de comprador y vendedor de la zona de pruebas de PayPal para realizar pruebas de pago.

Para túneles HTTPS locales, utilice la URL HTTPS del túnel como URL del webhook. Para producción, utilice la URL del sitio HTTPS público final.

SumUp Hosted Checkout mantiene el ingreso de tarjetas y la interfaz de usuario de billetera compatible en una página alojada en SumUp. el La integración crea el lado del servidor de pago y nunca expone la clave API al navegador.

Para un flujo de trabajo de propietario de tienda pantalla por pantalla, utilice el Inicio rápido de SumUp. La breve secuencia de configuración es:

1. Cree y seleccione un comerciante sandbox en SumUp Dashboard Configuración del desarrollador → Sandboxes.
2. Copie el entorno de pruebas ID de comerciante que se muestra en el área de cuenta del Panel superior izquierdo.
3. Cree una clave API de prueba secreta en Configuración → Para desarrolladores → Kit de herramientas → Claves API.
4. Ingrese la puerta de enlace, el modo, la clave API y el código de comerciante en Configuración de comercio y confirme que esté listo.
5. Pruebe con la tarjeta sandbox documentada de SumUp antes de usar credenciales activas.

Referencias oficiales de resumen:

• Pago alojado
• Crear y recuperar pagos
• Webhooks de estado de pago
• API llaves
• Prueba de pagos en línea

En Commerce Settings, seleccione SumUp, seleccione Sandbox e ingrese la clave API y el código de comerciante. Las credenciales guardadas se cifran en reposo y permanecen como de solo escritura. Las implementaciones administradas por hosting pueden en su lugar, establezca estas variables de entorno; tienen prioridad y hacen que los campos del formulario coincidan sólo lectura:

Use la clave API secreta creada para el comerciante sandbox seleccionado; no utilice la clave pública de SumUp. Una clave secreta de prueba normalmente comienza con sk_test_. No lo pegue en bloques CMS, configuración del sitio, capturas de pantalla, registros de soporte o chat normal. WebBlocks Commerce envía esta devolución de llamada automáticamente cuando crea cada pago:

No se requiere registro manual de webhook en el panel SumUp para este adaptador. el publico No obstante, SumUp debe poder acceder al punto final HTTPS y no debe estar bloqueado por un firewall. página de mantenimiento, contraseña HTTP o regla de proxy.

SumUp llama al return_url configurado con CHECKOUT_STATUS_CHANGED y un ID de pago. eso La carga útil no se acepta como comprobante de pago. WebBlocks Commerce recupera el pago de SumUp, luego hace coincidir el ID, el código de comerciante, la referencia del pedido, el monto, la moneda, el estado del terminal, y transacción exitosa antes de marcar un pedido como pagado. Transiciones de estado fallidas y caducadas liberar el inventario reservado. Los tipos de eventos desconocidos se ignoran de forma segura.

abierto:

La pantalla de configuración proporciona campos de credenciales de solo escritura e intencionalmente muestra solo diagnósticos seguros:

• puerta de enlace activa
• moneda predeterminada y su fuente de configuración
• Modo PayPal
• Modo suma
• ID de cliente configurado o faltante
• secreto de cliente configurado o faltante
• ID de webhook configurado o faltante
• preparación para el pago
• preparación de webhook
• URL de webhook esperada
• Clave API SumUp y código de comerciante configurados o faltantes
• preparación del esquema del complemento

No debe mostrar secretos de PayPal sin procesar, claves API de SumUp, tokens de acceso, firmas de carga útil de webhook ni credenciales de pago. Los campos de credenciales en blanco conservan los valores cifrados existentes. Los controles de borrado explícitos eliminan los valores almacenados, mientras que los valores administrados por el entorno no se pueden editar ni borrar desde CMS.

abierto:

Crear un producto con:

• título
• slug
• descripción
• estado
• precio monto
• moneda
• Cantidad de inventario opcional
• opcional SKU
• Alcance del sitio opcional

Establezca el estado del producto en Active cuando debería estar disponible para su pago. Los productos borradores y archivados no inician el proceso de pago público.

La moneda predeterminada se almacena con las otras configuraciones de Commerce y se utiliza para productos nuevos. WEBBLOCKS_COMMERCE_DEFAULT_CURRENCY sigue siendo una anulación de entorno opcional; cuando está presente, el El selector es de sólo lectura. La moneda del producto se selecciona de la lista admitida de la puerta de enlace activa, y la API interna del producto aplica la misma regla.

Las puertas de enlace de conmutación se bloquean si un producto no archivado utiliza una moneda no admitida por el destino puerta de enlace. Los carritos con monedas mixtas siguen rechazados. Checkout realiza una compatibilidad final de la puerta de enlace verifique antes de crear un pedido o reservar inventario.

Los precios son unidades menores enteras, pero la precisión de las unidades menores es específica de la moneda y no siempre dos dígitos. Las vistas pública y de administrador utilizan la configuración regional actual del CMS a través de PHP intl NumberFormatter, por lo que los símbolos y separadores están localizados para EUR, USD, GBP, JPY y todos moneda seleccionable. Las solicitudes de puerta de enlace utilizan la misma precisión. Cero decimal específico de PayPal Se cumplen los requisitos para HUF y TWD.

No existe ninguna dependencia Composer adicional. PHP ext-intl es un requisito de plataforma y debe ser habilitado tanto para el servidor web como para la CLI. El resultado del estado del complemento advierte cuando no está disponible. Los códigos admitidos se basan en el código oficial. Referencia de moneda de PayPal y SumUp API de pago enumeración; país mercantil y las restricciones de cuenta aún pueden limitar esas listas de proveedores.

La pantalla de detalles del producto muestra la URL de compra pública del producto:

Después de que el complemento esté habilitado y listo para la configuración, el selector de bloques del generador de páginas muestra un bloque Commerce Buy Button propiedad del complemento.

Flujo de trabajo recomendado:

1. Obra la obra de arte, el portafolio o la página "Obras" en el generador de páginas.
2. Agregue Commerce Buy Button a la ranura deseada.
3. Seleccione un producto comercial activo.
4. Opcionalmente cambie la etiqueta del botón, la alineación y la visualización del precio.
5. Publique la página cuando el contenido circundante esté listo.

El bloque representa un formulario público nativo que agrega el producto seleccionado a:

La URL de compra del producto sigue siendo útil para enlaces de detalles del producto y expone una acción de agregar al carrito. El pago se completa desde el carrito, por lo que no se pueden omitir los campos obligatorios de cliente y entrega. Las vistas del carrito, la página del producto y el estado de pago amplían el CMS diseño público, preservando los espacios de encabezado y pie de página del sitio activo.

No pegue las URL de pago alojadas por el proveedor en el contenido del CMS. Se generan por pedido y deben provenir únicamente del flujo de inicio de pago.

Cuando un visitante utiliza un bloque de comercio o una página de producto:

1. El complemento verifica la configuración, el estado del producto, el stock rastreado y la moneda del carrito.
2. El producto se almacena en el carrito del lado del servidor respaldado por sesión; no se recopilan datos de pago.
3. El visitante proporciona nombre, correo electrónico, dirección de entrega y adición opcional de teléfono/dirección.
4. An el momento del pago, WebBlocks Commerce congela los metadatos de cliente/entrega, títulos de línea localizados, precios, IVA y totales en un pedido pendiente y reserva stock de forma atómica.
5. En el modo de pedido de prueba, el visitante regresa directamente a una página de estado firmada y no se contacta a ningún proveedor de pago. Con PayPal o SumUp, el adaptador activo crea un pago alojado y redirige al visitante.
6. A La página de devolución firmada puede informar que el procesamiento continúa, pero nunca marca el pedido pagado.
7. Los webhooks de PayPal están verificados por firma y los pedidos de PayPal aprobados se capturan.
8. Las notificaciones de estado de SumUp activan una nueva recuperación de API de pago y una coincidencia completa de pedidos/transacciones.
9. Solo el resultado del proveedor verificado mueve el pedido y el intento de pago a paid/succeeded.

Los eventos de Webhook se almacenan mediante la puerta de enlace y el ID del evento, por lo que la entrega repetida es idempotente.

abierto:

Orders son de solo lectura. La pantalla de detalles del pedido muestra:

• número de pedido
• nombre del cliente, correo electrónico requerido, teléfono opcional y dirección de entrega capturados por el carrito público
• estado del pedido
• artículos de línea
• intentos de pago
• referencias de pago y pago de gateway
• marcas de tiempo

La edición manual de estado, los reembolsos, el cálculo de tarifas de envío y los flujos de trabajo de cumplimiento se posponen intencionalmente. Se implementan la captura de direcciones de entrega y de clientes, instantáneas de IVA y reserva de inventario.

Seleccione Test order (no payment) en Commerce Settings cuando el propietario de una tienda quiera verificar el complete el formulario de escaparate y el flujo de registro de pedidos sin comunicarse con PayPal o SumUp. el publico El carrito etiqueta claramente el modo, requiere detalles del cliente y de entrega, crea un pedido pendiente, reserva stock rastreado, registra un intento de pago falso pendiente para la continuidad de la auditoría y redirecciona a una página de confirmación firmada que indica que no se cobró ningún pago. Volver a un configurado proveedor real antes de aceptar pedidos pagados de clientes.

Utilice esta lista de verificación antes de cambiar al modo en vivo:

• WebBlocks Commerce está instalado, habilitado y listo para la configuración.
• Commerce Settings muestra el esquema listo.
• Commerce Settings muestra la puerta de enlace paypal.
• La identificación del cliente de PayPal está configurada.
• El secreto del cliente de PayPal está configurado.
• El ID del webhook de PayPal está configurado.
• La URL del webhook utiliza HTTPS y apunta a /plugins/webblocks-commerce/webhooks/paypal.
• Un producto está activo y tiene el precio/moneda esperado.
• La URL de compra del producto se abre públicamente.
• Una página con Commerce Buy Button agrega el producto esperado a /plugins/webblocks-commerce/cart.
• Al iniciar el proceso de pago se redirige a PayPal.
• Un comprador de sandbox puede aprobar el pago.
• El visitante regresa a la página de éxito firmada.
• El pedido permanece pendiente antes de la confirmación del webhook.
• PayPal entrega CHECKOUT.ORDER.APPROVED.
• El webhook se verifica correctamente.
• Se completa la captura del pedido de PayPal.
• El pedido de CMS pasa a ser paid.
• El intento de pago pasa a ser succeeded.
• Reenviar el mismo webhook no duplica los intentos de pago.
• Las firmas de webhooks no válidas se rechazan y no marcan los pedidos pagados.
• No aparece ningún secreto de PayPal en las pantallas de administración, páginas públicas, registros, capturas de pantalla o documentos.

• El comerciante sandbox se selecciona en SumUp Dashboard.
• El ID de comerciante y la clave secreta sk_test_ pertenecen a esa misma cuenta sandbox.
• Commerce Settings muestra la puerta de enlace sumup, el modo sandbox y el pago listo.
• La clave de API de prueba y el código de comerciante de la zona de pruebas están configurados, pero el valor de la clave no se representa.
• Un bloque de Comercio agrega el producto EUR activo a /plugins/webblocks-commerce/cart.
• La cantidad, el IVA y el importe final son correctos antes del pago.
• Al iniciar el pago se crea un pedido pendiente y se redirige a checkout.sumup.com.
• La referencia de pago de SumUp coincide con el número de pedido de CMS.
• Completar un pago sandbox produce CHECKOUT_STATUS_CHANGED en /plugins/webblocks-commerce/webhooks/sumup.
• El controlador recupera el pago de SumUp y confirma una transacción exitosa.
• La orden de CMS pasa a ser paid y su intento de pago pasa a ser succeeded.
• Reenviar la misma notificación pagada no crea otro intento de pago.
• Un código de comerciante, una referencia, un monto o una moneda que no coincidan nunca marcan un pedido pagado.
• Los pagos de SumUp fallidos o vencidos liberan el inventario reservado.
• La tarjeta de prueba exitosa documentada 4200 0000 0000 0091 se completa con cualquier fecha de caducidad futura. y cualquier CVV de tres dígitos.

Antes de cambiar a WEBBLOCKS_COMMERCE_PAYPAL_MODE=live:

• Confirme que el operador posee una cuenta comercial de PayPal cuando PayPal lo requiera.
• Cree o seleccione la aplicación REST en vivo en el Panel de desarrollador de PayPal.
• Reemplace el ID de cliente de sandbox, el secreto de cliente y el ID de webhook con valores activos.
• Configure la URL del webhook en vivo con el dominio HTTPS de producción.
• Confirme que el sitio de producción pueda recibir solicitudes de webhook públicos de PayPal.
• Ejecute un pago en vivo de bajo valor si es aceptable para el operador.
• Revisar el pedido en el administrador de CMS.

Mantenga las credenciales activas y de sandbox separadas. No reutilice los ID de webhook de sandbox en el modo en vivo.

Para el modo en vivo SumUp, seleccione la cuenta de comerciante real verificada, cree un sk_live_ separado clave API secreta, use el ID de comerciante activo de esa cuenta, configure WEBBLOCKS_COMMERCE_SUMUP_MODE=live, actualice la configuración de la aplicación y ejecute un pago aceptable de bajo valor. Nunca reutilice o combine un comerciante sandbox, una clave de prueba, un comerciante en vivo o una clave en vivo.

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

• Abra Commerce Settings.
• Confirme que la puerta de enlace seleccionada sea paypal o sumup.
• Para PayPal, confirme que la ID del cliente y el secreto del cliente estén configurados.
• Para SumUp, confirme que la clave API y el código de comerciante estén configurados.
• Confirma que el producto esté activo y tenga un precio válido.
• Confirme que se hayan ejecutado las migraciones de complementos.

Si el proceso de pago redirige a PayPal pero el pedido permanece pendiente:

• Confirme que la URL del webhook de PayPal sea correcta.
• Confirmar que WEBBLOCKS_COMMERCE_PAYPAL_WEBHOOK_ID coincide con el webhook configurado en PayPal.
• Confirmar que PayPal envía CHECKOUT.ORDER.APPROVED.
• Confirme que se puede acceder al sitio desde PayPal a través de HTTPS.
• Confirmar que la verificación de la firma del webhook no falla.

Si se rechaza un webhook:

• Compruebe que el evento de webhook proceda del modo PayPal correspondiente.
• Compruebe que las credenciales de la zona de pruebas no estén mezcladas con los ID de webhook en vivo.
• Compruebe que el ID del webhook pertenezca a la misma aplicación REST de PayPal que las credenciales del cliente.

Si una orden SumUp permanece pendiente:

• Confirme que la URL HTTPS pública /plugins/webblocks-commerce/webhooks/sumup sea accesible.
• Confirme que la clave API puede leer el pago y pertenece al código de comerciante configurado.
• Confirme que la referencia de pago, el monto y la moneda aún coinciden con el pedido de CMS.
• Confirmar SumUp informa PAID e incluye una transacción SUCCESSFUL.

Si la página alojada de SumUp informa un pago vencido o faltante, inicie un nuevo pago desde carro. Las sesiones de pago alojado caducan después de aproximadamente 30 minutos y sus URL no se deben marcar como favoritas. o reutilizado.

El complemento actual aún no incluye:

• envío
• cupones
• suscripciones
• reembolsos de CMS
• cuentas de clientes
• flujos de trabajo de cumplimiento
• Incorporación de cuenta de proveedor (las credenciales de pago se pueden editar en Configuración de comercio)

Estas siguen siendo características separadas en lugar de estar ocultas dentro de las integraciones del proveedor.

El estado del pedido solo se cambia a través de Support\Orders\OrderStateMachine, nunca actualización sin formato. Aplica el gráfico de transición permitido (pending → paid|failed|cancelled|expired, paid → refunded), es idempotente para los webhooks reentregados y bloquea la fila del pedido para que Las devoluciones de llamada de Racing Gateway no pueden aplicar dos veces una transición.

El stock rastreado (inventory_quantity no nulo) se reserva atómicamente cuando comienza el pago. lo que evita la sobreventa bajo compradores concurrentes, y se devuelve al catálogo cuando un el pedido se cancela, caduca, falla o se reembolsa. Productos con un valor nulo inventory_quantity no tienen seguimiento (ilimitados) y nunca disminuyen.

ALos pedidos abandonados de pending mantienen su reserva hasta que caduquen. correr php artisan webblocks-commerce:expire-stale-orders --minutes=30 en un cronograma para lanzar el stock retenido por cajas que el comprador nunca completó. Conéctelo al kernel de la consola de la aplicación host, por ejemplo $schedule->command('webblocks-commerce:expire-stale-orders')->everyFifteenMinutes();.

Carts son del lado del servidor, persistentes y de moneda única. Un carrito almacena solo producto. referencias + cantidades; Los precios e IVA se resuelven en vivo desde el catálogo actual y solo congelado en el pedido al finalizar la compra (StartCheckout::forCart), que genera un pedido de varias líneas, reserva stock de forma atómica para cada línea y marca el carrito como converted. Añadiendo lo mismo el producto fusiona cantidades; Se rechaza agregar una moneda diferente o más acciones que las registradas.

Los visitantes utilizan el carrito público respaldado por sesión sin un token API. Antes de pagar, el formulario público. requiere el nombre, correo electrónico, calle, código postal, ciudad y código de país de dos letras del cliente; telefono y una segunda línea de dirección siguen siendo opcionales. Los detalles se almacenan en los metadatos del carrito/pedido y se muestran en las pantallas de estado del pedido y detalles del pedido de administrador.

Rutas públicas:

• GET /plugins/webblocks-commerce/cart: revisar líneas de carrito, IVA y total
• POST /plugins/webblocks-commerce/cart/items/{product}: agregue un producto desde un bloque de comercio o compre una página
• PATCH|DELETE /plugins/webblocks-commerce/cart/items/{product}: cambiar cantidad o eliminar una línea
• POST /plugins/webblocks-commerce/cart/checkout: guarde los detalles del cliente/entrega, cree el pedido y continúe con la puerta de enlace configurada

El carrito público, la página de compra y las páginas de estado de pago amplían el diseño público del CMS y muestran el espacios header y footer propios del sitio en torno a su contenido, resueltos desde la página de inicio mediante Support\PublicStorefrontShell. Un encabezado mantenido en un Shared Slot funciona de la misma manera, por lo que cambiar el El encabezado del sitio cambia el escaparate con él. El botón Comprar de Commerce es un bloque de complemento nativo y publicaciones al carrito; no requiere un bloque HTML de confianza.

Todo lo que hace el carrito está disponible en elAPI interna propiedad del complemento- montado en el Grupo API interno de CMS (/webadmin/api, autenticación de token de portador) a través del complementoapiRoutes()gancho, por lo que los agentes de IA obtienen las mismas capacidades que el panel de administración ofrece a los humanos. Puntos finales (capacidad en paréntesis):

• POST /webadmin/api/commerce/cart — crear un carrito (commerce.cart.write)
• GET /webadmin/api/commerce/cart/{token} — leer un carrito con totales en vivo (commerce.cart.read)
• POST /webadmin/api/commerce/cart/{token}/items — agregar {product_id, quantity} (commerce.cart.write)
• PATCH /webadmin/api/commerce/cart/{token}/items/{product} — establecer {quantity} (0 eliminaciones) (commerce.cart.write)
• DELETE /webadmin/api/commerce/cart/{token}/items/{product} — eliminar una línea (commerce.cart.write)
• DELETE /webadmin/api/commerce/cart/{token}/items — borrar el carrito (commerce.cart.write)
• POST /webadmin/api/commerce/cart/{token}/checkout: inicia el pago alojado, devuelve redirect_url (commerce.cart.write)

Los productos y pedidos se exponen de la misma manera (estos puntos finales son propiedad del complemento, no del Núcleo de CMS y solo están presentes cuando el complemento está habilitado):

• GET|POST /webadmin/api/commerce/products, PATCH /webadmin/api/commerce/products/{id} — catálogo incl. tax_class (commerce.read / commerce.products.write)
• GET /webadmin/api/commerce/orders, GET /webadmin/api/commerce/orders/{id}: solo lectura, con el desglose neto/impuesto/bruto completo (commerce.orders.read)

Atodas estas publicidades propias: mientras el complemento está habilitado, aparecen en el descubrimiento de API de CMS (Rutas GET /webadmin/api _links, GET /webadmin/api/openapi.json y guía de descubrimiento) a través de la contribución apiDiscovery() del complemento y desaparece cuando el complemento está deshabilitado.

No hay un token de comercio independiente: el complemento utiliza el token API de CMS compartido . su Las capacidades de commerce.* se aportan al conjunto otorgable del CMS a través de apiCapabilities(). (aparecen como un grupo "Comercio" en la interfaz de usuario del administrador del token mientras el complemento está habilitado), por lo que un El token único con privilegios mínimos puede limitarse únicamente a las capacidades comerciales.

El contenido del producto Storefront comparte el sistema CMS Site+Locale en lugar de uno paralelo. el la fila del producto base contiene el valor predeterminado/alternativo title/description; una fila de traducción por configuración regional (webblocks_commerce_product_translations, codificado por producto + configuración regional de CMS) los anula. esto es el eje del lenguaje del panel de administración content, distinto del lenguaje del panel de administración UI, que permanece en archivos Laravel resources/lang.

ProductLocalizer resuelve el título/descripción mostrado para una configuración regional, recurriendo a la base. Los carritos llevan un locale, por lo que los resúmenes del carrito y, lo que es más importante, la instantánea del título de la línea de pedido en checkout utiliza el texto localizado que el comprador realmente vio. La página de compra pública se localiza a través de un Consulta ?locale=<code>, volviendo a la base.

Editar traducciones en el formulario del producto de administración (según la configuración regional habilitada no predeterminada) o a través de la API (capacidad entre paréntesis):

• GET /webadmin/api/commerce/products/{product}/translations — lista base + traducciones (commerce.read)
• PUT /webadmin/api/commerce/products/{product}/translations/{locale} — insertar {title?, description?} (commerce.products.write)
• DELETE /webadmin/api/commerce/products/{product}/translations/{locale}: eliminar una configuración regional (commerce.products.write)