Custom Checkout Fields: documentación

Presentación

DataFirefly Custom Checkout Fields añade campos personalizados al proceso de pedido y al formulario de registro de PrestaShop 8 y 9: número de orden de compra, fecha de entrega deseada, SIRET, sector de actividad, archivo adjunto o cualquier otro campo que cree. Los valores se comprueban antes de validar el pedido y luego aparecen en la ficha del pedido, la factura PDF, el albarán, los correos, las listas del back office, las exportaciones CSV y el webservice.

Instalación

1. En el back office, abra Módulos > Gestor de módulos y haga clic en Subir un módulo.
2. Seleccione el archivo dfcheckoutfields.zip.
3. La instalación crea tres tablas, la carpeta protegida upload/dfcheckoutfields, los menús Pedidos > Campos personalizados y Pedidos > Exportar campos, y cinco campos listos para usar.
4. Haga clic en Configurar para ajustar las opciones generales.

Para actualizar, suba el nuevo ZIP encima del anterior: los scripts de actualización añaden las nuevas columnas sin tocar sus campos ni los valores guardados.

Campos creados en la instalación

• Número de orden de compra (po_number): texto de 50 caracteres como máximo, guardado en el pedido, visible en la factura, el albarán y como columna de la lista de pedidos.
• Fecha de entrega deseada (desired_date): como pronto hoy + 2 días, solo días laborables.
• Número SIRET (siret): comprobado con la clave de Luhn, guardado en la cuenta de cliente, pedido en el registro y en el pedido, limitado a clientes de Francia.
• Sector de actividad (sector): lista de ocho sectores, guardada en la cuenta de cliente, pedida en el registro.
• Archivo adjunto (attachment): PDF, imágenes y documentos Office, 8 MB como máximo.

Ninguno de estos campos es obligatorio por defecto. Modifíquelos, desactívelos o elimínelos según sus necesidades.

Ajustes generales

Módulos > Gestor de módulos > Campos personalizados de pedido y registro > Configurar.

• Posición del bloque en el proceso de pedido: paso de pago, encima de los métodos de pago (por defecto), o paso de envío, debajo de los transportistas. Un carrito con solo productos virtuales usa siempre el paso de pago.
• Título del bloque: visible en el pedido, las páginas de pedido, los PDF y los correos, por idioma.
• Posición en la factura PDF: encabezado bajo el número de factura, o parte inferior de la factura. Vea Factura y albarán.
• Nota privada si falta un campo obligatorio: añade la lista de campos que faltan a la nota privada del pedido cuando un módulo de pago omite el control.
• Copiar los campos SIRET al SIRET nativo del cliente: mantiene actualizado el campo SIRET de la ficha del cliente, usado por el modo B2B de PrestaShop.

Crear o modificar un campo

Pedidos > Campos personalizados, luego Añadir un campo o el lápiz de una fila. El formulario solo muestra las opciones útiles para el tipo y el almacenamiento elegidos.

Campo

• Etiqueta, texto de ejemplo y texto de ayuda: por idioma. Un idioma vacío usa la etiqueta del idioma por defecto.
• Código: identificador técnico en minúsculas, cifras y guiones bajos. Sirve también como variable de correo {dfcf_CODE} y en el webservice.
• Tipo: texto, texto multilínea, número, correo electrónico, fecha, lista desplegable, casilla, SIRET o archivo.
• Guardado en: Pedido (un valor por pedido) o Cuenta de cliente (valor conservado en la ficha del cliente, precargado en el pedido y copiado en cada pedido).
• Opciones de la lista: una opción por línea con el formato clave|Etiqueta, por ejemplo industry|Industria. Mantenga las mismas claves en todos los idiomas.

Dónde y cuándo

• Mostrar en el registro y obligatorio en el registro: solo campos de la cuenta de cliente, sin el tipo archivo. También aparecen en el formulario Mis datos personales.
• Mostrar en el pedido y obligatorio en el pedido.
• Mostrar solo si: vea Visualización condicional.
• Países: país de la dirección de facturación en el pedido, del visitante en el registro. Vacío para todos los países.
• Grupos de clientes: todo sin marcar para todos los grupos.

Validación

• Longitud máxima: 0 para el valor por defecto (255 caracteres, 2000 en multilínea).
• Patrón de validación: expresión regular sin delimitadores, por ejemplo ^[A-Z]{2}[0-9]{6}$.
• Plazo mínimo y plazo máximo en días para una fecha guardada en el pedido.
• Solo días laborables: rechaza sábado y domingo.
• Días de cierre: uno por línea, 2026-12-24 para un día, 2026-08-01:2026-08-21 para un periodo, 12-25 para todos los años.
• Extensiones permitidas y tamaño máximo para un archivo. Los scripts y ejecutables se rechazan siempre.

Documentos y exportaciones

Mostrar al cliente (confirmación, cuenta de cliente, correos al cliente), en la factura PDF, en el albarán, como columna filtrable de las listas del back office, en las exportaciones CSV.

Lista de campos

Los iconos de la lista activan o desactivan un ajuste con un clic. Arrastre las filas para cambiar el orden. La acción Duplicar crea una copia desactivada con el código code_copy. Un campo con valores en pedidos no se puede eliminar: desactívelo para conservar el historial.

Visualización condicional

Ejemplo: mostrar el SIRET solo a las empresas.

1. Cree un campo Casilla guardado en la cuenta de cliente, código is_company, etiqueta Soy una empresa.
2. Edite el campo SIRET, sección Dónde y cuándo, y elija Mostrar solo si: Soy una empresa. Deje vacío «tiene uno de estos valores»: para una casilla significa marcada.

Para una lista desplegable, indique las claves esperadas separadas por comas, por ejemplo health,public. Las condiciones se encadenan: un campo cuyo campo padre está oculto también se oculta. Un campo oculto nunca es obligatorio y su valor no se conserva. El campo padre debe mostrarse en el mismo lugar (registro o pedido) o estar ya rellenado en la cuenta de cliente.

Lado del cliente

En el pedido

El bloque aparece en el paso elegido. Cada valor se guarda mientras el cliente escribe. Mientras un campo obligatorio esté vacío o no sea válido, el clic en Realizar pedido (o Continuar en el paso de envío) queda bloqueado, el mensaje aparece bajo el campo y la página se desplaza hasta él. El archivo adjunto se envía arrastrando o con un clic, con barra de progreso. El cliente puede quitarlo y enviar otro.

En el registro y en Mis datos personales

Los campos de la cuenta de cliente marcados Mostrar en el registro se añaden al formulario nativo de creación de cuenta, al formulario de invitado del pedido y a Mis datos personales. Los errores se muestran como los de los campos de PrestaShop.

Después del pedido

Los valores marcados Mostrar al cliente aparecen en la página de confirmación y en el detalle del pedido de la cuenta de cliente. El cliente dueño del pedido puede descargar allí el archivo adjunto.

Factura y albarán

Parte inferior de la factura: el módulo usa el hook displayPDFInvoice e imprime una tabla después de los totales. No se modifica ningún archivo.

Encabezado, bajo el número de factura: PrestaShop no tiene hook en ese lugar. Al guardar este ajuste, el módulo añade un bloque delimitado por {* dfcf:start *} y {* dfcf:end *} al final de themes/SU_TEMA/pdf/invoice.summary-tab.tpl. Si el archivo no existe, se crea a partir del de PrestaShop. Si ya existe, el módulo lo completa y guarda una copia .dfcf-backup. Volver a Parte inferior de la factura o desinstalar retira el bloque. Si el archivo no se puede modificar, un mensaje indica su ruta.

Con DataFirefly Invoice Editor, que sustituye el renderizado de la factura, use Parte inferior de la factura: el editor conserva el contenido de los módulos en la posición que elija.

El albarán usa el hook displayPDFDeliverySlip, campo a campo.

Correos

Hay dos tipos de variables en los correos que contienen el ID del pedido, entre ellos order_conf y new_order:

• {dfcf_fields}: todos los valores en una tabla. En order_conf solo se incluyen los campos marcados Mostrar al cliente. En new_order, destinado al comerciante, se incluyen todos.
• {dfcf_CODE}: un solo valor, por ejemplo {dfcf_po_number} o {dfcf_desired_date}.

Añádalas en Diseño > Tema de correo electrónico, o en los archivos de correo de su tema.

Back office

• Página del pedido: tarjeta Campos personalizados con todos los valores. El botón Editar permite corregir un valor o sustituir el archivo adjunto.
• Ficha del cliente: tarjeta con los campos de la cuenta de cliente, editable de la misma forma.
• Listas: cada campo marcado como columna filtrable aparece en la lista de pedidos con un filtro de texto. Los campos de la cuenta de cliente también aparecen en la lista de clientes.

Exportación CSV

Pedidos > Exportar campos. Elija Pedidos o Clientes, el periodo, los estados de pedido (todo sin marcar para todos), el separador y si solo se exportan las filas con al menos un valor. El archivo está en UTF-8 con BOM y se abre directamente en Excel. Los pedidos se exportan con referencia, fecha, estado, cliente, totales sin y con IVA y moneda, seguidos de los campos marcados Incluir en las exportaciones CSV.

Webservice

1. Parámetros avanzados > Webservice: active el webservice y cree o edite una clave.
2. Marque GET en el recurso dfcf_values.
3. Llame a /api/dfcf_values?filter[id_order]=[123]&display=full.

Cada valor se devuelve con id_dfcf_field, id_order, id_customer, id_cart, value, value_display, field_code, field_label y has_file. Los valores del perfil de cliente tienen id_order e id_cart a 0.

Archivos adjuntos y seguridad

Cada archivo se comprueba por su extensión (lista del campo) y por su contenido real: un script renombrado a .pdf se rechaza. Se guarda en upload/dfcheckoutfields con un nombre aleatorio y sin extensión, en una carpeta cuyo acceso directo prohíbe un archivo .htaccess. En Nginx, añada la regla location ^~ /upload/dfcheckoutfields/ { deny all; }. La descarga pasa siempre por el módulo, que comprueba que el visitante es el cliente del pedido o un empleado.

RGPD

Los valores guardados en una cuenta de cliente se eliminan con el cliente. El módulo responde a las solicitudes de exportación y eliminación del módulo RGPD oficial de PrestaShop. Los valores copiados en los pedidos se conservan con el pedido.

Solución de problemas

El bloque no aparece en el pedido

Compruebe que el campo está activo, marcado Mostrar en el pedido, y que el grupo y el país del cliente corresponden a sus restricciones. Si eligió el paso de envío, compruebe que su tema llama al hook displayAfterCarrier.

El botón Realizar pedido no se bloquea

El módulo reconoce el botón de los temas Classic y Hummingbird. Un tema que sustituye ese botón por otro elemento, o un pago exprés lanzado desde la ficha de producto, no está cubierto: active la nota privada para recibir aviso de los pedidos incompletos.

Los campos no aparecen en el encabezado de la factura

Compruebe que el archivo pdf/invoice.summary-tab.tpl del tema se puede modificar, guarde de nuevo los ajustes y vacíe la caché en Parámetros avanzados > Rendimiento.

Una variable de correo aparece tal cual

Solo se rellena en los correos que contienen el ID del pedido. Compruebe también que el código coincide exactamente con el del campo.