Documentación de Withdrawal Button

Pasos de instalación y una referencia completa para cada campo y función del panel de administración, con ejemplos concretos — el mismo nivel de detalle que usa nuestro soporte para ayudar a los clientes.

Instalación

Requisitos

Magento 2.4.x — probado en 2.4.9, compatible con versiones 2.4.* anteriores. PHP 8.1–8.5. Compatible tanto con el tema Luma por defecto como con el tema Hyvä. Requiere que los módulos nativos Magento_ReCaptcha* estén presentes para la protección reCAPTCHA opcional (ya incluidos en el core de Magento).

Pasos de configuración

1. Añade las credenciales que recibirás por email a auth.json en la raíz de tu proyecto Magento:
```
{ "http-basic": { "repo.codingrow.com": { "username": "...", "password": "..." } } }
```
2. composer config repositories.codingrow composer https://repo.codingrow.com
3. composer require codingrow/module-withdrawal-button
4. bin/magento module:enable Codingrow_WithdrawalButton
5. bin/magento setup:upgrade && bin/magento setup:di:compile && bin/magento cache:flush
6. Pega tu clave de licencia en Admin → Stores → Configuration → Codingrow Extensions → Withdrawal Button → License → License Key, guarda, y luego bin/magento cache:flush.
7. Coloca el enlace de solicitud donde los clientes puedan encontrarlo — mira Colocar el widget más abajo.

El formulario frontend completo, los emails y la interfaz de administración están disponibles en 7 idiomas, seleccionados automáticamente según el idioma de la tienda/administración:

Desinstalación

composer remove codingrow/module-withdrawal-button y luego bin/magento setup:upgrade && bin/magento setup:di:compile && bin/magento cache:flush. Las solicitudes ya registradas en codingrow_withdrawalbutton_request nunca se eliminan automáticamente — exporta primero la cuadrícula si necesitas conservar un registro.

Guía de usuario

La página de solicitud de desistimiento

Una página, dos pasos, exactamente como exige la directiva de referencia: el cliente primero rellena los campos fijos (nombre, email, número de pedido, fecha de recepción) más los campos personalizados habilitados, ve un resumen de solo lectura de todo lo introducido, y solo entonces confirma en un botón final independiente. Los campos ocultos que trasladan los datos entre los dos pasos se revalidan en el servidor al confirmar — un cliente nunca puede saltarse las comprobaciones forzando directamente el paso "confirmado".

Verificación del pedido

Antes de aceptar una solicitud, el módulo comprueba que el número de pedido realmente existe y que la dirección de email coincide con la de ese pedido (sin distinguir mayúsculas/minúsculas, funciona tanto para pedidos de invitado como de cliente registrado). Si falla cualquiera de las dos comprobaciones, se muestra el mismo mensaje genérico de "no encontrado" en ambos casos — es deliberado: revelar "email incorrecto" frente a "el pedido no existe" permitiría probar números de pedido válidos por ensayo y error.

Estado del pedido y plazo de desistimiento

Dos ajustes en Stores → Configuration → Codingrow Extensions → Withdrawal Button → General controlan qué solicitudes se aceptan, además de la verificación obligatoria de pedido/email descrita arriba.

Order statuses eligible for withdrawal — una multiselección nativa de Magento (Pending / Processing / Complete / Closed / Canceled / On Hold). Una solicitud solo se acepta si el estado actual del pedido es uno de los seleccionados; preseleccionados en la instalación en Pending, Processing, Complete, Closed y On Hold. Dejar la lista vacía bloquea todas las solicitudes independientemente del estado del pedido — una elección explícita del comerciante, no un error.
Withdrawal period (days) — cuántos días se permiten entre la fecha de recepción declarada y el momento en que se envía la solicitud (14 por defecto, el mínimo previsto por la normativa de la UE sobre desistimiento). Transcurrido ese plazo la solicitud se rechaza con un mensaje que invita al cliente a contactar directamente con la tienda; la columna de días transcurridos en la cuadrícula de administración marca las solicitudes que superan ese mismo límite.

Prevención de solicitudes duplicadas

Un pedido solo puede tener una solicitud de desistimiento activa, independientemente de su estado — incluso una "Rechazada". Un cliente que no esté de acuerdo con un rechazo no puede simplemente reenviar la misma solicitud para evitarlo; si hace falta una excepción real, el administrador elimina antes la solicitud anterior de la cuadrícula.

Fecha de recepción y días transcurridos

El plazo de desistimiento (configurable, 14 días por defecto) comienza desde que se recibió la mercancía, no desde la fecha de compra o factura — una información que Magento no puede conocer por sí solo, ya que depende del transportista. El formulario la solicita con un selector de fecha HTML5 nativo (sin dependencia de jQuery UI que pudiera entrar en conflicto con un tema), limitado para que no se pueda introducir una fecha futura. La fecha del pedido se lee automáticamente del pedido vinculado — el cliente nunca tiene que escribirla. Ambas fechas, más los días transcurridos desde la recepción, se muestran en la cuadrícula de administración (marcados al superar ese plazo) y están disponibles como variables de email.

Constructor de campos personalizados

Además de los cuatro campos exigidos por ley (nombre, email, número de pedido, fecha de recepción — siempre obligatorios, nunca eliminables), puedes añadir un número ilimitado de campos propios desde Stores → Configuration → Codingrow Extensions → Withdrawal Button → Custom Fields: etiqueta, tipo, si es obligatorio, y si se muestra actualmente en el formulario — el orden de las filas en esa lista es el orden de visualización en el formulario.

Tipo	Se muestra como
Texto	Campo de una línea
Área de texto	Cuadro multilínea
Desplegable	Un `<select>` con las opciones que escribas, una por línea
Casilla	Una única casilla (p. ej. "Todavía tengo el embalaje original")

Ejemplo — un campo Desplegable obligatorio "Motivo de la devolución" con opciones "Defectuoso / No coincide con la descripción / Cambié de opinión": los clientes deben elegir uno antes de poder enviar, y el valor elegido aparece en la columna "Campos personalizados" de la cuadrícula de administración y en ambos emails de notificación.

Los valores enviados para un campo que se deshabilita más tarde se conservan en el historial de la solicitud y se siguen mostrando donde se registraron — solo la etiqueta del campo se recalcula por ID, así que renombrar un campo después actualiza la etiqueta en todos los sitios donde se muestran también sus respuestas anteriores.

Colores y texto del botón

Dos campos de color hexadecimal (texto y fondo) te permiten adaptar el botón a tu marca — solo cambian los colores; la forma, el padding y la fuente siempre siguen los del tema que uses (Luma o Hyvä), así el botón nunca puede quedar visualmente roto. Un valor hexadecimal no válido simplemente se ignora, volviendo al color por defecto del tema. El texto del botón también es configurable, mostrado exactamente como se escribe (mayúsculas y minúsculas preservadas, sin capitalización automática) — déjalo vacío para mantener la etiqueta traducida por defecto.

Protección reCAPTCHA

Withdrawal Button se registra como formulario protegible en el sistema reCAPTCHA nativo de Magento — Stores → Configuration → Customers → Google reCAPTCHA → Storefront → "Enable for Withdrawal Button". La versión que ya tengas configurada para el resto de la tienda (v2 casilla, v2 invisible, o v3) se aplica automáticamente; no hay ninguna configuración de captcha independiente que mantener.

Cuadrícula de administración y acciones masivas

Cada solicitud aparece en Codingrow Extensions → Withdrawal Button, paginada y filtrable, con columnas para número de pedido, cliente, fecha de recepción, días transcurridos (marcados al superar 14), valores de los campos personalizados y estado. Las acciones masivas permiten actualizar el estado de varias solicitudes seleccionadas a la vez, o eliminar filas para limpiar datos de prueba.

Estado	Significado
Pendiente	Recién enviada, aún no revisada.
En proceso	Siendo gestionada por la tienda.
Completada	Devolución/reembolso finalizado.
Rechazada	La tienda ha rechazado la solicitud.
Cancelada	El cliente retiró su propia solicitud.

Plantillas de email y variables

Dos plantillas de email nativas de Magento — un recibo al cliente (la confirmación en soporte duradero exigida por ley) y una notificación interna al administrador — enviadas automáticamente mediante TransportBuilder, exactamente igual que los emails de pedido propios de Magento. Clona cualquiera de las dos desde Marketing → Email Templates, edita el texto con el editor WYSIWYG nativo, y luego selecciona tu copia en Configuration → Email Templates — sin código de plantillas personalizado involucrado.

Variable	Contenido
`order_increment_id`	El número de pedido
`order_date`	La fecha del propio pedido, leída automáticamente
`receipt_date`	La fecha en que el cliente declaró haber recibido la mercancía
`days_since_receipt`	Días transcurridos desde esa fecha
`request_id`	Número de referencia interno de esta solicitud
`submitted_at`	Fecha y hora exactas en que se confirmó la solicitud
`custom_fields_text`	Todos los campos personalizados rellenados, formateados como líneas "Etiqueta: valor"

Etiqueta de devolución en PDF

Un simple justificante opcional (logo, nombre del remitente, dirección de devolución, instrucciones de embalaje) generado internamente con Zend_Pdf — la misma biblioteca PDF que usa el propio core de Magento para facturas y envíos, sin ninguna dependencia de terceros añadida — y adjuntado automáticamente al email de recibo del cliente una vez habilitado en Configuration → Return Label. Sube un logo, rellena la dirección de devolución y cualquier instrucción de embalaje, y cada futuro email de confirmación de solicitud llevará una etiqueta lista para imprimir con el número de referencia, número de pedido, nombre del cliente y fecha de recepción de esa solicitud, además de los campos personalizados que el cliente haya rellenado.

El enlace de solicitud nunca está fijado en el tema — se coloca exclusivamente mediante el sistema nativo de Widgets de Magento, así el comerciante controla totalmente si aparece, y dónde. Dos formas de hacerlo, según lo ampliamente que quieras mostrarlo:

Método	Ideal para
Content → Elements → Widgets	Mostrar el enlace en muchas/todas las páginas a la vez, o en una posición fija del diseño (footer, barra lateral) en todo el sitio.
Insert Widget dentro del contenido de una página CMS	Colocarlo en una sola página específica — p. ej. la home — exactamente donde quieras dentro del contenido de esa página, sin afectar a ninguna otra.

En todo el sitio, mediante Content → Elements → Widgets:

1. Content → Elements → Widgets → Add Widget, elige el widget de enlace de Withdrawal Button.
2. Asígnalo a "All Pages" o "Specified Page(s)" y establece el contenedor de visualización (p. ej. content o sidebar.additional) — en temas Hyvä, el contenedor "Footer" puede no estar disponible en el selector de widgets; en ese caso usa el área de contenido principal, justo antes del footer.
3. Guarda y recarga las páginas de destino — no hace falta vaciar la caché para una instancia de widget recién guardada.

En una sola página específica, p. ej. la home:

1. Content → Pages, abre la página (p. ej. "Home page").
2. En el editor WYSIWYG de la pestaña Content, coloca el cursor donde quieras el botón y haz clic en Insert Widget.
3. Elige el widget de enlace de Withdrawal Button, define su texto de etiqueta y clase CSS, y luego Insert — esto inserta una directiva {{widget type="Codingrow\WithdrawalButton\Block\Widget\Link" ...}} directamente en el contenido de esa página, sin afectar a las demás.
4. Guarda la página.

Nota: el widget es la única forma soportada de mostrar el enlace — el módulo nunca lo inyecta automáticamente en el footer ni en ninguna otra plantilla, ya que el comerciante puede legítimamente querer colocarlo en otro sitio (una página de pedidos, una página CMS dedicada, una categoría de producto específica) o no mostrarlo en absoluto en todo el sitio.

Licencia

Sin una clave de licencia válida, la página de desistimiento permanece visible (un comerciante nunca debe quedarse sin el botón legalmente exigido solo porque una licencia haya caducado) pero los nuevos envíos se bloquean hasta que se introduce una clave en Configuration → License → License Key.