Invoice Pilot

Invoice Pilot extiende WooCommerce con facturación país-consciente para los 27 estados miembros de la UE. Captura en el checkout los campos correctos de facturación (códigos SDI / PEC italianos, SIRET francés, Leitweg-ID alemán, NIP polaco, CUI rumano, etc.) y, a partir del pedido, emite facturas, notas de crédito, proformas y presupuestos inmutables en PDF y XML. El PDF se renderiza con mPDF; el envoltorio XML se elige automáticamente según el país del comprador y cubre once perfiles nacionales, entre ellos FatturaPA (IT), XRechnung (DE), KSeF FA(2) (PL), Factur-X (FR), CIUS_RO (RO), Facturae (ES) y UBL 2.1 / PEPPOL BIS 3.0 como fallback genérico.

Más allá del motor de documentos, Invoice Pilot trae integraciones de primera clase con seis proveedores contables — SmartBill (Rumanía), Fatture in Cloud (Italia), Xero, QuickBooks Online, Fortnox (Suecia) y Sage —, un validador de VAT que consulta el servicio europeo VIES con fallback por formato por país, un dashboard con tarjetas KPI y gráficos de tendencia, y una capa opcional de IA multi-proveedor (Anthropic Claude, OpenAI, Google Gemini, DeepSeek, Grok xAI) para smart-fill en checkout, pre-flight de cumplimiento, traducción de líneas y búsqueda de documentos en lenguaje natural. El plugin también soporta WordPress Multisite con tablas por sitio y una página de visión global a nivel de red.

Puntos fuertes

• Ciclo de vida de documentos basado en WooCommerce para facturas, notas de crédito, proformas y presupuestos, con series de numeración reservadas, un flujo limpio de emisión / regeneración / reemisión / anulación / nota de crédito, y un tratamiento visual por tipo (banner de aviso en documentos no fiscales, etiquetas “Válido hasta” en presupuestos, “Total reembolsado” en notas de crédito, bloque de pago oculto en presupuesto y nota de crédito).
• Campos de facturación específicos de la UE-27 registrados tanto contra el checkout legacy con shortcode como contra el checkout en bloques de WooCommerce 8.6+ (vía la Additional Checkout Fields API).
• Renderizado en PDF vía mPDF usando una de las tres plantillas incluidas (Minimal, Classic, Modern), con selectores de color de acento, color de texto, familia tipográfica y logo del vendedor.
• Once XML writers, despachados automáticamente según el país del comprador: FatturaPA (IT), Factur-X / CII (FR), XRechnung 3.0 (DE), KSeF FA(2) (PL), CIUS_RO 1.0.0 (RO), Facturae 3.2.2 (ES), SAF-T PT (PT), OIOUBL (DK), Finvoice 3.0 (FI), ebInterface 6.1 (AT), myDATA InvoicesDoc (GR / EL), con UBL 2.1 / PEPPOL BIS 3.0 como fallback universal.
• Cadena de validación de VAT que combina el servicio SOAP europeo VIES con validación offline por regex por país, una caché en BD y un cron horario que revalida las entradas obsoletas.
• Seis integraciones contables — SmartBill, Fatture in Cloud, Xero, QuickBooks Online, Fortnox y Sage — cada una con credenciales cifradas, operaciones push / status / void y una cola de reintentos. La pestaña Integraciones de los ajustes usa un selector de proveedor sticky para que el panel que estabas configurando se quede abierto entre guardados.
• Capa de IA opcional con cinco proveedores (Anthropic, OpenAI, Google Gemini, DeepSeek, Grok xAI) que cubre smart-fill, control de cumplimiento, traducción de líneas y búsqueda en lenguaje natural; el plugin funciona al 100 % sin una API key.
• Dashboard con selector de periodo, cinco tarjetas KPI y dos gráficos de tendencia; un Integration Log separado registra cada push y cada fallo.
• Soporte de WordPress Multisite — cada subsitio tiene sus propias tablas, ajustes y contadores de numeración, con una página de network admin que agrega estadísticas.

Requisitos

La integración con el block checkout está registrada contra la Additional Checkout Fields API de WooCommerce (introducida en WooCommerce 8.6). En versiones anteriores de WooCommerce, el filtro legacy woocommerce_billing_fields sigue añadiendo los campos de VAT, tax code y específicos por país al checkout con shortcode, así que el plugin degrada con elegancia.

Instalación

1. Descarga el último ZIP de Invoice Pilot desde la página de Releases  de GitHub.
2. En WordPress, abre Plugins → Añadir nuevo → Subir plugin.
3. Elige el ZIP y pulsa Instalar ahora.
4. Pulsa Activar plugin.
5. Abre Invoice Pilot → Ajustes para configurar el vendedor, las series de numeración y las integraciones opcionales.

La activación crea las tablas de base de datos del plugin, instala los ajustes por defecto y siembra cinco series de numeración (una por tipo de documento): INV (factura, por defecto), REC (recibo), CN (nota de crédito), PRO (proforma) y Q (presupuesto), todas con el patrón YYYY-NNNN y reinicio anual. También se programan cuatro tareas cron: limpieza diaria de logs, reintento de pushes fallidos cada quince minutos, revalidación horaria de VIES y refresco diario del token de Fatture in Cloud.

En WordPress Multisite, el mismo bootstrap por sitio se ejecuta automáticamente cuando se crea un nuevo subsitio (wp_initialize_site).

Configuración

Todas las pantallas de Invoice Pilot viven bajo el menú principal Invoice Pilot en la barra lateral del admin de WordPress:

• Dashboard — tarjetas KPI y gráficos de tendencia.
• Documentos — data-grid moderno que lista cada documento emitido (factura, nota de crédito, proforma, presupuesto, recibo) con una barra de herramientas unificada (búsqueda con IA + filtro por tipo), pastillas de estado codificadas por color (pagado / anulado / convertido / borrador / emitido), paginación de 20 filas y acciones inline de PDF / XML / Borrar.
• Ajustes — página de configuración con ocho pestañas (documentada abajo).
• Log — entradas del log de integración con retención y una acción manual de limpieza.

La página de ajustes se divide en las pestañas siguientes, en el orden en que aparecen en la UI:

1. General
2. Series
3. Tipos de documento
4. Plantillas
5. Validación de VAT
6. Integraciones
7. IA
8. Avanzado

General

La pestaña General está dividida en tres tarjetas: Licencia, Datos del vendedor y Valores por defecto del documento.

Licencia

Datos del vendedor lleva la identidad impresa en cada documento emitido; Valores por defecto del documento lleva un número reducido de valores por defecto a nivel de WooCommerce.

Series

La pestaña Series es una tabla CRUD sobre las series de numeración almacenadas en la tabla series propia del plugin. Cada fila controla cómo se numeran los documentos de un tipo dado.

Columnas: Slug, Patrón, Contador, Reinicio, Por defecto, Habilitada, Acciones (Editar / Borrar).

El formulario Añadir / Editar expone:

Renombrar un slug actualiza la fila de la serie en sitio (preservando el id entero y cualquier referencia) y migra automáticamente el ajuste default_series si apuntaba al slug antiguo. Borrar una serie no elimina los documentos existentes; mantienen sus números.

Tipos de documento

La pestaña Tipos de documento conmuta los tipos de documento opcionales y expone los ajustes específicos de FatturaPA bollo y ritenuta.

Tarjeta Tipos de documento

Tarjeta FatturaPA — B2B italiano

Plantillas

Elige una de las tres plantillas PDF incluidas y personaliza sus colores y tipografía.

Campos adicionales:

La pestaña embebe también una vista previa PDF en vivo (renderizada contra el endpoint REST /wp-json/invoice-pilot/v1/preview-template) para que puedas comparar plantillas en paralelo antes de guardar. Cambiar el radio intercambia el iframe al momento; la elección persiste solo cuando pulsas Guardar plantilla.

Un selector de Tipo de documento se sitúa sobre el iframe para que puedas previsualizar cómo se renderiza cada uno de los cuatro tipos — invoice, credit_note, proforma, quote — con la misma plantilla, vendedor de muestra y comprador de muestra. Las diferencias aplicadas por tipo son:

Los presupuestos además renombran las celdas prominentes “Emitida” / “Fecha de vencimiento” a Válido hasta, y el total destacado a Total estimado; las notas de crédito lo renombran a Total reembolsado. Esas diferencias salen de un mapa de override de etiquetas por tipo y un helper doc_type_context() alimentado al motor de plantillas, así los tres diseños incluidos (Minimal / Classic / Modern) mantienen una identidad visual consistente entre tipos de documento sin duplicar archivos de plantilla.

El pie de página lleva siempre el país del comprador en su forma completa en inglés (p. ej. Germany, no DE) — el código ISO del pedido se resuelve con Locale::getDisplayRegion() de PHP antes del render, lo que mantiene la factura renderizada legible para compradores humanos y auditores fiscales. El VAT del vendedor se imprime según Formato VAT en PDF en General → Valores por defecto del documento — por defecto en formato con prefijo estilo VIES (VAT IT04032690614), con una opción Solo número para jurisdicciones que prefieren el número escueto.

El dispatcher que elige el envoltorio XML correcto por país del comprador es el filtro invoice_pilot_xml_writer_for_country, así que el código del host puede sobrescribir por ISO (ver Hooks y filtros).

Validación de VAT

Los identificadores de VAT introducidos en el checkout (y en cualquier pantalla de dirección que exponga el campo) pasan por una cadena de validadores. Cada validador se activa con un interruptor independiente y se ejecuta en orden hasta que uno devuelve un resultado positivo; las respuestas positivas y negativas se cachean durante el TTL configurado.

Una fila de solo lectura Estado de la caché informa del número de entradas cacheadas y de cuántas han caducado y están pendientes de purga.

Probar validación de VAT — una tarjeta de tester debajo de los ajustes ejecuta cada proveedor directamente contra un único VAT, saltándose el orden de la cadena y la caché, para que puedas saber si VIES confirmó realmente el número o si lo hizo solo el chequeo de formato offline.

Sembrar tipos estándar UE-27 de VAT — la tarjeta de abajo rellena WooCommerce → Ajustes → Impuestos → Tipos estándar con el tipo estándar de VAT actual de cada Estado miembro UE-27 (AT 20% BE 21% BG 20% HR 25% CY 19% CZ 21% DK 25% EE 22% FI 25.5% FR 20% DE 19% GR 24% HU 27% IE 23% IT 22% LV 21% LT 21% LU 17% MT 18% NL 21% PL 23% PT 23% RO 21% SK 23% SI 22% ES 21% SE 25%). Por defecto solo se insertan los países que faltan; marca Sobrescribir tipos existentes para refrescar cada fila al valor canónico (útil tras una subida nacional del IVA). La tarjeta lista cada par (ISO, tipo) para que veas exactamente qué se va a escribir antes de pulsar el botón.

Integraciones

La pestaña Integraciones renderiza un panel por cada proveedor de integración registrado, detrás de un único selector Proveedor en la parte alta — elige el proveedor que quieras configurar y solo se muestra su tarjeta; los demás se quedan en el DOM ocultos. El selector es sticky entre guardados del formulario: cuando guardas el formulario de un proveedor (o aterrizas en la pestaña con ?integration=<id> en la URL), el siguiente render mantiene ese proveedor seleccionado, así que no te devuelve al proveedor que esté activo primero en el orden de registro.

Por defecto Invoice Pilot trae seis proveedores; el código de terceros puede registrar más a través del filtro invoice_pilot_integration_providers.

Cada panel de proveedor lo cierra una tarjeta Estado de la conexión con un botón Probar conexión. El botón lanza una petición ligera contra las credenciales guardadas e imprime la respuesta del upstream — guarda primero el formulario si acabas de pegar tokens nuevos.

SmartBill

Proveedor rumano de facturación. Las credenciales se cifran en reposo usando la capa de cripto simétrica del plugin.

Cuando está activo, Invoice Pilot llama a POST /SBORO/api/v2/invoice al emitir, luego a pull_status para reconciliar y a void cuando se cancela una factura.

Fatture in Cloud

Proveedor italiano de facturación. Los tokens OAuth se guardan cifrados en reposo. El cron diario invoice_pilot_refresh_fic_token refresca el access token automáticamente cuando la integración está activa.

Por política del producto Fatture in Cloud, Invoice Pilot no envía FatturaPA al SDI por ti. El envío al SDI queda como un paso manual separado desde dentro de tu cuenta de FIC.

Xero

Plataforma contable global. Los tokens OAuth 2.0 se cifran en reposo. La pestaña de ajustes está organizada con Conexión (estado + botones Conectar / Desconectar) arriba y Ajustes (credenciales de la app + comportamiento del push) abajo.

Conexión

Invoice Pilot trae de serie un flujo OAuth integrado — ya no tienes que hacer el baile en Postman y pegar cuatro cadenas en el formulario. La configuración de extremo a extremo es:

1. Crea una Web app en developer.xero.com  con la URI de redirección impresa en el panel Conexión — cópiala tal cual, Xero la compara carácter a carácter. Las apps creadas después del 2 de marzo de 2026 solo pueden solicitar el conjunto de scopes granulares; Invoice Pilot elige el adecuado automáticamente.
2. Genera un Client secret en la página de la app en Xero (Xero solo lo muestra una vez), luego pega Client ID y Client secret en el formulario de Ajustes y guarda.
3. Pulsa Conectar a Xero. Pasarás por la pantalla estándar de consentimiento y, si tu cuenta autoriza más de una organización, se te redirigirá a un selector dentro de la tarjeta para elegir el tenant de destino. Los tokens se intercambian y persisten automáticamente.
4. Desconectar limpia los tokens de acceso y de refresco y el tenant id, manteniendo las credenciales de la app para una reconexión rápida.

Los pushes usan POST /Invoices con la cabecera estándar Idempotency-Key derivada del id y el número de la factura local, así que un reintento de red colapsa al mismo InvoiceID de Xero en lugar de crear un duplicado. El refresh token rota automáticamente ante un 401; si llega a expirar (Xero invalida los refresh tokens tras 60 días de inactividad) basta con volver a pulsar Conectar.

Campos

QuickBooks Online

Intuit QuickBooks Online — US / CA / UK / global. Los tokens OAuth 2.0 se cifran en reposo. La pestaña de ajustes está organizada con Conexión (estado + botones Conectar / Desconectar) arriba y Ajustes (credenciales de la app + comportamiento del push) abajo.

Conexión

Invoice Pilot trae de serie un flujo OAuth integrado — ya no tienes que hacer el baile en Postman y pegar cinco cadenas en el formulario. La configuración de extremo a extremo es:

1. Crea una app en developer.intuit.com  con QuickBooks Online and Payments como plataforma y el scope com.intuit.quickbooks.accounting. Abre la pestaña Keys & OAuth y alterna entre Development y Production según el entorno al que apuntes — cada uno tiene su propio par client_id + secret.
2. Añade la URI de redirección impresa en el panel Conexión a la lista Redirect URIs y pulsa Save — Intuit acepta http://localhost para las apps de Development.
3. Pega Client ID y Client secret en el formulario de Ajustes, selecciona el Environment correspondiente (Sandbox / Production) y guarda.
4. Pulsa Connect to QuickBooks. La pantalla de consentimiento de Intuit te permite elegir la empresa contra la que la integración escribirá; el realmId elegido se devuelve en la URL de callback y se guarda automáticamente — no hay un selector de tenant aparte.
5. Desconectar limpia los tokens de acceso y de refresco y el realm id, manteniendo las credenciales de la app para una reconexión rápida.

Cada push usa POST /v3/company/{realmId}/invoice con el parámetro de query requestid fijado a un valor estable por factura — QBO colapsa los POST reintentados a la respuesta original, así que un reintento de red nunca creará un duplicado. Los pushes también llevan minorversion=75 para que QBO devuelva las formas de entidad actuales (sin ello la API degrada silenciosamente al contrato de 2017). Los refresh tokens duran 100 días desde su emisión y rotan en cada uso; el plugin gestiona la rotación de forma transparente ante un 401.

Campos

Fortnox

Plataforma contable sueca. Credenciales OAuth 2.0 cifradas en reposo.

Sage

Plataforma contable OAuth 2.0 (Sage Accounting / Business Cloud).

IA

La pestaña IA se divide en dos tarjetas: Configuración del proveedor y Funciones. El plugin funciona al 100 % sin una API key; esta pestaña añade capacidades opcionales impulsadas por IA.

Configuración del proveedor

Modelos ofrecidos por proveedor:

Funciones

Avanzado

Retención y desinstalación

Acciones de mantenimiento

• Ejecutar limpieza de log ahora — dispara la acción invoice_pilot_cleanup_logs al momento en lugar de esperar al cron diario.
• Purgar caché de validación — borra todas las filas de la tabla de caché de validación de VAT.

Una pequeña fila Versiones al final imprime la versión actual del plugin y la versión del esquema de base de datos.

Uso

Emisión automática de una factura desde un pedido de WooCommerce

El flujo por defecto no requiere ninguna acción manual.

1. Un cliente hace un pedido en WooCommerce. El checkout expone los campos VAT number y Tax code más cualquier campo específico del país registrado para el país de facturación (por ejemplo, SDI recipient code y Certified email (PEC) en pedidos IT). El campo VAT se valida en vivo a medida que el cliente escribe — un badge ✓ verde aparece dentro del input cuando la cadena confirma el número, ✕ rojo cuando falla. Si el comprador está en otro Estado miembro UE y el VAT es válido, WooCommerce pone a cero el IVA del carrito automáticamente (reverse charge B2B intra-UE — ver Ajustes → Validación de VAT).
2. Cuando el pedido llega al estado disparador definido en Ajustes → General → Estado disparador (processing por defecto), Invoice Pilot emite una factura usando la Serie por defecto (INV por defecto), persiste un snapshot JSON inmutable del pedido, renderiza el PDF, genera el envoltorio XML del país del comprador y hace push a cualquier integración activa.
3. La pantalla del pedido gana una meta box Invoice Pilot que lista los documentos emitidos con enlaces al PDF y al XML, más botones de acción Regenerar, Reemitir, Anular, Crear nota de crédito, Crear proforma, Crear presupuesto y Enviar al proveedor.

La meta box de Invoice Pilot expone, para el último documento no anulado del pedido: el número del documento (p. ej. INV-2026-0063), la pastilla de estado (Issued / Paid / Void), los botones de descarga PDF y XML (enlaces REST firmados con token), una acción Regenerar documento que vuelve a renderizar los artefactos contra la plantilla actual y los ajustes del vendedor sin cambiar el número del documento, y una sección Otros documentos que expone botones de un clic Crear proforma y Crear presupuesto. Cuando hay una integración activa, aparece un botón Enviar al proveedor junto a los enlaces PDF / XML que reproduce la llamada de integración contra el destino configurado.

Emitir manualmente

Si la emisión automática está desactivada o el pedido aún no ha llegado al estado disparador, la meta box del pedido expone un botón Emitir ahora. Se aplica el mismo flujo — snapshot, PDF, XML, push de integración — pero corre bajo demanda.

Notas de crédito a partir de reembolsos

Cuando Emitir nota de crédito automáticamente al reembolsar desde WC está activo (por defecto), cualquier reembolso de WooCommerce creado contra un pedido con factura existente dispara una nota de crédito en la serie CN. La nota de crédito enlaza de vuelta con la factura padre y la referencia en el XML. El PDF renderizado lleva un banner de aviso “Reembolso de INV-…” arriba, una pastilla de estado NOTA DE CRÉDITO, Total reembolsado en la celda destacada y oculta el pie con IBAN / método de pago (el flujo de pago original ya no aplica). También puedes emitir una nota de crédito manualmente — total o parcial — desde la tarjeta Acciones en la pantalla de edición de la factura, siempre que la factura padre esté en estado issued.

Proformas y presupuestos

Cuando los interruptores correspondientes están activos, la pantalla del pedido también expone los botones Crear proforma y Crear presupuesto. Ambos producen documentos no fiscales — se renderiza un PDF pero no se genera XML para los presupuestos. El PDF renderizado lleva un tratamiento visual específico por tipo: un banner de aviso arriba (“Proforma — no es un documento fiscal.” / “Presupuesto — no es un documento fiscal, sujeto a aceptación.”), una pastilla de estado “PRESUPUESTO” / “PROFORMA” en lugar de “EMITIDA” y, en los presupuestos, la etiqueta de fecha destacada pasa a Válido hasta y el total destacado a Total estimado. Los presupuestos ocultan el bloque de IBAN / método de pago porque todavía no hay pago pendiente.

Una proforma se puede convertir en factura con la acción Convertir, que renumera el documento bajo la serie de facturas configurada.

Enviar una factura al cliente

El plugin registra una acción de pedido Enviar factura de Invoice Pilot al cliente dentro del desplegable estándar de acciones de pedido de WooCommerce, que envía el PDF al comprador usando el wp_mail() de WordPress.

Descargar documentos

Los PDFs y los envoltorios XML se sirven desde un endpoint REST direccionable públicamente pero firmado con token:

GET /wp-json/invoice-pilot/v1/download/{id}/{format}?token=…

{format} es pdf o xml. El token se genera al emitir el documento y se imprime en la meta box del pedido y en la tabla del listado de facturas.

Dashboard

Invoice Pilot → Dashboard abre una tarjeta Resumen de actividad sobre una tarjeta Tendencias. El Resumen de actividad expone una barra de periodo con cuatro ventanas — 7 días, 14 días, 30 días (por defecto) y 90 días — y cinco tarjetas KPI:

• Facturas — recuento total de documentos emitidos en el periodo.
• Net revenue — suma de los totales netos en la moneda de la tienda, renderizada con el símbolo de moneda del locale y dos decimales (p. ej. €3,876.09 o 3.876,09 € según el locale del admin).
• VAT collected — suma de los totales de VAT del snapshot inmutable. Mismo formateo de moneda dependiente del locale que Net revenue. Una migración de esquema aparte rellena este valor para las facturas emitidas antes de la versión 1.3.1 del esquema, donde la columna no se poblaba en el momento de escribir.
• Avg value — ingresos netos divididos por el número de facturas, también formateado como moneda.
• B2B / B2C — reparto entre facturas B2B (el comprador tiene un número de VAT) y B2C en el mismo periodo.

Debajo de los KPIs, la tarjeta Tendencias renderiza dos gráficos en paralelo — Invoices over time (un gráfico de doble eje, línea

• área, con el recuento de facturas en el eje izquierdo y la tendencia de ingresos netos rellena sobre el eje derecho) y By buyer country (un gráfico de donut de los principales códigos ISO de comprador, con la leyenda de colores debajo). Todas las cifras se hidratan desde /wp-json/invoice-pilot/v1/dashboard?days=N.

Listado de documentos

Invoice Pilot → Documentos lista cada documento emitido con pastillas de estado (pagado / anulado / convertido / borrador / emitido — codificadas por color según el estado del ciclo de vida), una columna Cumplimiento que lleva el badge codificado por color producido por el pre-flight de IA, y acciones inline de PDF / XML / Borrar por fila. La página pagina de 20 en 20 filas y expone una barra de herramientas unificada que combina la búsqueda IA en texto libre con un filtro por tipo de documento (invoice / credit_note / proforma / quote / receipt) más un recuento en curso a la derecha. Cuando la búsqueda IA está activa, la caja de búsqueda acepta consultas en texto libre (por ejemplo, “Facturas alemanas del mes pasado por encima de 1.000 EUR”) que el proveedor configurado traduce en una list query; los chips de filtro resueltos aparecen sobre la tabla para que veas exactamente cómo ha interpretado el modelo tu frase.

Listado de pedidos de WooCommerce

Invoice Pilot añade una única columna Factura al listado estándar de pedidos de WooCommerce (/wp-admin/admin.php?page=wc-orders) para que el dueño de la tienda vea de un vistazo qué pedidos ya están documentados y cuáles no, sin salir de la pantalla de pedidos. La columna se sitúa entre Pedido y Fecha y muestra el número de documento asignado por la serie configurada (por ejemplo INV-2026-0063) leído tal cual desde la columna inmutable number, con un pequeño icono de vista previa con forma de ojo al lado del número que abre el PDF renderizado inline en una pestaña nueva.

Los pedidos sin documento emitido muestran una raya (em-dash) — útil cuando depuras desajustes con el estado disparador o filtras pedidos que necesitan una ejecución manual de wp invoice-pilot issue. El mismo renderer cablea tanto la columna legacy de la tabla de posts (manage_edit-shop_order_columns) como la columna HPOS (manage_woocommerce_page_wc-orders_columns), así que la experiencia es idéntica con independencia del almacenamiento de pedidos que use tu tienda.

Log de integración

Invoice Pilot → Log registra cada push, respuesta y fallo de integración. La barra de herramientas de la parte alta combina un selector Acciones en lote + botón Aplicar (actualmente un único bulk-delete), un desplegable de proveedor y un desplegable de acción — ambos poblados con los valores que de verdad aparecen en el log, así que solo muestran filtros que coinciden con alguna fila real — y un recuento de entradas en curso a la derecha.

El data grid lleva ocho columnas:

Los campos sensibles del payload los redacta en el momento de escribir el Core\Logger del plugin, así que los cuerpos de petición y respuesta son seguros para quedarse en el log. Las entradas antiguas se podan en el cron diario invoice_pilot_cleanup_logs según el ajuste Retención de log (días) de la pestaña Avanzado.

Network admin (Multisite)

En una red Multisite aparece una página adicional Invoice Pilot Network en la barra lateral del network admin. Agrega recuentos y totales de facturas en cada subsitio que tenga Invoice Pilot activo.

Facturación UE-27

Invoice Pilot trae un registro de campos de facturación específicos por país para cada estado miembro de la UE-27. Cada campo es opcional en el checkout (el plugin no fuerza datos solo B2B en un pedido B2C); la validación se dispara solo cuando el país del comprador coincide con el ISO del campo.

El registro cubre actualmente:

La integración con el block checkout registra los campos bajo el namespace invoice-pilot/... a través de la Additional Checkout Fields API. Por defecto, solo los campos italianos se exponen en el block checkout para no abrumar a los compradores no italianos; el interruptor Todos los campos UE-27 en el checkout en General activa el conjunto completo. El checkout legacy con shortcode siempre renderiza el registro completo filtrado por el país de facturación seleccionado.

Los campos por país se persisten en el pedido, se copian en el snapshot inmutable de la factura y los consumen los XML writers — por ejemplo, el italiano ei_recipient_code se convierte en CodiceDestinatario / PECDestinatario en el envoltorio FatturaPA, mientras que el alemán leitweg_id se convierte en BuyerReference / EndpointID 0204 en XRechnung.

Integraciones

SmartBill

SmartBill (Rumanía) está conectado al IntegrationManager del plugin a través del filtro invoice_pilot_integration_providers y expone la interfaz estándar de proveedor: push, pull_status, void y test_connection.

• Push mapea el snapshot de la factura al esquema JSON de SmartBill y llama a POST /SBORO/api/v2/invoice con el CIF y la serie configurados.
• Sincronización de estado reconcilia los estados borrador / emitido / pagado cuando corre el cron de reintentos cada quince minutos.
• Void cancela en SmartBill una factura enviada previamente cuando la factura origen se anula en WordPress.

Todas las acciones se registran en el log de integración. Los fallos se ponen en cola y los reintenta el cron invoice_pilot_retry_integrations.

Fatture in Cloud

Fatture in Cloud (Italia) sigue la misma interfaz de proveedor y mapea el snapshot de la factura a la forma entity / items_list que espera el endpoint de documentos emitidos de FIC. Los campos italianos por país se mapean explícitamente:

• ei_recipient_code → ei_code
• ei_certified_email → certified_email
• VAT / tax code / provincia / país del comprador → claves correspondientes de entity

Las credenciales OAuth se cifran en reposo. El cron diario invoice_pilot_refresh_fic_token refresca el access token cuando la integración está activa. Poner Crear clientes en activo hace que la integración cree un nuevo registro de cliente en FIC en la primera factura de un comprador.

Invoice Pilot no envía FatturaPA al SDI por ti. El envío al SDI queda como un paso manual separado desde dentro de tu cuenta de Fatture in Cloud.

Smart-fill con IA

La capa de IA es totalmente opcional. Sin una API key configurada, el plugin sigue emitiendo facturas, renderizando PDFs y XML, validando VAT y haciendo push a integraciones — solo las cuatro funciones de IA de abajo quedan no disponibles.

Hay cinco proveedores soportados:

La API key se guarda cifrada en reposo usando la capa de cripto simétrica del plugin. Pulsar Probar conexión lanza una petición mínima al endpoint elegido y muestra el error del upstream si las credenciales no son correctas.

Cuatro funciones se pueden conmutar de forma independiente una vez que hay una clave en archivo:

• Smart-fill en checkout — aparece en el checkout un textarea “Pega los datos de facturación”. El modelo parsea el texto libre y rellena el formulario estructurado de facturación de WooCommerce, incluidos los campos específicos por país. Con rate limit por sesión.
• Pre-flight de cumplimiento — cada factura pasa por el modelo justo antes de emitirse, con la opción de bloquear emisión ante errores de nivel crítico cuando se detecta un problema crítico (por ejemplo, una factura B2B italiana sin código de destinatario SDI).
• Auto-traducción de líneas — las descripciones de las líneas de factura se traducen al idioma del comprador. Cuando el plugin hermano Polyglot  está instalado, el pipeline de traducción se delega a él.
• Búsqueda de documentos en lenguaje natural — la caja de búsqueda de la página Documentos del admin acepta consultas en texto libre que el modelo traduce a una list query.

Cada función tiene su propio rate limit por hora.

Hooks y filtros

Los nombres de hooks centralizados viven en la clase \InvoicePilot\Core\Hooks. Lista completa:

Registrar un XML writer personalizado:

add_filter(
    'invoice_pilot_xml_writer_for_country',
    function ( $writer, $iso ) {
        if ( 'NL' === $iso ) {
            return new My_Custom_Nl_Writer();
        }
        return $writer;
    },
    20,
    2
);

Registrar un proveedor de integración personalizado:

add_filter(
    'invoice_pilot_integration_providers',
    function ( array $providers ) {
        $providers[] = new My_Custom_Provider();
        return $providers;
    }
);

Ocultar o extender los campos de checkout específicos por país (por ejemplo para eliminar los prompts ei_certified_email (PEC) y fiscal_regime (código RF) de Italia cuando tu tienda no los necesita — sin tener que bifurcar el plugin):

add_filter(
    'invoice_pilot_country_fields',
    function ( array $fields, string $iso ) {
        if ( 'IT' === $iso ) {
            $fields = array_values(
                array_filter(
                    $fields,
                    fn ( $f ) => ! in_array(
                        $f->name,
                        [ 'ei_certified_email', 'fiscal_regime' ],
                        true
                    )
                )
            );
        }
        return $fields;
    },
    10,
    2
);

El filtro se ejecuta tanto en la ruta de validación del envío PHP como en el snapshot JS servido al checkout de WC Blocks, por lo que las dos capas permanecen sincronizadas. Nombres máquina de los campos actualmente incluidos (úsalos en el filtro):

El registro completo por país está definido en CountryFieldRegistry::install_defaults() y cubre todos los ISO de la EU-27.

FAQ

¿Invoice Pilot envía FatturaPA al SDI?

No. Invoice Pilot genera el XML FatturaPA y lo guarda en el pedido; el envío al SDI se deja a propósito como un paso manual separado (o a la integración de Fatture in Cloud en tu cuenta).

¿Puedo añadir un writer para un país que no esté incluido?

Sí. Engánchate a invoice_pilot_xml_writer_for_country y devuelve tu propia implementación de \InvoicePilot\Modules\Xml\XmlWriterInterface.

¿Funciona con el block checkout de WooCommerce?

Sí. Los campos específicos por país se registran mediante la Additional Checkout Fields API de WooCommerce 8.6+, así que aparecen tanto en el block checkout como en el legacy con shortcode. En versiones de WooCommerce anteriores a la 8.6 solo se usa la ruta de filtro legacy.

¿Funciona en WordPress Multisite?

Sí. Cada subsitio tiene sus propias tablas, ajustes y contadores de numeración. Una página de network admin en Network Admin → Invoice Pilot Network agrega los recuentos de facturas de toda la red. En los subsitios nuevos, las tablas y las series por defecto se crean automáticamente vía el hook wp_initialize_site.

¿Se cifran las credenciales?

Sí. Los tokens de SmartBill, los tokens OAuth de Fatture in Cloud y la API key de IA se cifran en reposo vía \InvoicePilot\Core\Crypto. Dejar un campo de token en blanco en el siguiente guardado conserva el valor guardado.

¿Qué pasa con mis datos si borro el plugin?

Nada, salvo que tú lo decidas. El valor por defecto de Avanzado → Borrar datos al desinstalar es desactivado, así que las tablas, las opciones, los logs de integración y la caché de validación se conservan entre desactivación y reactivación. Activa la opción si quieres que la rutina uninstall.php borre todo cuando WordPress elimine el plugin.

¿Dónde consigo una API key para las funciones de IA?

Cada proveedor tiene su propia consola: Anthropic en console.anthropic.com , OpenAI en platform.openai.com , Google AI Studio en aistudio.google.com , DeepSeek en platform.deepseek.com , y Grok en console.x.ai . La pestaña IA enlaza directamente con la consola del proveedor elegido.

¿Necesito una API key de IA para que el plugin funcione?

No. Las funciones de IA (smart-fill, control de cumplimiento, traducción de líneas, búsqueda en lenguaje natural) son opcionales. El motor de facturación principal — ciclo de vida del documento, generación de PDF y XML, validación de VAT, integraciones, dashboard — funciona sin API key.

Resolución de problemas

La factura no se emite cuando el pedido pasa a Processing

Comprueba Ajustes → General → Estado disparador. El valor por defecto es processing; si lo has personalizado (por ejemplo a completed), la rutina de emisión automática solo se dispara con el estado configurado. También puedes pulsar Emitir ahora en la meta box del pedido para emitir manualmente, sin importar el disparador.

El checkout muestra demasiados (o demasiado pocos) campos por país

Por defecto solo se exponen los campos italianos SDI. Abre Ajustes → General → Document defaults → Campos de facturación por país y elige el ámbito:

• Desactivado — solo los campos universales VAT y código fiscal.
• Solo Italia (SDI / PEC / régimen fiscal) — por defecto.
• Todos los campos UE-27 por país — cada ISO del registro.

El ajuste se aplica tanto al block checkout como al checkout legacy con shortcode. Los campos por país siguen ocultándose en cliente cuando el país de facturación no coincide.

La validación de VAT se cuelga o agota el timeout

El servicio VIES está a veces lento o no disponible. El plugin mantiene una caché por VAT durante el TTL configurado (24 horas por defecto) y revalida las entradas obsoletas cada hora a través del cron invoice_pilot_revalidate_vies. Si VIES está caído, el validador de Formato por país sigue aceptando números bien formados. También puedes subir el TTL de caché en Ajustes → Validación de VAT.

El dashboard no muestra datos

La SQL del dashboard depende de JSON_EXTRACT / JSON_UNQUOTE contra la columna inmutable del snapshot de factura. Asegúrate de que tu servidor de base de datos sea MySQL 5.7+ o MariaDB 10.2+. Si la barra de periodo muestra la ventana correcta pero las tarjetas se quedan en --, abre /wp-json/invoice-pilot/v1/dashboard?days=30 directamente y revisa la respuesta — los fallos de autenticación REST aparecen como rest_forbidden.

Un push de integración falla

Abre Invoice Pilot → Log y localiza la entrada fallida — la columna HTTP marca las respuestas que no son 2xx con un badge de color y la columna Error muestra en rojo el mensaje de error del upstream. La entrada fallida la reintenta automáticamente el cron invoice_pilot_retry_integrations cada quince minutos; también puedes pulsar Enviar al proveedor en la meta box del pedido para reintentar al momento. Usa la acción Borrar en una fila para limpiar una entrada puntual sin esperar al cron de retención.

Probar conexión en la pestaña IA reporta un error

El mensaje que aparece en rojo viene directamente del endpoint del proveedor. Causas habituales:

• API key inválida o revocada — genera una nueva y pégala en el campo API key; luego guarda.
• Un nombre de modelo al que la cuenta no tiene acceso — elige otro modelo en el desplegable.
• Salida de red bloqueada por el hosting — confirma que el HTTPS saliente hacia api.anthropic.com, api.openai.com, generativelanguage.googleapis.com, api.deepseek.com o api.x.ai esté permitido.

Las alertas por email al cliente no llegan

Los correos de factura al cliente se envían con la función wp_mail() de WordPress. Si no llega ningún correo, el problema casi siempre está en la configuración de correo del sitio, no en Invoice Pilot. Instala un plugin de correo transaccional (por ejemplo, uno que encamine el correo de WordPress por SMTP) y vuelve a disparar la acción de pedido Enviar factura de Invoice Pilot al cliente desde un pedido de prueba.