Skip to main content
El módulo de Finseed muestra un recuadro en el paso de pago para la captura del NIF. Esta guía está pensada para desarrolladores de temas y agencias. Explica qué nombres del recuadro son estables, cómo cambiar su aspecto en cada nivel de esfuerzo y qué debe conservar una plantilla propia para no romper la captura.

​
Dónde se muestra el recuadro

El recuadro se muestra en el paso de pago, encima de los métodos de pago, a través del punto de enganche displayPaymentTop, en PrestaShop 1.7.7 y posteriores con el tema Classic, y también con el tema Hummingbird de PrestaShop 9. No usa JavaScript: la línea se despliega con un elemento <details> y el formulario se envía con un <form> normal. El módulo registra una hoja de estilos pequeña en todas las páginas de la tienda, con prioridad 200. PrestaShop carga el theme.css del tema con prioridad 50 y el custom.css del tema con prioridad 1000, de menor a mayor, y a igual especificidad gana la regla cargada en último lugar, así que una regla de tu custom.css con la misma especificidad que la nuestra gana por orden de carga.

​
Cómo se ve el recuadro en cada estado

  • La línea de oferta (offer). Una línea plegada, con una flecha y la acción subrayada como un enlace: «¿Necesitas factura con tus datos fiscales? · Añadir». Al desplegarla aparece el formulario.
  • La línea de confirmación o de revisión (offer). La misma línea cuando la dirección ya aporta un identificador: «¿Necesitas factura con el NIF 12345678Z a nombre de Ana García? · Sí / Cambiar» si es válido. Cuando el identificador de la dirección no supera la comprobación, la línea dice «El NIF 12345678Z de tu dirección no sirve para la factura · Revisar». La acción («Añadir», «Sí / Cambiar» o «Revisar») es un único <span> dentro de la línea; toda la línea, el <summary>, es la zona en la que se puede pulsar.
  • El estado obligatorio (required). El recuadro aparece abierto, sin línea plegable, con un borde izquierdo de color de aviso y la frase en negrita «Para compras superiores a 3.000 € es obligatorio indicar el NIF. Los métodos de pago aparecerán cuando lo indiques.» El importe es el límite configurado en Finseed. Los métodos de pago quedan ocultos hasta que el cliente indica un identificador válido.
El atributo data-finseed-state del elemento raíz tiene dos valores, offer y required. Los dos primeros estados comparten el valor offer y se diferencian solo por el texto de la línea.

​
Cómo es el marcado del recuadro

Así es el marcado que escribe la plantilla del módulo en la línea de oferta, reducido a su estructura. El módulo se llama finseed, y ese es el nombre que aparece en las rutas de los niveles 2 y 3.
El mensaje de rechazo, el atributo aria-describedby y el enlace a la dirección solo se escriben cuando hay algo que mostrar, y los dos desplegables solo cuando finseed_needs_document_type es verdadero; cuando no se escriben, el formulario no envía esos campos. El <details> lleva el atributo open cuando finseed_open es verdadero. En el estado obligatorio no hay <details>: el elemento raíz contiene un <p class="finseed-tax-id__rule"> con la frase, después el mismo formulario y, al final, el bloque <style> de la sección el estilo en línea del estado obligatorio.

​
Los nombres estables

Estos nombres se mantienen hasta la versión 2.0.0 del módulo. Cambiar cualquiera de ellos es un cambio de versión mayor, anunciado en las notas de la versión.

​
Elemento raíz y atributo de estado

​
Clases de los elementos

El campo de texto y los desplegables llevan además la clase form-control del tema, los desplegables también form-select, y el botón btn btn-primary. El recuadro no usa ninguna clase de utilidad de Bootstrap.

​
Nombres de los campos e identificadores

El mensaje de rechazo lleva el identificador finseed-tax-id-error, al que apunta el atributo aria-describedby del campo de texto.

​
Plantilla y variables

La plantilla es views/templates/hook/checkout_tax_id_block.tpl. Recibe estas variables: Todas las variables de texto llegan sin escapar. La plantilla del módulo escapa cada una al escribirla con escape:'html':'UTF-8'; una plantilla propia debe hacer lo mismo.

​
Identificador y ruta de la hoja de estilos

​
Variables CSS

La hoja de estilos lee cinco variables CSS y nunca las declara, así que un valor que definas en body llega al recuadro por herencia. En cada uso, la hoja toma primero tu variable; si no está definida, la variable de Bootstrap del tema que se indica; y si tampoco existe, el valor fijo. Las variables de Bootstrap existen en Hummingbird, que las define con un valor claro y otro oscuro; Classic no define ninguna, así que en Classic se usa el valor fijo. Un valor de otro tipo no es válido y deja sin valor la declaración completa en la que se usa, como si fuera unset. Por ejemplo, con 1px solid #ccc en --finseed-tax-id-border-color el marco desaparece, porque la variable se usa dentro de la declaración border.

​
El estilo en línea del estado obligatorio

En el estado obligatorio, la plantilla escribe este bloque, que oculta los métodos de pago:
Ese bloque y su lista de selectores también son estables. Sus declaraciones llevan !important, así que una regla de tu custom.css o de una hoja de sustitución no lo anula salvo que también lleve !important y tenga mayor especificidad; una regla así, en PrestaShop 1.7, deja pagar sin el NIF. Lo que oculta se cambia con una plantilla propia. Los selectores corresponden al marcado de los métodos de pago de los temas que incluye PrestaShop. En PrestaShop 8 y 9 el servidor retira además los métodos de pago a partir de la petición siguiente a la primera vez que el recuadro se muestra; hasta entonces los oculta este bloque. En PrestaShop 1.7 es lo único que impide pagar sin el NIF que exiges; un pedido que lo evite llega a Finseed sin los datos fiscales y queda retenido, como explica cuándo el NIF es obligatorio. Si tu tema usa otro marcado para los métodos de pago, nada los oculta en PrestaShop 1.7, ni en esa primera petición en PrestaShop 8 y 9, y tu plantilla propia debe ocultar los tuyos.

​
Los niveles de personalización

En orden de esfuerzo, de menor a mayor.

​
1. Solo CSS

Es el nivel que sirve para casi cualquier cambio visual y no rompe la captura, mientras el recuadro siga visible: si lo ocultas con CSS, el módulo lo da por mostrado, así que un cliente que no lo ve cuenta como si hubiera ignorado la pregunta y, por encima del límite, se queda sin métodos de pago y sin formulario. Tiene dos formas:
  • Definir las variables CSS en body, en el custom.css de tu tema:
  • Escribir reglas en el custom.css de tu tema, con una clase del recuadro o con el identificador raíz como prefijo. Nuestra hoja usa por selector una clase, o una clase más un atributo (data-finseed-state o [open]), sin !important ni identificadores, así que una regla tuya con la misma forma gana por orden de carga. Una regla que empiece por #finseed-checkout-tax-id gana frente a cualquier regla de nuestra hoja, en cualquier orden.
Tres reglas de nuestra hoja llevan un atributo, y una regla tuya con una sola clase no las supera. Para cambiarlas, reproduce la misma forma de selector: Esa es la forma de los selectores en la hoja actual. Lo estable son los nombres que usan; cómo está dibujada la flecha (el pseudoelemento y sus propiedades) no lo es y puede cambiar en cualquier versión.

​
2. Sustituir la hoja de estilos

Un archivo en themes/<tu tema>/modules/finseed/views/css/checkout-tax-id.css sustituye a nuestra hoja por completo. PrestaShop busca la ruta primero en el tema, después en el tema padre y por último en el módulo. Si el archivo no existe, no cambia nada. Un archivo vacío elimina todo el estilo del módulo. Parte de una copia de la hoja del módulo, views/css/checkout-tax-id.css, y cambia lo que necesites. Tres cosas a tener en cuenta:
  • En el tema Classic, un archivo vacío deja el recuadro sin flecha, sin cursor de enlace y sin marco: el theme.css de Classic muestra <summary> como un bloque sin marcador. Tu copia debe aportar esos estilos.
  • Los elementos que añadamos en versiones posteriores llegan sin estilo hasta que actualices tu copia. Cada nuevo elemento se anuncia en las notas de la versión.
  • Con la opción de combinar las hojas CSS (CCC) activada en la página de rendimiento de PrestaShop, una hoja modificada en la misma ruta se sirve sin cambios hasta que vacías la caché desde esa misma página.

​
3. Sustituir la plantilla

Un archivo en themes/<tu tema>/modules/finseed/views/templates/hook/checkout_tax_id_block.tpl sustituye a nuestra plantilla. PrestaShop busca en el tema, después en el tema padre y por último en el módulo. Este nivel permite cambiar la estructura del recuadro y sus textos, con las condiciones de la sección qué debe conservar una plantilla propia. Parte de una copia de la plantilla del módulo. PrestaShop sirve una copia compilada de la plantilla, así que tu archivo se aplica cuando vacías la caché de plantillas, salvo que la tienda esté configurada para recompilarlas al cambiar.

​
4. Mover el recuadro a otro punto del checkout (no soportado)

No está soportado. Si desenganchas el módulo del punto displayPaymentTop, el recuadro desaparece; en PrestaShop 8 y 9 el bloqueo de los métodos de pago deja de actuar, y en PrestaShop 1.7 no queda ningún bloqueo. El módulo no ofrece hoy una forma de mostrar el recuadro en otro punto del checkout.

​
Qué debe conservar una plantilla propia

Una plantilla que sustituye a la nuestra debe mantener:
  • El identificador raíz finseed-checkout-tax-id y el atributo data-finseed-state con el valor de finseed_state.
  • El campo oculto token, con el valor de finseed_front_token.
  • Los cuatro nombres de campo: token y tax_id en todos los estados; document_type e issuing_country cuando finseed_needs_document_type es verdadero, como hace la plantilla del módulo.
  • El formulario con method="post" y la URL de finseed_endpoint_url como destino.
  • El bloque <style> de la sección el estilo en línea del estado obligatorio, escrito cuando finseed_hide_payment_options es verdadero, con los selectores adaptados a tu marcado si difiere del de los temas de PrestaShop.
Las clases y los demás identificadores no son necesarios para la captura, pero sin ellos nuestra hoja de estilos no se aplica al recuadro. Dos formas de romper la captura:
  • Una plantilla que devuelve una cadena vacía en cualquiera de los estados desactiva el bloqueo de los métodos de pago en ese carrito: el módulo entiende que el recuadro no llegó al cliente y no retiene el pago.
  • Una plantilla que omite el bloque <style> elimina todo el bloqueo en PrestaShop 1.7.

​
Qué prometemos y qué puede cambiar

Los nombres de la sección Los nombres estables y el bloque <style> del estado obligatorio con su lista de selectores se mantienen hasta la versión 2.0.0 del módulo. No prometemos los textos, la estructura de elementos más allá de los listados, cómo está dibujada la flecha ni los valores de espaciado: pueden cambiar en cualquier versión sin aviso.