Invoice Pilot

Invoice Pilot étend WooCommerce avec une facturation pays par pays pour les 27 États membres de l’UE. Il capture les bons champs de facturation à la commande (codes SDI / PEC italiens, SIRET français, Leitweg-ID allemand, NIP polonais, CUI roumain, etc.), puis émet des factures, avoirs, proformas et devis PDF et XML immuables à partir de la commande. Le PDF est rendu via mPDF ; l’enveloppe XML est choisie automatiquement en fonction du pays de l’acheteur et couvre onze profils nationaux dont FatturaPA (IT), XRechnung (DE), KSeF FA(2) (PL), Factur-X (FR), CIUS_RO (RO), Facturae (ES) et UBL 2.1 / PEPPOL BIS 3.0 comme fallback générique.

Au-delà du moteur documentaire, Invoice Pilot embarque des intégrations de premier ordre avec six fournisseurs comptables — SmartBill (Roumanie), Fatture in Cloud (Italie), Xero, QuickBooks Online, Fortnox (Suède) et Sage — un validateur de TVA qui interroge le service européen VIES avec un fallback de format par pays, un tableau de bord avec cartes KPI et graphiques de tendance, et une couche IA multi-fournisseurs optionnelle (Anthropic Claude, OpenAI, Google Gemini, DeepSeek, Grok xAI) pour le smart-fill à la commande, le contrôle de conformité pré-émission, la traduction des lignes et la recherche documentaire en langage naturel. Le plugin prend également en charge WordPress Multisite avec des tables par site et une page d’aperçu à l’échelle du réseau.

Points forts

• Cycle de vie documentaire piloté par WooCommerce pour factures, avoirs, proformas et devis, avec séries de numérotation réservées, un flux propre émission / régénération / réémission / annulation / avoir, et un style par type de document (bandeau de mention sur les documents non fiscaux, libellés « Valable jusqu’au » sur les devis, « Total du remboursement » sur les avoirs, bloc de paiement masqué sur les devis et avoirs).
• Champs de facturation spécifiques par pays UE-27 enregistrés à la fois pour la commande shortcode héritée et pour la commande en blocs WooCommerce 8.6+ (via l’Additional Checkout Fields API).
• Rendu PDF via mPDF avec l’un des trois templates fournis (Minimal, Classic, Modern), avec sélecteur de couleur d’accent, couleur du texte, famille de police et logo vendeur.
• Onze writers XML dispatchés automatiquement depuis le pays de l’acheteur : 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), avec UBL 2.1 / PEPPOL BIS 3.0 comme fallback universel.
• Chaîne de validation de TVA combinant le service SOAP européen VIES avec une validation regex hors-ligne par pays, un cache en base et un cron horaire qui revalide les entrées périmées.
• Six intégrations comptables — SmartBill, Fatture in Cloud, Xero, QuickBooks Online, Fortnox et Sage — chacune avec identifiants chiffrés, opérations push / status / void et file de retry. L’onglet des intégrations utilise un sélecteur de fournisseur sticky : le panneau que vous configuriez reste ouvert d’une sauvegarde à l’autre.
• Couche IA optionnelle avec cinq fournisseurs (Anthropic, OpenAI, Google Gemini, DeepSeek, Grok xAI) couvrant smart-fill, contrôle de conformité, traduction des lignes et recherche en langage naturel ; le plugin fonctionne entièrement sans clé d’API.
• Tableau de bord avec sélecteur de période, cinq cartes KPI et deux graphiques de tendance ; un Journal d’intégration distinct enregistre chaque push et chaque échec.
• Prise en charge WordPress Multisite — chaque sous-site a ses propres tables, ses réglages et ses compteurs de numérotation, avec une page d’admin réseau qui agrège les statistiques.

Prérequis

L’intégration au block checkout est enregistrée via l’Additional Checkout Fields API de WooCommerce (introduite dans WooCommerce 8.6). Sur les versions plus anciennes, le filtre hérité woocommerce_billing_fields ajoute toujours les champs TVA, code fiscal et spécifiques par pays au shortcode checkout : le plugin se dégrade gracieusement.

Installation

1. Téléchargez le dernier ZIP Invoice Pilot depuis la page Releases  GitHub.
2. Dans WordPress, ouvrez Extensions → Ajouter → Téléverser une extension.
3. Choisissez le ZIP et cliquez sur Installer maintenant.
4. Cliquez sur Activer.
5. Ouvrez Invoice Pilot → Réglages pour configurer le vendeur, les séries de numérotation et les intégrations optionnelles.

L’activation crée les tables du plugin, installe les réglages par défaut et amorce cinq séries de numérotation (une par type de document) : INV (facture, par défaut), REC (reçu), CN (avoir), PRO (proforma) et Q (devis), toutes utilisant le pattern YYYY-NNNN avec une remise à zéro annuelle. Quatre tâches cron sont également planifiées : nettoyage quotidien des logs, retry des pushes d’intégration échoués toutes les quinze minutes, revalidation VIES horaire et rafraîchissement quotidien du token Fatture in Cloud.

Sur WordPress Multisite, le même bootstrap par site est exécuté automatiquement à la création d’un nouveau sous-site (wp_initialize_site).

Configuration

Tous les écrans d’Invoice Pilot vivent sous le menu de premier niveau Invoice Pilot dans la barre latérale d’administration WordPress :

• Tableau de bord — cartes KPI et graphiques de tendance.
• Documents — data-grid moderne listant chaque document émis (facture, avoir, proforma, devis, reçu) avec une barre d’outils unifiée (recherche IA + filtre par type), des pastilles de statut colorées (paid / void / converted / draft / issued), une pagination 20 lignes et des actions inline PDF / XML / Supprimer.
• Réglages — page de configuration en huit onglets (documentée plus bas).
• Journal — entrées du journal d’intégration avec rétention et action de nettoyage manuel.

La page Réglages est découpée selon les onglets suivants, dans l’ordre d’apparition dans l’UI :

1. Général
2. Séries
3. Types de document
4. Templates
5. Validation TVA
6. Intégrations
7. IA
8. Avancé

Général

L’onglet Général se compose de trois cartes : Licence, Détails du vendeur et Valeurs par défaut des documents.

Licence

Détails du vendeur porte l’identité imprimée sur chaque document émis ; Valeurs par défaut des documents porte un petit nombre de valeurs WooCommerce par défaut.

Séries

L’onglet Séries est une table CRUD des séries de numérotation stockées dans la table series du plugin. Chaque ligne contrôle la façon dont les documents d’un type donné sont numérotés.

Colonnes : Slug, Pattern, Compteur, Reset, Par défaut, Activée, Actions (Modifier / Supprimer).

Le formulaire Ajouter / Modifier expose :

Renommer un slug met à jour la ligne en place (préservant l’id entier et les références éventuelles) et migre automatiquement le réglage default_series s’il pointait sur l’ancien slug. Supprimer une série ne retire pas les documents existants ; ils conservent leurs numéros.

Types de document

L’onglet Types de document bascule les types de documents optionnels et expose les réglages bollo et ritenuta propres à FatturaPA.

Carte Types de document

Carte FatturaPA — B2B italien

Templates

Choisissez l’un des trois templates PDF fournis et personnalisez ses couleurs et sa typographie.

Champs supplémentaires :

L’onglet embarque également un aperçu PDF en direct (rendu via l’endpoint REST /wp-json/invoice-pilot/v1/preview-template) pour comparer les templates côte à côte avant d’enregistrer. Changer le radio permute l’iframe immédiatement ; le choix n’est persisté qu’au moment où vous cliquez sur Enregistrer le template.

Un sélecteur de Type de document se trouve au-dessus de l’iframe pour prévisualiser le rendu de chacun des quatre types — invoice, credit_note, proforma, quote — avec le même template, le même vendeur et le même acheteur d’exemple. Les différences appliquées par type sont :

Les devis renomment en plus les cellules « Émis » / « Échéance » mises en avant en Valable jusqu’au, et le total mis en avant devient Total estimé ; les avoirs le renomment en Total du remboursement. Ces différences proviennent d’une table de surcharges de libellés par type et d’un helper doc_type_context() injecté dans le moteur de template, pour que les trois designs fournis (Minimal / Classic / Modern) conservent une identité visuelle cohérente entre les types de documents sans dupliquer les fichiers de template.

Le pied de page porte toujours le pays de l’acheteur sous sa forme anglaise complète (par exemple Germany, et non DE) — le code ISO de la commande est résolu via Locale::getDisplayRegion() de PHP avant le rendu, ce qui garde la facture rendue lisible pour les acheteurs humains et les auditeurs fiscaux. Le numéro de TVA du vendeur, lui, est imprimé selon Format du numéro de TVA sur le PDF dans Général → Valeurs par défaut des documents — par défaut sous la forme préfixée style VIES (VAT IT04032690614), avec une option Sans préfixe pour les juridictions qui préfèrent le numéro brut.

Le dispatcher qui choisit la bonne enveloppe XML selon le pays de l’acheteur est le filtre invoice_pilot_xml_writer_for_country, que le code hôte peut surcharger par ISO (voir Hooks et filtres).

Validation TVA

Les identifiants de TVA saisis à la commande (et sur tout écran d’adresse qui expose le champ) passent par une chaîne de validateurs. Chaque validateur est activé par un interrupteur indépendant et tourne dans l’ordre jusqu’à ce qu’un d’entre eux renvoie un résultat positif ; les réponses positives comme négatives sont mises en cache pour le TTL configuré.

Une ligne État du cache en lecture seule rapporte le nombre d’entrées en cache et combien ont expiré en attente d’éviction.

Tester la validation TVA — une petite carte de test sous les réglages exécute chaque fournisseur directement contre une seule TVA, en contournant l’ordre de la chaîne et le cache, pour vous permettre de voir si VIES a réellement confirmé le numéro ou si seul le contrôle de format hors-ligne l’a fait.

Seeder les taux de TVA standard UE-27 — la carte du bas peuple WooCommerce → Réglages → Taxe → Taux standard avec le taux de TVA standard actuel pour chaque État membre 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%). Par défaut seuls les pays manquants sont insérés ; cochez Écraser les taux existants pour forcer le rafraîchissement de chaque ligne à la valeur canonique (utile après une hausse nationale de la TVA). La carte liste aussi chaque paire (ISO, taux) pour que vous voyiez exactement ce qui sera écrit avant de presser le bouton.

Intégrations

L’onglet Intégrations rend un panneau par fournisseur d’intégration enregistré, derrière un sélecteur Fournisseur unique en haut — choisissez le fournisseur à configurer et seule sa carte est visible, les autres restent dans le DOM masqués. Le sélecteur est sticky entre les sauvegardes : lorsque vous enregistrez le formulaire d’un fournisseur (ou que vous arrivez sur l’onglet avec ?integration=<id> dans l’URL), le rendu suivant garde ce fournisseur sélectionné, vous évitant d’être renvoyé sur celui qui est activé en premier dans l’ordre d’enregistrement.

Par défaut, Invoice Pilot embarque six fournisseurs ; du code tiers peut en enregistrer d’autres via le filtre invoice_pilot_integration_providers.

Chaque panneau de fournisseur est clos par une carte Statut de connexion avec un bouton Tester la connexion. Le bouton émet une requête légère contre les identifiants enregistrés et affiche la réponse upstream — enregistrez d’abord le formulaire si vous venez de coller de nouveaux tokens.

SmartBill

Fournisseur de facturation roumain. Les identifiants sont chiffrés au repos par la couche de crypto symétrique du plugin.

Lorsque l’intégration est activée, Invoice Pilot appelle POST /SBORO/api/v2/invoice à l’émission, puis pull_status pour réconcilier et void lorsqu’une facture est annulée.

Fatture in Cloud

Fournisseur de facturation italien. Les tokens OAuth sont stockés chiffrés au repos. Le cron quotidien invoice_pilot_refresh_fic_token rafraîchit automatiquement l’access token lorsque l’intégration est activée.

Conformément à la politique produit de Fatture in Cloud, Invoice Pilot ne soumet pas FatturaPA au SDI à votre place. La soumission SDI est laissée à une étape manuelle distincte depuis votre compte FIC.

Xero

Plateforme comptable mondiale. Les tokens OAuth 2.0 sont chiffrés au repos. L’onglet de réglages est organisé en Connexion (statut + boutons Connecter / Déconnecter) en haut et Réglages (identifiants de l’application + comportement du push) en bas.

Connexion

Invoice Pilot embarque un flux OAuth intégré — vous n’avez plus à faire la danse dans Postman et à coller quatre chaînes dans le formulaire. La configuration de bout en bout est :

1. Créez une Web app sur developer.xero.com  avec l’URI de redirection imprimée dans le panneau Connexion — recopiez-la telle quelle, Xero la compare caractère par caractère. Les applications créées après le 2 mars 2026 ne peuvent demander que le jeu de scopes granulaires ; Invoice Pilot choisit le bon automatiquement.
2. Générez un Client secret sur la page de l’application Xero (Xero ne l’affiche qu’une seule fois), puis collez Client ID et Client secret dans le formulaire Réglages et enregistrez.
3. Cliquez sur Connecter à Xero. Vous serez envoyé vers l’écran de consentement standard et, si votre compte autorise plus d’une organisation, vous serez redirigé vers un sélecteur intégré à la carte pour choisir le tenant cible. Les tokens sont échangés et persistés automatiquement.
4. Déconnecter efface les access et refresh tokens ainsi que le tenant id, tout en conservant les identifiants de l’application pour faciliter une reconnexion.

Les pushes utilisent POST /Invoices avec l’en-tête standard Idempotency-Key dérivé de l’id et du numéro de la facture locale, afin qu’un retry réseau retombe sur le même InvoiceID côté Xero au lieu de créer un doublon. Le refresh token est rotaté automatiquement sur 401 ; s’il finit par expirer (Xero invalide les refresh tokens après 60 jours d’inactivité), il suffit de recliquer sur Connecter.

Champs

QuickBooks Online

Intuit QuickBooks Online — US / CA / UK / mondial. Les tokens OAuth 2.0 sont chiffrés au repos. L’onglet de réglages est organisé en Connexion (statut + boutons Connecter / Déconnecter) en haut et Réglages (identifiants de l’application + comportement du push) en bas.

Connexion

Invoice Pilot embarque un flux OAuth intégré — vous n’avez plus à faire la danse dans Postman et à coller cinq chaînes dans le formulaire. La configuration de bout en bout est :

1. Créez une application sur developer.intuit.com  avec QuickBooks Online and Payments comme plateforme et le scope com.intuit.quickbooks.accounting. Ouvrez l’onglet Keys & OAuth et basculez entre Development et Production selon l’environnement visé — chacun a sa propre paire client_id
   • secret.
2. Ajoutez l’URI de redirection imprimée dans le panneau Connexion à la liste Redirect URIs puis cliquez sur Save — Intuit accepte http://localhost pour les applications de Development.
3. Collez Client ID et Client secret dans le formulaire Réglages, choisissez l’Environment correspondant (Sandbox / Production) et enregistrez.
4. Cliquez sur Connect to QuickBooks. L’écran de consentement d’Intuit vous permet de choisir l’entreprise contre laquelle l’intégration écrira ; le realmId choisi est renvoyé dans l’URL de callback et enregistré automatiquement — il n’y a pas de sélecteur de tenant séparé.
5. Déconnecter efface les access et refresh tokens ainsi que le realm id, tout en conservant les identifiants de l’application pour faciliter une reconnexion.

Chaque push utilise POST /v3/company/{realmId}/invoice avec le paramètre de requête requestid fixé à une valeur stable par facture — QBO collapse les POST réessayés sur la réponse d’origine, si bien qu’un retry réseau ne créera jamais de doublon. Les pushes portent aussi minorversion=75 pour que QBO renvoie les formes d’entités actuelles (sans cela, l’API rétrograde silencieusement vers son contrat de 2017). Les refresh tokens durent 100 jours à compter de leur émission et sont rotés à chaque utilisation ; le plugin gère la rotation de manière transparente sur 401.

Champs

Fortnox

Plateforme comptable suédoise. Identifiants OAuth 2.0 chiffrés au repos.

Sage

Plateforme comptable OAuth 2.0 (Sage Accounting / Business Cloud).

IA

L’onglet IA est découpé en deux cartes : Configuration du fournisseur et Fonctionnalités. Le plugin fonctionne entièrement sans clé d’API ; cet onglet ajoute des capacités optionnelles propulsées par l’IA.

Configuration du fournisseur

Modèles proposés par fournisseur :

Fonctionnalités

Avancé

Rétention et désinstallation

Actions de maintenance

• Lancer le nettoyage des logs maintenant — déclenche l’action invoice_pilot_cleanup_logs immédiatement au lieu d’attendre le cron quotidien.
• Purger le cache de validation — supprime chaque ligne de la table de cache de validation TVA.

Une petite ligne Versions en bas affiche la version courante du plugin et la version du schéma de base de données.

Utilisation

Émettre une facture automatiquement depuis une commande WooCommerce

Le workflow par défaut ne demande aucune action manuelle.

1. Un client passe commande sur WooCommerce. La commande expose les champs TVA et Code fiscal ainsi que tout champ spécifique au pays de facturation (par exemple SDI recipient code et Certified email (PEC) sur les commandes IT). Le champ TVA est validé en direct au fur et à mesure que le client tape — un badge ✓ vert apparaît à l’intérieur de l’input quand la chaîne confirme le numéro, ✕ rouge quand elle échoue. Si l’acheteur est dans un autre État membre UE et que la TVA est valide, WooCommerce met automatiquement la TVA du panier à zéro (reverse charge B2B intra-UE — voir Réglages → Validation TVA).
2. Lorsque la commande atteint le statut déclencheur défini sous Réglages → Général → Statut déclencheur (processing par défaut), Invoice Pilot émet une facture en utilisant la Série par défaut (INV par défaut), persiste un snapshot JSON immuable de la commande, rend le PDF, génère l’enveloppe XML pour le pays de l’acheteur et pousse vers toute intégration activée.
3. L’écran de commande gagne une meta box Invoice Pilot qui liste les documents émis avec des liens vers le PDF et le XML, plus des boutons d’action Régénérer, Réémettre, Annuler, Créer un avoir, Créer un proforma, Créer un devis et Pousser vers le fournisseur.

La meta box Invoice Pilot fait remonter, pour le dernier document non annulé de la commande : le numéro du document (par exemple INV-2026-0063), la pastille de statut (Issued / Paid / Void), les boutons de téléchargement PDF et XML (liens REST signés par token), une action Regenerate document qui re-rend les artefacts contre le template et les réglages vendeur courants sans changer le numéro du document, et une section Other documents qui expose des boutons Create proforma et Create quote en un clic. Lorsqu’une intégration est activée, un bouton Push to provider apparaît à côté des liens PDF / XML et rejoue l’appel d’intégration contre la cible configurée.

Émettre manuellement

Si l’émission automatique est désactivée ou que la commande n’a pas encore atteint le statut déclencheur, la meta box de la commande expose un bouton Émettre maintenant. Le même flux s’applique — snapshot, PDF, XML, push d’intégration — mais à la demande.

Avoirs depuis les remboursements

Lorsque Émission automatique d’un avoir au remboursement WC est activée (par défaut), tout remboursement WooCommerce créé sur une commande dotée d’une facture déclenche un avoir dans la série CN. L’avoir renvoie à la facture parente et la référence dans le XML. Le PDF rendu porte un bandeau de mention « Remboursement de INV-… » en haut, une pastille de statut CREDIT NOTE, Total du remboursement dans la cellule mise en avant, et masque le pied IBAN / méthode de paiement (le flux de paiement original ne s’applique plus). Vous pouvez aussi émettre un avoir manuellement — total ou partiel — depuis la carte Actions sur l’écran d’édition de la facture, à condition que la facture parente soit en statut issued.

Proformas et devis

Lorsque les interrupteurs correspondants sont activés, l’écran de commande expose aussi les boutons Créer un proforma et Créer un devis. Les deux produisent des documents non fiscaux — un PDF est rendu mais aucun XML n’est généré pour les devis. Le PDF rendu porte un traitement visuel propre à son type : un bandeau de mention en haut (« Proforma — document non fiscal. » / « Devis — document non fiscal, sous réserve d’acceptation. »), une pastille de statut « QUOTE » / « PROFORMA » à la place de « ISSUED », et sur les devis le libellé de date mis en avant passe à Valable jusqu’au et le total mis en avant à Total estimé. Les devis masquent le bloc IBAN / méthode de paiement puisqu’aucun paiement n’est encore dû.

Un proforma peut être converti en facture via l’action Convertir, qui re-numérote le document sous la série de facture configurée.

Envoyer une facture au client

Le plugin enregistre une action de commande Envoyer la facture Invoice Pilot au client dans le menu déroulant standard des actions de commande WooCommerce, qui envoie le PDF à l’acheteur via wp_mail() de WordPress.

Télécharger les documents

Les PDF et enveloppes XML sont servis depuis un endpoint REST adressable publiquement mais signé par token :

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

{format} vaut pdf ou xml. Le token est généré à l’émission du document et imprimé dans la meta box de la commande et dans la table de liste des factures.

Tableau de bord

Invoice Pilot → Tableau de bord ouvre une carte Vue d’ensemble d’activité au-dessus d’une carte Tendances. La Vue d’ensemble expose une barre de période avec quatre fenêtres — 7 jours, 14 jours, 30 jours (par défaut) et 90 jours — et cinq cartes KPI :

• Factures — nombre total de documents émis sur la période.
• Net revenue — somme des totaux nets dans la devise de la boutique, rendue avec le symbole monétaire de la locale et deux décimales (par exemple €3,876.09 ou 3.876,09 € selon la locale de l’administrateur).
• VAT collected — somme des totaux de TVA depuis le snapshot immuable. Même formatage monétaire dépendant de la locale que Net revenue. Une migration de schéma distincte remplit cette valeur pour les factures émises avant la version de schéma 1.3.1, où la colonne n’était pas peuplée à l’écriture.
• Avg value — chiffre d’affaires net divisé par le nombre de factures, également formaté en devise.
• B2B / B2C — répartition entre factures B2B (l’acheteur a un numéro de TVA) et B2C sur la même période.

Sous les KPI, la carte Tendances rend deux graphiques côte à côte — Invoices over time (un graphique double axe ligne + aire avec le nombre de factures sur l’axe gauche et la tendance du chiffre d’affaires net remplie sur l’axe droit) et By buyer country (un graphique en donut des principaux codes ISO acheteurs, avec la légende de couleurs en dessous). Toutes les figures sont alimentées par /wp-json/invoice-pilot/v1/dashboard?days=N.

Liste des documents

Invoice Pilot → Documents liste chaque document émis avec des pastilles de statut (paid / void / converted / draft / issued — colorées selon l’état du cycle de vie), une colonne Conformité portant le badge coloré produit par le pré-contrôle IA, et des actions inline PDF / XML / Supprimer par ligne. La page pagine par 20 lignes et expose une barre d’outils unifiée qui combine la recherche IA en texte libre avec un filtre par type de document (invoice / credit_note / proforma / quote / receipt) plus un décompte en cours à droite. Lorsque la recherche IA est activée, le champ de recherche accepte des requêtes libres (par exemple, « factures allemandes du mois dernier au-dessus de 1 000 EUR ») que le fournisseur configuré traduit en requête de liste ; les chips de filtre résolus apparaissent au-dessus du tableau pour que vous voyiez exactement comment le modèle a interprété votre phrase.

Liste des commandes WooCommerce

Invoice Pilot ajoute une unique colonne Facture à la liste standard des commandes WooCommerce (/wp-admin/admin.php?page=wc-orders) pour que le gérant de la boutique voie d’un coup d’œil quelles commandes ont déjà été documentées et lesquelles ne le sont pas, sans quitter l’écran des commandes. La colonne se place entre Commande et Date et affiche le numéro de document attribué par la série configurée (par exemple INV-2026-0063) lu tel quel depuis la colonne immuable number, avec une petite icône d’aperçu eye à côté du numéro qui ouvre en ligne le PDF rendu dans un nouvel onglet.

Les commandes sans document émis rendent un tiret cadratin — utile pour déboguer les inadéquations de statut déclencheur ou pour filtrer les commandes qui nécessitent un passage manuel par wp invoice-pilot issue. Le même renderer câble à la fois la colonne de la table de posts héritée (manage_edit-shop_order_columns) et la colonne HPOS (manage_woocommerce_page_wc-orders_columns), si bien que l’expérience est identique quel que soit le stockage de commandes utilisé par votre boutique.

Journal d’intégration

Invoice Pilot → Journal enregistre chaque push d’intégration, chaque réponse et chaque échec. La barre d’outils en haut combine un sélecteur Bulk actions + bouton Apply (pour l’instant une seule bulk-delete), un menu fournisseur et un menu action — tous deux peuplés à partir des valeurs réellement vues dans le log de sorte qu’ils n’affichent jamais que des filtres correspondant à une ligne réelle — et un décompte d’entrées en cours sur la droite.

La data grid porte huit colonnes :

Les champs sensibles du payload sont rédigés à l’écriture par le Core\Logger du plugin, les requêtes et corps de réponse peuvent donc être conservés sans risque dans le log. Les anciennes entrées sont purgées par le cron quotidien invoice_pilot_cleanup_logs selon le réglage Rétention des logs (jours) de l’onglet Avancé.

Admin réseau (Multisite)

Sur un réseau Multisite, une page supplémentaire Invoice Pilot Network apparaît dans la barre latérale d’admin réseau. Elle agrège les nombres et totaux de factures sur chaque sous-site où Invoice Pilot est actif.

Facturation UE-27

Invoice Pilot embarque un registre de champs de facturation spécifiques par pays pour chaque État membre UE-27. Chaque champ est optionnel à la commande (le plugin n’impose pas de données B2B sur une commande B2C) ; la validation ne se déclenche que lorsque le pays de l’acheteur correspond à l’ISO du champ.

Le registre couvre actuellement :

L’intégration au block checkout enregistre les champs sous l’espace de noms invoice-pilot/... via l’Additional Checkout Fields API. Par défaut, seuls les champs italiens sont exposés dans le block checkout pour ne pas submerger les acheteurs non italiens ; l’interrupteur Tous les champs UE-27 à la commande dans Général active le jeu complet. Le shortcode checkout hérité rend toujours le registre complet filtré par le pays de facturation sélectionné.

Les champs pays sont persistés sur la commande, copiés dans le snapshot immuable de la facture et consommés par les writers XML — par exemple l’italien ei_recipient_code devient CodiceDestinatario / PECDestinatario dans l’enveloppe FatturaPA, tandis que l’allemand leitweg_id devient BuyerReference / EndpointID 0204 dans XRechnung.

Intégrations

SmartBill

SmartBill (Roumanie) est câblé dans l’IntegrationManager du plugin via le filtre invoice_pilot_integration_providers et expose l’interface standard de fournisseur : push, pull_status, void et test_connection.

• Push mappe le snapshot de la facture sur le schéma JSON SmartBill et appelle POST /SBORO/api/v2/invoice avec le CIF et la série configurés.
• Synchronisation de statut réconcilie les états draft / issued / paid lors du run du cron de retry des quinze minutes.
• Void annule sur SmartBill une facture précédemment poussée lorsque la facture source est annulée dans WordPress.

Toutes les actions sont consignées dans le journal d’intégration. Les échecs sont mis en file et ré-essayés par le cron invoice_pilot_retry_integrations.

Fatture in Cloud

Fatture in Cloud (Italie) suit la même interface de fournisseur et mappe le snapshot de la facture sur la forme entity / items_list attendue par l’endpoint des documents émis de FIC. Les champs italiens spécifiques sont mappés explicitement :

• ei_recipient_code → ei_code
• ei_certified_email → certified_email
• TVA / code fiscal / province / pays de l’acheteur → clés entity correspondantes

Les identifiants OAuth sont chiffrés au repos. Le cron quotidien invoice_pilot_refresh_fic_token rafraîchit l’access token lorsque l’intégration est activée. Mettre Créer les clients sur on fait créer à l’intégration une nouvelle fiche client dans FIC sur la première facture d’un acheteur.

Invoice Pilot ne soumet pas FatturaPA au SDI à votre place. La soumission SDI est laissée à une étape manuelle distincte depuis votre compte Fatture in Cloud.

Smart-fill IA

La couche IA est entièrement optionnelle. Sans clé d’API configurée, le plugin émet toujours des factures, rend les PDF et XML, valide la TVA et pousse vers les intégrations — seules les quatre fonctionnalités IA ci-dessous sont indisponibles.

Cinq fournisseurs sont pris en charge :

La clé d’API est stockée chiffrée au repos via la couche de crypto symétrique du plugin. Cliquer sur Tester la connexion émet une requête minimale vers l’endpoint choisi et fait remonter l’erreur upstream si les identifiants sont mauvais.

Quatre fonctionnalités peuvent être basculées indépendamment une fois la clé enregistrée :

• Smart-fill à la commande — une zone de texte « Coller les détails de facturation » apparaît à la commande. Le modèle parse le texte libre et remplit le formulaire de facturation WooCommerce structuré, y compris les champs spécifiques par pays. Limité en débit par session.
• Pré-contrôle de conformité — chaque facture est passée au modèle juste avant émission, avec l’option de bloquer l’émission sur défauts critiques lorsqu’un problème critique est détecté (par exemple, une facture B2B italienne sans le code destinataire SDI).
• Auto-traduction des lignes — les descriptions des lignes de facture sont traduites dans la langue de l’acheteur. Lorsque le plugin compagnon Polyglot  est installé, le pipeline de traduction lui est délégué.
• Recherche documentaire en langage naturel — la barre de recherche sur la page d’admin Documents accepte des requêtes libres que le modèle traduit en requête de liste.

Chaque fonctionnalité a sa propre limite de débit horaire.

Hooks et filtres

Les noms de hooks centralisés vivent dans la classe \InvoicePilot\Core\Hooks. Liste complète :

Enregistrer un writer XML personnalisé :

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

Enregistrer un fournisseur d’intégration personnalisé :

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

Masquer ou étendre les champs de checkout spécifiques par pays (par exemple pour supprimer les invites ei_certified_email (PEC) et fiscal_regime (code RF) de l’Italie lorsque votre boutique n’en a jamais besoin — pas de fork du plugin requis) :

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
);

Le filtre s’exécute à la fois sur le chemin de validation du submit PHP et sur le snapshot JS servi au checkout WC Blocks, de sorte que les deux couches restent synchronisées. Noms machine des champs actuellement fournis (à utiliser dans le filtre) :

Le registre complet par pays est défini dans CountryFieldRegistry::install_defaults() et couvre tous les ISO EU-27.

FAQ

Invoice Pilot soumet-il FatturaPA au SDI ?

Non. Invoice Pilot génère le XML FatturaPA et le stocke sur la commande ; la soumission SDI est volontairement laissée à une étape manuelle distincte (ou à l’intégration Fatture in Cloud sur votre compte).

Puis-je ajouter un writer pour un pays non intégré ?

Oui. Branchez-vous sur invoice_pilot_xml_writer_for_country et renvoyez votre propre implémentation de \InvoicePilot\Modules\Xml\XmlWriterInterface.

Fonctionne-t-il avec le block checkout WooCommerce ?

Oui. Les champs spécifiques par pays sont enregistrés via l’Additional Checkout Fields API de WooCommerce 8.6+, ils apparaissent donc à la fois dans le block checkout et dans le shortcode checkout hérité. Sur les versions de WooCommerce antérieures à 8.6, seul le chemin de filtre hérité est emprunté.

Fonctionne-t-il sur WordPress Multisite ?

Oui. Chaque sous-site a ses propres tables, ses réglages et ses compteurs de numérotation. Une page d’admin réseau sous Network Admin → Invoice Pilot Network agrège les nombres de factures sur le réseau. Sur les nouveaux sous-sites, les tables et les séries par défaut sont créées automatiquement via le hook wp_initialize_site.

Les identifiants sont-ils chiffrés ?

Oui. Les tokens SmartBill, les tokens OAuth Fatture in Cloud et la clé d’API IA sont chiffrés au repos via \InvoicePilot\Core\Crypto. Laisser un champ de token vide à la sauvegarde suivante préserve la valeur existante.

Que deviennent mes données si je supprime le plugin ?

Rien, sauf opt-in. La valeur par défaut de Avancé → Effacer les données à la désinstallation est off, les tables, options, journaux d’intégration et cache de validation sont donc préservés entre désactivation et réactivation. Activez l’option si vous voulez que la routine uninstall.php supprime tout lorsque WordPress supprime le plugin.

Où obtenir une clé d’API pour les fonctionnalités IA ?

Chaque fournisseur a sa propre console : Anthropic sur console.anthropic.com , OpenAI sur platform.openai.com , Google AI Studio sur aistudio.google.com , DeepSeek sur platform.deepseek.com  et Grok sur console.x.ai . L’onglet IA renvoie directement vers la console du fournisseur choisi.

Faut-il une clé IA pour que le plugin fonctionne ?

Non. Les fonctionnalités IA (smart-fill, contrôle de conformité, traduction de lignes, recherche en langage naturel) sont optionnelles. Le moteur de facturation principal — cycle de vie documentaire, génération PDF et XML, validation de TVA, intégrations, tableau de bord — tourne sans clé d’API.

Dépannage

La facture n’est pas émise lorsque la commande passe à Processing

Vérifiez Réglages → Général → Statut déclencheur. La valeur par défaut est processing ; si vous l’avez personnalisée (par exemple à completed), la routine d’émission auto ne se déclenche que sur le statut configuré. Vous pouvez aussi cliquer sur Émettre maintenant depuis la meta box de commande pour émettre manuellement, indépendamment du déclencheur.

La commande affiche trop (ou trop peu) de champs pays

Par défaut, seuls les champs italiens SDI sont exposés. Ouvrez Réglages → Général → Document defaults → Champs de facturation spécifiques au pays et choisissez la portée :

• Off — seuls les champs universels TVA et code fiscal sont affichés.
• Italie uniquement (SDI / PEC / régime fiscal) — défaut.
• Tous les champs UE-27 spécifiques au pays — chaque ISO du registre.

Le réglage s’applique à la fois au block checkout et au shortcode checkout hérité. Les champs spécifiques au pays sont toujours masqués côté client lorsque le pays de facturation ne correspond pas.

La validation TVA se bloque ou tombe en timeout

Le service VIES est parfois lent ou indisponible. Le plugin conserve un cache par TVA pour le TTL configuré (24 heures par défaut) et revalide les entrées périmées toutes les heures via le cron invoice_pilot_revalidate_vies. Si VIES est hors ligne, le validateur Format par pays accepte toujours les numéros bien formés. Vous pouvez aussi augmenter le TTL du cache sous Réglages → Validation TVA.

Le tableau de bord n’affiche aucune donnée

Le SQL du tableau de bord s’appuie sur JSON_EXTRACT / JSON_UNQUOTE sur la colonne de snapshot de facture immuable. Vérifiez que votre serveur de base de données est MySQL 5.7+ ou MariaDB 10.2+. Si la barre de période affiche la bonne fenêtre mais que les cartes restent sur --, ouvrez /wp-json/invoice-pilot/v1/dashboard?days=30 directement et examinez la réponse — les échecs d’authentification REST apparaissent comme rest_forbidden.

Un push d’intégration échoue

Ouvrez Invoice Pilot → Journal et repérez l’entrée en échec — la colonne HTTP signale les réponses non 2xx avec un badge coloré et la colonne Erreur affiche le message d’erreur upstream en rouge. L’entrée échouée est automatiquement ré-essayée par le cron invoice_pilot_retry_integrations toutes les quinze minutes ; vous pouvez aussi cliquer sur Pousser vers le fournisseur dans la meta box de commande pour ré-essayer immédiatement. Utilisez l’action Supprimer sur une ligne pour purger une entrée ponctuelle sans attendre le cron de rétention.

Tester la connexion dans l’onglet IA renvoie une erreur

Le message renvoyé en rouge provient directement de l’endpoint du fournisseur. Causes fréquentes :

• Une clé d’API invalide ou révoquée — générez-en une nouvelle et collez-la dans le champ Clé d’API, puis enregistrez.
• Un nom de modèle auquel le compte n’a pas accès — choisissez un autre modèle dans le menu déroulant.
• Sortie réseau bloquée par l’hébergeur — confirmez que le HTTPS sortant vers api.anthropic.com, api.openai.com, generativelanguage.googleapis.com, api.deepseek.com ou api.x.ai est autorisé.

Les e-mails de notification au client n’arrivent pas

Les e-mails de facture client sont envoyés via la fonction wp_mail() de WordPress. Si aucun e-mail n’arrive, le problème vient presque toujours de la configuration mail du site et non d’Invoice Pilot. Installez un plugin de mail transactionnel (par exemple un plugin qui route les e-mails WordPress via SMTP) et redéclenchez l’action Envoyer la facture Invoice Pilot au client depuis une commande de test.