DfProforma Shopware — Presupuestos pro forma con aceptación del cliente y auto-conversión
Documentación completa del plugin Shopware 6.7 de presupuestos pro forma: instalación, flujo de aceptación del cliente, auto-conversión, Flow Builder y personalización.
Qué hace DfProforma
Shopware 6.7 sabe emitir facturas, albaranes y notas de crédito — pero no presupuestos pro forma. Y sin embargo, en prácticamente todos los contextos B2B (equipamiento industrial, servicios a empresas, compras públicas, ventas por licitación), el cliente debe recibir un documento formal que acepta antes de que el pedido se vuelva firme.
DfProforma cubre esta carencia sin trucos: un verdadero tipo de documento Shopware nativo df_proforma, su propio rango de numeración PF{n}, una plantilla PDF Twig con marca, un flujo de aceptación del cliente autónomo con URL pública firmada HMAC-SHA256, y una conversión automática a pedido firme en cuanto la transacción subyacente pasa al estado pagado.
Requisitos
- Shopware 6.7.0 o superior (el plugin no es retrocompatible con 6.6 debido a la refactorización del sistema de documentos)
- PHP 8.2 mínimo
- MySQL 8.0+ o MariaDB 10.6+
- Workers de mensajes Shopware activos (recomendado para la gestión automática de vencimientos)
- Mail Service Shopware configurado (SMTP funcional para envíos transaccionales)
Instalación
1. Subir el plugin
Desde la administración de Shopware, vaya a Extensiones → Mis extensiones → Subir extensión, y seleccione el archivo DfProforma-1.0.6.zip.
2. Instalar y activar
En la lista de extensiones, haga clic en Instalar y luego en Activar. Las migraciones de Shopware se ejecutan automáticamente y crean:
- La tabla SQL
df_proformacon sus índices enorder_id,status,public_token - El tipo de documento
df_proformaendocument_type - El rango de numeración
document_df_proformaen formatoPF{n}configurable - La plantilla de email transaccional base para generación, envío y aceptación
3. Recompilar la administración
El plugin incluye un módulo Vite admin que extiende la ficha del pedido (sw-order-detail-base). Debe recompilar el bundle de administración global para que aparezca la pestaña Pro forma:
bin/build-administration.sh
bin/console cache:clearConfiguración
Ajustes globales
Desde Extensiones → Mis extensiones → DfProforma → Configurar, accede a los siguientes ajustes:
- Validez por defecto — Número de días durante los cuales el enlace de aceptación sigue siendo válido (30 por defecto). Cada presupuesto puede sobrescribir este valor individualmente.
- Auto-conversión al pago — Activada por defecto. Desactívela si desea conservar el control manual de la transición Aceptado → Convertido.
- Nombre del remitente — Nombre mostrado como remitente de los emails transaccionales (por defecto: el nombre del sales-channel).
- Acento de marca del PDF — Color de acento utilizado en la plantilla PDF incluida (banda de cabecera, línea separadora, badge de estado).
Configuración por sales-channel
Los ajustes anteriores pueden sobrescribirse por sales-channel en Ajustes → Sales channels → [su canal] → Configuración del plugin. Útil si gestiona varias tiendas con políticas de validez diferentes (por ejemplo 30 días para B2C, 60 días para B2B).
Generar un presupuesto pro forma
Desde la ficha del pedido (admin)
- Abra un pedido en Pedidos → Vista general
- Haga clic en la pestaña Pro forma (junto a Documentos)
- Haga clic en Generar presupuesto pro forma
- Se crea el PDF, el presupuesto aparece en la lista con un número
PF-…y el estado Borrador
Desde el API admin
Se exponen tres endpoints para integrar la generación en sus flujos externos:
POST /api/_action/df-proforma/generate
Body: { "orderId": "…" }
POST /api/_action/df-proforma/mark-sent
Body: { "proformaId": "…" }
GET /api/_action/df-proforma/by-order/{orderId}Autenticación OAuth2 admin estándar de Shopware. Útil para conectar DfProforma con un CRM externo o un pipeline de automatización.
Enviar un presupuesto al cliente
Email transaccional
Desde la lista de presupuestos (pestaña Pro forma de la ficha del pedido), haga clic en el icono del sobre junto al presupuesto. El módulo:
- Pasa el presupuesto al estado Enviado (con marca de tiempo)
- Envía un email al cliente vía el Mail Service Shopware, usando la plantilla
df_proforma_sent, en el idioma del sales-channel - Adjunta el PDF del presupuesto e incluye la URL pública de aceptación
- Emite el evento
ProformaGeneratedEvent(disparador Flow Builder)
URL pública de aceptación
Cada presupuesto enviado lleva una URL de la forma:
https://su-tienda.com/proforma/accept/{token}El token está cifrado y firmado con HMAC-SHA256 usando la clave secreta de Shopware (APP_SECRET / kernel.secret). Imposible de falsificar o adivinar. La URL caduca tras la validez del presupuesto (30 días por defecto).
Página pública de aceptación del cliente
El cliente abre la URL — sin cuenta Shopware necesaria (la página omite la autenticación estándar de cuenta de cliente). Ve:
- Un resumen limpio del pedido: líneas, precios, IVA, totales, condiciones
- Un botón principal Aceptar este presupuesto
- Un botón secundario Rechazar con motivo
- La validez mostrada («Válido hasta el 20/06/2026»)
En la aceptación:
- Firma con marca de tiempo al milisegundo y persistida en base de datos
- Dirección IP del cliente persistida como prueba
- Estado pasa a Aceptado con historial de transición marcado
- Evento
ProformaAcceptedEventdespachado a Flow Builder
En caso de rechazo, el campo Motivo es obligatorio — útil para sus comerciales que pueden recontactar al cliente con una contrapropuesta.
@DfProforma/storefront/page/account/proforma/quote.html.twig desde su tema.
Flujo de estados
Seis estados cubren todo el ciclo de vida de un presupuesto:
- Borrador — Presupuesto creado pero aún no enviado al cliente
- Enviado — Email enviado, esperando respuesta del cliente
- Aceptado — El cliente hizo clic en Aceptar en la página pública
- Rechazado — El cliente hizo clic en Rechazar con motivo
- Caducado — Validez superada sin respuesta (transición automática vía scheduled task)
- Convertido — Pedido subyacente pagado, conversión automática
Cada transición se persiste con marca de tiempo al segundo, identificador del actor, tipo de disparador (comercial, cliente, sistema, pago) y payload JSON para metadatos libres. Puede reconstruir el historial exacto de cualquier presupuesto en cualquier momento.
Auto-conversión al pago
El módulo registra un Subscriber en el evento order_transaction.state.paid de la máquina de estados de Shopware. Cuando una transacción pasa a pagada (Stripe, transferencia bancaria, PayPal, etc.), el Subscriber:
- Busca todos los presupuestos pro forma en estado Aceptado vinculados al pedido
- Los pasa al estado Convertido
- Marca el historial de transición con tipo de disparador pago
Sin intervención humana, sin cron, sin retraso. Sus informes comerciales se mantienen consistentes sin esfuerzo.
Flow Builder — eventos Business Event
El módulo emite dos eventos estándar Shopware Business Event:
ProformaGeneratedEvent— Al generar un presupuesto (implementaBusinessEventInterface)ProformaAcceptedEvent— A la aceptación del cliente (implementaBusinessEventInterface)
Ambos aparecen automáticamente en la lista de disparadores del Flow Builder Shopware nativo. Puede conectar cualquier acción Flow:
- Notificación Slack al equipo de ventas al aceptar
- Email resumen interno al comercial responsable
- Webhook a su CRM (HubSpot, Salesforce, Pipedrive…)
- Actualización de campo personalizado en el cliente (por ejemplo, etiqueta
quote-accepted) - Notificación push móvil vía un servicio de terceros
Sin intervención en el código del módulo — todo se configura desde Ajustes → Shop → Flow Builder.
Personalización de la plantilla PDF
El PDF del presupuesto se renderiza vía DocumentFileRendererRegistry (el nuevo sistema de renderizado de archivos de Shopware 6.7), a partir de la plantilla Twig @DfProforma/documents/proforma.html.twig incluida en el módulo.
Para personalizarla, cree un plugin personalizado o sobreescríbala desde su tema respetando la jerarquía estándar de plantillas Twig de Shopware:
custom/plugins/YourTheme/src/Resources/views/documents/proforma.html.twigLa plantilla incluida expone estos bloques Twig identificados:
- Cabecera con logo y datos de la empresa
- Bloque de cliente
- Resumen de líneas del pedido
- Totales HT/TTC con desglose de IVA
- Banda de resumen al pie (número PF, fechas de emisión y caducidad)
- Marca de agua PRO FORMA
- Acento de marca configurable vía
config.accentColor
Variables disponibles en la plantilla: order (OrderEntity cargada con todas sus asociaciones), config (configuración del documento incluyendo documentNumber, documentDate, validUntil, validityDays), context.
Multiidioma
FR, EN, DE y ES se incluyen por defecto, snippets de storefront y admin. Para añadir más idiomas, cree un archivo de snippets por locale en src/Resources/snippet/ siguiendo la convención estándar de Shopware.
Las plantillas de email transaccionales también son multiidioma: la plantilla correcta se selecciona automáticamente según el idioma del sales-channel del cliente en el momento del envío. Puede personalizar las plantillas por idioma desde Ajustes → Shop → Plantillas de email.
API — endpoints admin disponibles
POST /api/_action/df-proforma/generate # Genera un presupuesto para un pedido
POST /api/_action/df-proforma/mark-sent # Marca como enviado (transición manual)
GET /api/_action/df-proforma/by-order/{id} # Lista los presupuestos de un pedidoLas entidades df_proforma también son accesibles vía el API DAL estándar de Shopware (/api/df-proforma) para búsquedas, exportaciones o integraciones avanzadas.
Desinstalación
Por defecto, los datos de negocio se conservan al desinstalar (opción Keep User Data activada). Así preserva el historial de auditoría de los presupuestos emitidos, útil para conformidad y trazabilidad comercial.
Para forzar la eliminación completa (tabla df_proforma, tipo de documento, rango de numeración, plantilla de email), desactive la opción Keep User Data en el prompt de desinstalación.
Solución de problemas
La pestaña Pro forma no aparece en la ficha del pedido
El bundle de administración no se recompiló tras la instalación. Ejecute bin/build-administration.sh y luego bin/console cache:clear.
Error «Unable to find a document generator with type df_proforma»
El tag de servicio del renderer no es correcto — este bug se corrigió desde la 1.0.2. Asegúrese de usar una versión del plugin ≥ 1.0.2.
Error «Call to undefined method Context::getSalesChannelId()»
Causa histórica: firma antigua del constructor RenderedDocument. Corregido en 1.0.4. Actualice a 1.0.6.
Error Twig «Cannot rewind a generator that was already run»
Corregido en 1.0.6 — la plantilla se adaptó para no consumir dos veces un generador procedente de |filter().
El cliente recibe el email pero la URL de aceptación devuelve un 404
Verifique que el sales-channel Storefront esté correctamente registrado como dominio del canal de ventas utilizado para el pedido. La ruta pública /proforma/accept/{token} está registrada en el Storefront — no funciona si accede a la URL vía el dominio admin.
La caducidad automática no funciona
Verifique que los message workers de Shopware estén en ejecución en segundo plano (bin/console messenger:consume o vía un supervisor tipo systemd/supervisord). La caducidad pasa por la cola de mensajes estándar de Shopware.
Soporte y actualizaciones
12 meses de actualizaciones incluidas (compatibilidad Shopware, correcciones de errores, adiciones funcionales menores). Soporte por email en francés e inglés en 24 horas laborables. Código fuente PHP entregado en texto plano, conforme PSR-4, auditable y modificable.
Para cualquier pregunta o incidencia: contact@datafirefly.com.