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, también con el tema Hummingbird de PrestaShop 9 y en el checkout en una sola página que incluye PrestaShop 9.2. La línea se despliega con un elemento <details> y el formulario se envía con un <form> normal, así que el cliente puede indicar sus datos sin JavaScript. 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.

​
Qué hace el script del recuadro

El módulo registra también un script, views/js/checkout-tax-id.js, en todas las páginas de la tienda. Cuando el navegador lo ejecuta, el script hace lo siguiente:
  • Muestra el campo Empresa solo cuando el cliente es una empresa, y le pone la etiqueta corta «Empresa». Con una dirección en España, el cliente es una empresa cuando escribe un CIF o un número de IVA de la UE sin elegir un tipo de documento. Fuera de España, cuando responde «Empresa» en Compras como.
  • Después del rechazo «Indica el nombre de la empresa.», mantiene visible Empresa mientras el cliente no cambia el identificador.
  • Cuando el cliente responde a Compras como, cambia la etiqueta del campo del identificador, y oculta los desplegables de tipo de documento y país para una empresa.
  • Cuando los desplegables vienen marcados para un documento guardado, los vacía si el cliente escribe otro valor, y los vuelve a marcar si el cliente vuelve al valor guardado. Cuando el cliente elige un tipo o un país, el script deja de tocar los desplegables.
  • En el checkout en una sola página de PrestaShop 9.2, vuelve a dibujar el recuadro cuando el cliente cambia la dirección. Pide al servidor el recuadro para la dirección nueva, a través del controlador checkouttaxidblock del módulo, y lo pone en lugar del anterior.
Sin el script, el recuadro queda como lo dibuja el servidor: el campo Empresa aparece para cualquier cliente, con la etiqueta «Empresa (solo si facturas a una empresa)», la etiqueta del identificador no cambia con la respuesta a Compras como, y el recuadro no cambia cuando el cliente cambia la dirección en el checkout en una sola página. El script solo usa los nombres de la sección qué nombres lee el script del recuadro. Solo oculta grupos: el de Empresa, que encuentra por la clase finseed-tax-id__company, y el de cada desplegable, que encuentra por la clase finseed-tax-id__field. Nunca oculta otro elemento. Así, en una plantilla propia sin esas clases, todos los controles quedan visibles.

​
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). Cuando ya hay un identificador aceptado, de la dirección o indicado antes en el recuadro, la línea dice «¿Necesitas factura con el NIF 12345678Z a nombre de Ana García? · Sí / Cambiar». Cuando el identificador de la dirección no supera la comprobación, la línea dice «El NIF 12345678Z de tu dirección necesita revisión · 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 «Necesitamos tus datos fiscales para emitir la factura. Los métodos de pago aparecerán cuando los indiques.» Debajo del campo del identificador, un texto de ayuda indica el límite configurado en Finseed, por ejemplo «Necesario en compras superiores a 3.000 €». Los métodos de pago quedan ocultos hasta que el cliente indica un identificador que el módulo acepta.
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, con todos los elementos opcionales que puede llevar en ese estado, para una dirección de facturación en otro país de la Unión Europea. Esos elementos nunca aparecen todos a la vez. El módulo se llama finseed, y ese es el nombre que aparece en las rutas de los niveles 2 y 3.
Cada parte opcional se escribe solo cuando su variable lo pide; cuando no se escribe, el formulario no envía ese campo:
  • Los tres campos ocultos declared_for, declared_for_type y declared_for_country, cuando finseed_declared_for no está vacío.
  • El grupo Compras como, cuando finseed_asks_buyer_kind es verdadero.
  • El texto de ayuda del identificador, justo después del campo, cuando finseed_tax_id_help no está vacío. Solo ocurre en el estado obligatorio, como muestra el marcado de abajo.
  • Cada mensaje de rechazo, cuando su variable no está vacía. Con una dirección en España, después del rechazo del identificador, el enlace a la dirección, cuando finseed_address_link_url no está vacía; el ejemplo no lo muestra, porque su dirección está en otro país. El atributo aria-describedby de cada campo nombra los textos de ayuda y de rechazo que ese campo tiene escritos, y el campo con un rechazo lleva además aria-invalid="true".
  • El grupo Empresa, cuando finseed_asks_company_name es verdadero.
  • Los dos desplegables, cuando finseed_needs_document_type es verdadero o finseed_declared_for no está vacío.
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. Así es ese marcado, reducido y con una dirección en España, sin los elementos opcionales del ejemplo anterior:

​
Los nombres estables

Los nombres de esta sección se mantienen hasta la versión 2.0.0 del módulo, como explica qué prometemos y qué puede cambiar.

​
Elemento raíz y sus atributos

​
Clases de los elementos

Los campos 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

Los textos de ayuda y de rechazo llevan estos identificadores, a los que apunta el atributo aria-describedby de su campo:

​
Qué nombres lee el script del recuadro

Además del identificador raíz y de los atributos data-finseed-redraw-url y data-finseed-drawn-for del elemento raíz, el script lee estos atributos: El script lee también:
  • Las clases de grupo finseed-tax-id__company y finseed-tax-id__field.
  • Los identificadores finseed-tax-id, finseed-tax-id-company-name, finseed-tax-id-company-name-error, finseed-tax-id-document-type y finseed-tax-id-issuing-country.
  • Las etiquetas del identificador y de Empresa, que encuentra por su atributo for: label[for="finseed-tax-id"] y label[for="finseed-tax-id-company-name"].
  • Las opciones buyer_kind y los tres campos ocultos declared_for, declared_for_type y declared_for_country.
  • El campo oculto token, en el que escribe el token vigente después de cada nuevo dibujo del recuadro.
Sin el atributo data-finseed-eu-vat-formats en el formulario o sin el identificador finseed-tax-id, el script no cambia nada dentro del recuadro, pero sigue volviendo a dibujarlo.

​
Plantillas y variables

La plantilla del recuadro 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. Cuando el módulo no dibuja el recuadro en un carrito, por ejemplo con Preguntar solo cuando sea obligatorio por debajo del límite, escribe en su lugar la plantilla views/templates/hook/checkout_tax_id_redraw_anchor.tpl: un <div> oculto con los atributos data-finseed-redraw-url y data-finseed-drawn-for, este último vacío. Recibe la variable finseed_redraw_url. Ahí dibuja el script el recuadro cuando un cambio de dirección en el checkout en una sola página lo hace necesario.

​
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 de tu versión. Cuando actualices el módulo, vuelve a partir de la plantilla de la versión nueva y aplica de nuevo tus cambios: una copia antigua no escribe los nombres que la versión nueva añadió, y la sección qué debe conservar una plantilla propia dice qué deja de funcionar sin cada uno. El módulo usa tu plantilla también cuando el script vuelve a dibujar el recuadro. La plantilla del <div> oculto, checkout_tax_id_redraw_anchor.tpl, se sustituye de la misma forma, en la misma carpeta del tema. Una copia debe conservar los atributos data-finseed-redraw-url y data-finseed-drawn-for, este último vacío. Sin data-finseed-redraw-url, el recuadro no aparece cuando un cambio de dirección en el checkout en una sola página lo hace necesario. 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 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 lo siguiente. Cada punto dice qué deja de funcionar sin él.
  • El identificador raíz finseed-checkout-tax-id. Sin él, el script no encuentra el recuadro: no oculta Empresa ni vuelve a dibujar el recuadro.
  • El atributo data-finseed-state con el valor de finseed_state. Sin él, nuestra hoja de estilos no marca el estado obligatorio.
  • Los atributos data-finseed-redraw-url y data-finseed-drawn-for en el elemento raíz, con los valores de finseed_redraw_url y finseed_drawn_for. Sin data-finseed-redraw-url, en el checkout en una sola página de PrestaShop 9.2, un recuadro escrito al cargar la página no cambia cuando el cliente cambia la dirección. Por ejemplo, si el cliente pasa de una dirección en España a una en Francia, el recuadro no pregunta Compras como, el módulo trata al cliente como particular y la factura no sale a nombre de la empresa que indique. Sin data-finseed-drawn-for, el script sustituye el recuadro en la primera actualización del checkout aunque nada haya cambiado, y un mensaje de rechazo mostrado al cargar la página desaparece. Cuando la página se carga sin recuadro, el script guarda la URL del <div> oculto del módulo, y el recuadro que dibuja ahí con tu plantilla se sigue actualizando aunque tu plantilla no escriba esos dos atributos.
  • El formulario con method="post" y la URL de finseed_endpoint_url como destino, y el campo oculto token, con el valor de finseed_front_token. Sin ellos, el módulo no guarda nada de lo que el cliente envía, y el cliente vuelve al paso de pago sin ningún mensaje.
  • El campo tax_id en todos los estados, y los desplegables document_type e issuing_country cuando finseed_needs_document_type es verdadero o finseed_declared_for no está vacío. Sin tax_id, el identificador llega vacío y el módulo rechaza cada envío. Sin los desplegables, el cliente no puede declarar un pasaporte o un documento extranjero. Además, cuando finseed_declared_for no está vacío, Confirmar envía sin declarar el documento que el cliente ya había declarado, y el módulo lo comprueba como si el cliente no lo hubiera declarado: puede rechazarlo o guardarlo con otro tipo.
  • Los campos ocultos declared_for, declared_for_type y declared_for_country dentro del formulario, con los valores de sus variables, cuando finseed_declared_for no está vacío. Sin ellos, el script no sabe para qué valor vienen marcados los desplegables. Si el cliente cambia el valor, el módulo lo comprueba con el tipo y el país marcados para el valor anterior.
  • Las opciones buyer_kind de Compras como, con los valores de finseed_buyer_kind_options, cuando finseed_asks_buyer_kind es verdadero. Sin ellas, el módulo trata como particular a todo cliente con una dirección fuera de España: no guarda ninguna empresa, y la factura toma la de la dirección de facturación, si la tiene.
  • El campo company_name, solo cuando finseed_asks_company_name es verdadero. Sin él, la factura toma la empresa de la dirección de facturación. Con él cuando la variable es falsa, la plantilla pide un nombre que el módulo no guarda.
  • Los mensajes de rechazo: finseed_tax_id_error, finseed_company_name_error y finseed_issuing_country_error, cada uno bajo su campo, o solo finseed_error_message, que lleva el rechazo de cualquier campo. Una plantilla que escribe solo finseed_tax_id_error no muestra «Indica el nombre de la empresa.» ni «Elige el país que expide el documento.»: el cliente ve el formulario de nuevo sin saber qué falta.
  • Los nombres que lee el script: los atributos data-finseed-eu-vat-formats, data-finseed-tax-id-label y data-finseed-short-label; los identificadores finseed-tax-id, finseed-tax-id-company-name, finseed-tax-id-document-type y finseed-tax-id-issuing-country; el atributo for de las etiquetas del identificador y de Empresa, con los valores finseed-tax-id y finseed-tax-id-company-name; y las clases de grupo finseed-tax-id__company y finseed-tax-id__field. Sin alguno de ellos, el script deja como lo dibuja el servidor la parte del recuadro que depende de él: Empresa visible para cualquier cliente, con la etiqueta larga, la etiqueta del identificador fija y los desplegables visibles para una empresa. Una etiqueta que envuelve su campo sin el atributo for no basta, porque el script no la encuentra. Si tu plantilla escribe el rechazo de Empresa bajo su propio campo, ese mensaje necesita además el identificador finseed-tax-id-company-name-error. Con él, el script mantiene visible Empresa después del rechazo «Indica el nombre de la empresa.». Sin él, con una dirección en España, el script puede ocultar el grupo con el mensaje dentro, y el cliente ve el formulario de nuevo sin ningún mensaje.
  • 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. Sin él, en PrestaShop 1.7 nada oculta los métodos de pago.
Las demás clases no son necesarias para la captura, pero nuestra hoja de estilos solo se aplica a los elementos que las llevan. 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.

​
Qué prometemos y qué puede cambiar

Los nombres de la sección Los nombres estables, las dos plantillas y el bloque <style> del estado obligatorio con su lista de selectores 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. No prometemos los textos, la estructura de elementos más allá de los listados, cómo está dibujada la flecha, los valores de espaciado ni la ruta y el identificador del script: pueden cambiar en cualquier versión sin aviso.