Saltar al contenido principal

Documentation Index

Fetch the complete documentation index at: https://www.easyverifactu.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

EasyVerifactu añade dos campos al checkout de WooCommerce: una casilla de “factura con datos fiscales” y un campo NIF/CIF. Esta guía está pensada para desarrolladores, agencias y equipos técnicos que necesitan reordenar, restilizar o renombrar esos campos sin romper la integración. Cubre los dos sabores de checkout que soporta el plugin, los hooks seguros para personalizar, qué prácticas rompen la integración y cómo diagnosticarlo desde el navegador.

​
Dos checkouts, dos vías de integración

WooCommerce tiene dos motores de checkout y EasyVerifactu soporta ambos. Comparten la misma forma canónica de datos en el pedido (OrderMeta), pero la superficie de personalización es completamente distinta. Identifica primero cuál usa tu tienda antes de tocar nada.
  • Checkout Blocks (moderno). El checkout basado en bloques de Gutenberg, validación de campos por JSON Schema, personalización vía ajustes nativos del bloque y patrones. Es el predeterminado en WooCommerce 8.3 y posteriores. Nuestros campos se registran a través de la Additional Checkout Fields API bajo el namespace easyverifactu.
  • Checkout Classic (legacy). El checkout del shortcode [woocommerce_checkout], basado en $_POST y personalizado mediante el filtro woocommerce_checkout_fields. Muchas tiendas previas a la versión 8.3 y muchos themes/page builders siguen anclados a este modo. Nuestros campos se registran con prioridades 34 y 35 entre billing_company (prioridad 30) y billing_country (prioridad 40).
Identifica cuál estás usando antes de aplicar cualquier técnica. Las instrucciones de la sección “Hooks y técnicas seguras” sólo aplican al checkout clásico. Si estás en Blocks, usa los ajustes nativos del bloque y los patrones de WooCommerce.

​
Qué añade el plugin y dónde

EasyVerifactu añade dos campos a la sección de facturación (billing) del checkout cuando la tienda opera en EUR. En cualquier otra divisa los campos no se registran.
  • Casilla easyverifactu_wants_full_invoice. Tipo checkbox. Etiqueta: “Quiero factura con datos fiscales (empresa o autónomo)”.
  • Campo easyverifactu_tax_id. Tipo text. Etiqueta: “NIF / CIF / Identificación fiscal” (opcional) o “NIF / CIF (obligatorio en compras superiores a 3.000 €)” cuando el carrito supera el umbral.
En el checkout clásico ambos campos van con prioridades 34 y 35, lo que produce el orden visual: nombre → apellidos → empresa → opt-in factura completa → NIF/CIF → país → dirección. En el checkout Blocks ambos campos se registran vía woocommerce_register_additional_checkout_field con location: 'order', por lo que aparecen en la sección de orden del bloque y los IDs internos son easyverifactu/wants_full_invoice y easyverifactu/tax_id (con barra, no con guion bajo).

​
Comportamiento por umbral

El umbral regulatorio (RD 1619/2012) de 3.000 € define el comportamiento de revelado:
  • Carrito ≤ 3.000 €. La casilla está visible. El NIF/CIF está oculto hasta que el comprador marca la casilla. Al marcarla, aparece el campo NIF/CIF como opcional.
  • Carrito > 3.000 €. La casilla desaparece (la factura completa es obligatoria de todas formas) y el NIF/CIF se muestra siempre con la etiqueta de obligatorio.
La lógica de revelado vive en el navegador, pero la validación final se hace en servidor sobre woocommerce_after_checkout_validation. Un comprador sin JavaScript no puede saltarse el requisito.

​
Hooks y técnicas seguras para personalizar (checkout clásico)

Las técnicas de esta sección sólo aplican al checkout clásico (shortcode). El checkout Blocks se personaliza desde el editor de Gutenberg y los ajustes del propio bloque.

​
Reordenar los campos

Para reubicar nuestros campos en el orden de facturación, engancha un filtro a woocommerce_checkout_fields con prioridad mayor que 10 (la nuestra) y reescribe la clave priority. Por defecto, la casilla está en prioridad 34 y el NIF/CIF en 35, justo después de billing_company. Ejemplo: colocarlos entre el nombre (prioridad 10) y los apellidos (prioridad 20). 
add_filter( 'woocommerce_checkout_fields', function( $fields ) {
    if ( isset( $fields['billing']['easyverifactu_wants_full_invoice'] ) ) {
        $fields['billing']['easyverifactu_wants_full_invoice']['priority'] = 11;
    }
    if ( isset( $fields['billing']['easyverifactu_tax_id'] ) ) {
        $fields['billing']['easyverifactu_tax_id']['priority'] = 12;
    }
    return $fields;
}, 99 );

​
Restilizar con CSS

Los campos exponen ganchos por ID y por clase. Úsalos para alinear con el diseño del theme:
  • #easyverifactu_wants_full_invoice y #easyverifactu_tax_id para los inputs.
  • .easyverifactu-legacy-checkout__wants-full-invoice y .easyverifactu-legacy-checkout__tax-id para las clases del wrapper <p class="form-row">.
Puedes apuntar también a las clases de fila de WooCommerce (.form-row, .form-row-wide) si tu hoja de estilos ya las trata.

​
Renombrar etiquetas

Sobrescribe la clave label en el mismo filtro. Si quieres usar “NIF” a secas en lugar del título largo por defecto: 
add_filter( 'woocommerce_checkout_fields', function( $fields ) {
    if ( isset( $fields['billing']['easyverifactu_tax_id'] ) ) {
        $fields['billing']['easyverifactu_tax_id']['label'] = 'NIF';
    }
    if ( isset( $fields['billing']['easyverifactu_wants_full_invoice'] ) ) {
        $fields['billing']['easyverifactu_wants_full_invoice']['label']
            = 'Necesito factura para mi empresa';
    }
    return $fields;
}, 99 );
Ten en cuenta que la etiqueta “obligatorio en compras superiores a 3.000 €” se aplica dinámicamente desde el cliente cuando se cruza el umbral. Si la reescribes, el cliente reescribirá tu valor en el momento del revelado para reflejar el estado regulatorio.

​
Añadir contenido adyacente

Para insertar texto o componentes alrededor de la sección de facturación, usa los hooks de acción nativos de WooCommerce:
  • woocommerce_before_checkout_billing_form
  • woocommerce_after_checkout_billing_form
Por ejemplo, para mostrar una nota explicativa encima del bloque de facturación: 
add_action( 'woocommerce_before_checkout_billing_form', function() {
    echo '<p class="ev-billing-intro">Necesitamos tus datos de facturación para emitir tu factura conforme a Verifactu.</p>';
} );

​
Qué rompe la integración y cómo detectarlo

La mayoría de incidencias en personalizaciones avanzadas caen en uno de estos patrones. Reconocerlos te ahorrará tiempo de soporte.

​
Page builders que reemplazan la plantilla del checkout

Elementor Pro, Divi, Beaver Builder o Bricks ofrecen widgets de checkout que sustituyen por completo la plantilla nativa. Cuando lo hacen, el pipeline de campos de WooCommerce no se ejecuta y nuestros campos no se renderizan. Solución. Configura el módulo de checkout del builder para usar los campos nativos de WooCommerce, no una lista de campos definida en el propio builder. Cada producto lo nombra de forma diferente, pero la opción suele estar etiquetada como “Use WooCommerce fields”, “Default fields” o similar.

​
Plugins de editor de campos del checkout

“Checkout Field Editor for WooCommerce”, “WooCommerce Checkout Manager”, “Flexible Checkout Fields” y similares mantienen una lista interna de campos permitidos. Cualquier campo que no esté en esa lista (como los nuestros) puede ser eliminado del formulario. Solución. Añade easyverifactu_wants_full_invoice y easyverifactu_tax_id a la lista de campos permitidos del editor.

​
Themes que sobrescriben las plantillas de checkout

Algunos themes incluyen sobrescrituras de woocommerce/checkout/form-checkout.php u otras plantillas del checkout. Si la sobrescritura no itera dinámicamente los campos del filtro y los lista a mano, nuestros campos no aparecerán. Solución. Revisa el archivo form-checkout.php del theme dentro de wp-content/themes/<tu-theme>/woocommerce/checkout/. Asegúrate de que llama a woocommerce_checkout_billing() o que recorre los campos devueltos por el filtro woocommerce_checkout_fields. Una plantilla que codifica a mano la lista de campos rompe cualquier personalización dinámica, no sólo la nuestra.

​
Contrato DOM del que depende el revelado condicional

El script de revelado y validación en el cliente espera una estructura DOM concreta. Si tu theme o un plugin la alteran, el revelado y la validación inline se degradan silenciosamente. La validación de servidor sigue funcionando, pero la experiencia del comprador empeora.
  • Envoltorio <p class="form-row"> alrededor de cada campo. Lo usamos para mostrar/ocultar la fila y para marcar el estado de error visualmente.
  • Selector .order-total .woocommerce-Price-amount (o .order-total bdi). Lo leemos para conocer el total del carrito en vivo y aplicar el umbral de 3.000 €.
  • IDs #billing_first_name, #billing_last_name, #billing_company, #billing_country. Los leemos para componer el nombre del comprador y el código de país que enviamos al validador de identificadores fiscales.
  • Evento updated_checkout disparado con jQuery sobre document.body. WooCommerce lo emite tras cada cambio en el carrito (cupón, envío, etc.) y reescuchamos para reaplicar el estado tras el re-renderizado del formulario.
Si alguno de estos elementos cambia de nombre, desaparece o se dispara por otro canal, el revelado condicional y la validación inline al perder foco fallan en silencio. La validación en servidor sobre woocommerce_after_checkout_validation sigue bloqueando el pedido si el NIF/CIF es incorrecto, así que el cumplimiento no se ve comprometido.

​
Diagnóstico rápido desde el navegador

Antes de pedir soporte, abre la consola del navegador en la página de checkout y comprueba lo siguiente: 
window.easyverifactuLegacyCheckout
Si devuelve undefined, nuestro script no se ha cargado. Confirma que el theme y los plugins activos no están bloqueando wp_enqueue_scripts en la página de checkout. Si devuelve un objeto, debe contener al menos restUrl, restNonce, thresholdCents, fieldWantsFullInvoice, fieldTaxId. Después, escribe un NIF inválido en el campo y quita el foco. En la pestaña Network deberías ver una petición POST a /wp-json/easyverifactu/v1/validate-tax-id (en tiendas con permalinks bonitos) o a /?rest_route=/easyverifactu/v1/validate-tax-id (en tiendas con la configuración “Sencillo” de permalinks). Si la petición no se dispara, el handler de blur no se ha enlazado (suele indicar un bundle cacheado obsoleto en el servidor de WordPress o que el theme reemplaza el input antes de que enlacemos). Si la petición devuelve 401 o 403, el nonce REST no es válido y suele indicar caché de página agresiva que sirve nonces caducados a usuarios distintos. Cuando la validación inline funciona, el input gana el atributo aria-invalid="true" y la fila añade las clases woocommerce-invalid y woocommerce-invalid-required-field.

​
Cuando la posición estándar no encaja con tu diseño

Hoy no proporcionamos un shortcode independiente para colocar los campos en cualquier zona de la página. Los dos campos aparecen en la posición que indican las prioridades 34 y 35 del filtro woocommerce_checkout_fields. Para reubicarlos basta con cambiar esa prioridad como se muestra en la sección anterior. Si tu diseño exige una posición que ninguna prioridad alcanza (por ejemplo, fuera del bloque de facturación), escríbenos. Estamos midiendo la demanda de añadir un hook tipo do_action( 'easyverifactu_render_tax_id_field' ) o un shortcode [easyverifactu_tax_id_field] para casos extremos. Ambas opciones tienen restricciones (el campo renderizado debe terminar dentro del <form class="checkout"> para que su valor se envíe con el resto del pedido), y preferimos construir la vía de escape correcta a la más pedida.

​
Tu personalización no rompe el cumplimiento

Sea cual sea el comportamiento del cliente, los hooks de servidor siguen siendo la fuente de verdad. validate_submission aplica el requisito de NIF/CIF para compras superiores a 3.000 € y consulta al validador de identificadores fiscales en cada envío. persist_to_order escribe la información canónica sobre el pedido. Un frontend mal configurado puede degradar la experiencia del comprador, pero no puede producir un pedido sin la información fiscal requerida cuando la ley la exige. Esto está diseñado así a propósito.

​
Cuando algo no funciona

Antes de contactar con soporte, captura la siguiente información. Reduce el tiempo de diagnóstico a la mitad.
  • Logs de WooCommerce filtrados por easyverifactu. Ve a WooCommerce > Estado > Registros y abre el log más reciente con esa fuente.
  • Consola y Network del navegador en la página de checkout. Captura el contenido de window.easyverifactuLegacyCheckout, la petición al endpoint validate-tax-id (con permalinks bonitos aparece como /wp-json/easyverifactu/v1/validate-tax-id; con la configuración “Sencillo” de permalinks aparece como /?rest_route=/easyverifactu/v1/validate-tax-id). Incluye cuerpo, respuesta, código de estado y cualquier error que aparezca en consola.
  • Estado actual de los campos del checkout. Si tienes acceso WP-CLI, ejecuta wp option get woocommerce_checkout_fields. Si no, copia el HTML del <form class="checkout"> renderizado.
  • Theme activo y plugins de personalización del checkout activos. Nombre exacto y versión.
  • Una grabación de pantalla del fallo. Cualquier vídeo corto del problema vale más que una descripción escrita.
Con esos datos abre un ticket desde easyverifactu.com/contacto y nuestro equipo podrá reproducirlo localmente.