Personalizar el checkout de WooCommerce

​

Dos checkouts, dos vías de integración

• Checkout Blocks (moderno). El checkout basado en bloques de Gutenberg, con validación de campos por JSON Schema y personalización desde el editor de bloques. Es el predeterminado en las versiones recientes de WooCommerce. Nuestros campos se registran a través de la Additional Checkout Fields API (WooCommerce 8.9 o posterior) bajo el namespace finseed.
• Checkout Classic (heredado). El checkout del shortcode [woocommerce_checkout], basado en $_POST y personalizado mediante el filtro woocommerce_checkout_fields. Muchas tiendas antiguas y muchos themes o page builders siguen ancladas a este modo. Nuestros campos se registran con prioridades de la 34 a la 39, entre billing_company (prioridad 30) y billing_country (prioridad 40).

​

Qué añade el plugin y dónde

• Casilla finseed_wants_full_invoice. Tipo checkbox, con la etiqueta “Quiero factura con mis datos fiscales”. Es la petición del comprador de una factura con sus datos fiscales.
• Selector finseed_buyer_kind. Tipo select, con la etiqueta Compras como y las opciones Particular y Empresa. Aparece junto al NIF/CIF solo cuando la dirección de facturación está fuera de España.
• Campo finseed_tax_id. Tipo text. Recoge el identificador fiscal del comprador. Su etiqueta depende del país de facturación y de la respuesta a Compras como: con una dirección española es “NIF / CIF / NIE”.
• Campo finseed_company_name. Tipo text, con la etiqueta Empresa. El plugin trata al comprador como empresa en dos casos: con una dirección española, cuando el NIF/CIF escrito tiene forma de CIF o es un número de IVA de la UE bien formado con el prefijo de otro país (por ejemplo, DE815892943), y el comprador no ha elegido nada en Tipo de documento; fuera de España, cuando el comprador elige la opción Empresa de Compras como. Solo entonces aparece el campo Empresa, así que con una dirección española y un NIF personal no aparece. Debajo lleva el texto de ayuda “El nombre completo de la empresa, con S.L., S.A. u otra forma al final.” Mientras está visible, es obligatorio en cuanto el NIF/CIF tiene un valor. Si queda vacío, el checkout muestra el error “Indica el nombre de la empresa.” La primera vez que aparece, toma como valor inicial el del campo de empresa de WooCommerce (billing_company). Si la tienda no muestra ese campo, toma la empresa guardada en la cuenta del comprador. El comprador puede cambiar ese valor. En la factura, el nombre escrito en Empresa tiene prioridad sobre billing_company. Si el script del checkout clásico no se carga, el campo aparece para todos los compradores con la etiqueta “Empresa (solo si facturas a una empresa)”, y el servidor solo lo exige cuando trata al comprador como empresa.
• Selectores finseed_document_type y finseed_issuing_country. Tipo select, con las etiquetas Tipo de documento (opciones Pasaporte y Documento de identidad de otro país) y País que expide el documento. Tipo de documento aparece con una dirección fuera de España cuando el comprador no elige la opción Empresa de Compras como. Con una dirección española aparece cuando el checkout rechaza el identificador con un mensaje que termina con “Si es un pasaporte o un documento de otro país, indica el tipo y el país.” País que expide el documento aparece cuando el comprador elige un tipo.

​

Comportamiento por umbral

• Carrito ≤ umbral. 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 > umbral. La casilla desaparece (la factura completa es obligatoria de todas formas) y el NIF/CIF se muestra siempre como obligatorio. Debajo del campo aparece el texto de ayuda “Necesario en compras superiores a 3.000 €”, con el umbral que se aplique a tu tienda.

​

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

​

Reordenar los campos

add_filter( 'woocommerce_checkout_fields', function( $fields ) {
    $finseed_fields = array(
        'finseed_wants_full_invoice',
        'finseed_buyer_kind',
        'finseed_tax_id',
        'finseed_company_name',
        'finseed_document_type',
        'finseed_issuing_country',
    );
    foreach ( $finseed_fields as $position => $key ) {
        if ( isset( $fields['billing'][ $key ] ) ) {
            $fields['billing'][ $key ]['priority'] = 41 + $position;
        }
    }
    return $fields;
}, 99 );

​

Restilizar con CSS

• #finseed_wants_full_invoice, #finseed_buyer_kind, #finseed_tax_id, #finseed_company_name, #finseed_document_type y #finseed_issuing_country para los inputs y selectores.
• .finseed-legacy-checkout__wants-full-invoice, .finseed-legacy-checkout__buyer-kind, .finseed-legacy-checkout__tax-id, .finseed-legacy-checkout__company-name, .finseed-legacy-checkout__document-type y .finseed-legacy-checkout__issuing-country para las clases del contenedor <p class="form-row">.
• .finseed-field-help para el texto de ayuda que el script añade debajo del NIF/CIF y de Empresa.

​

Renombrar las etiquetas

add_filter( 'woocommerce_checkout_fields', function( $fields ) {
    if ( isset( $fields['billing']['finseed_wants_full_invoice'] ) ) {
        $fields['billing']['finseed_wants_full_invoice']['label']
            = 'Necesito factura a nombre de mi empresa';
    }
    return $fields;
}, 99 );

​

Añadir contenido adyacente

• woocommerce_before_checkout_billing_form
• woocommerce_after_checkout_billing_form

add_action( 'woocommerce_before_checkout_billing_form', function() {
    echo '<p class="finseed-billing-intro">Introduce tus datos fiscales para recibir una factura completa.</p>';
} );

​

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

​

Page builders que reemplazan la plantilla del checkout

​

Plugins de editor de campos del checkout

​

Themes que sobrescriben las plantillas de checkout

​

Contrato DOM del que depende el revelado condicional

• Contenedor <p class="form-row"> alrededor de cada campo. Lo usamos para mostrar u ocultar la fila y para marcar el estado de error.
• Selector .order-total .woocommerce-Price-amount (o .order-total bdi). Lo leemos para conocer el total del carrito en vivo y aplicar el umbral.
• IDs #billing_first_name, #billing_last_name, #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 lo reescuchamos para reaplicar el estado tras el re-renderizado del formulario.

​

Diagnóstico rápido desde el navegador

window.finseedLegacyCheckout

​

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

​

Tu personalización no rompe el cumplimiento

• Checkout clásico. La validación sobre woocommerce_after_checkout_validation aplica el requisito de NIF/CIF (por encima del umbral, o en todos los pedidos con Siempre obligatorio), consulta al validador de identificadores fiscales en cada envío y rechaza el pedido de una empresa que escribe su NIF/CIF y deja Empresa vacío. La persistencia sobre woocommerce_checkout_create_order escribe la información canónica en el pedido.
• Checkout Blocks. Ninguno de esos dos hooks se ejecuta. En todas las versiones, el plugin actúa sobre woocommerce_store_api_checkout_update_order_from_request. Ahí rechaza el envío si falta el NIF/CIF cuando es obligatorio (por encima del umbral, o en todos los pedidos con Siempre obligatorio), si el identificador no es válido o si una empresa escribe su NIF/CIF y deja Empresa vacío. Esta última comprobación solo se hace si la petición a la Store API incluye finseed/company_name. Después guarda los datos en el pedido.

​

Cuando algo no funciona

• Logs de WooCommerce filtrados por finseed. 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.finseedLegacyCheckout y la petición al endpoint de validación (con enlaces permanentes personalizados aparece como /wp-json/finseed/v1/validate-tax-id; con la configuración “Sencillo” aparece como /?rest_route=/finseed/v1/validate-tax-id). Incluye cuerpo, respuesta, código de estado y cualquier error de 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.