Invoice Pilot

Invoice Pilot extinde WooCommerce cu facturare care înțelege specificul fiecărei țări din cele 27 de state membre UE. Capturează la checkout câmpurile de billing corecte (codurile italiene SDI / PEC, SIRET-ul francez, Leitweg-ID-ul german, NIP-ul polonez, CUI-ul românesc și așa mai departe), apoi emite din comandă facturi, note de credit, proforme și oferte imutabile, în PDF și XML. PDF-ul este randat cu mPDF; plicul XML este ales automat în funcție de țara cumpărătorului și acoperă unsprezece profiluri naționale, inclusiv FatturaPA (IT), XRechnung (DE), KSeF FA(2) (PL), Factur-X (FR), CIUS_RO (RO), Facturae (ES) și UBL 2.1 / PEPPOL BIS 3.0 ca fallback generic.

Pe lângă motorul de documente, Invoice Pilot vine cu integrări first-class cu șase furnizori de contabilitate — SmartBill (România), Fatture in Cloud (Italia), Xero, QuickBooks Online, Fortnox (Suedia) și Sage — un validator de TVA care consultă serviciul european VIES cu un fallback de format per țară, un dashboard cu carduri KPI și grafice de trend și un strat AI multi-provider opțional (Anthropic Claude, OpenAI, Google Gemini, DeepSeek, Grok xAI) pentru smart-fill la checkout, verificare de conformitate pre-emitere, traducere a liniilor de factură și căutare a documentelor în limbaj natural. Plugin-ul suportă și WordPress Multisite, cu tabele per site și o pagină de prezentare la nivel de rețea.

Puncte forte

• Ciclu de viață al documentelor condus de WooCommerce pentru facturi, note de credit, proforme și oferte, cu serii de numerotare rezervate, un flow curat de emitere / regenerare / re-emitere / anulare / notă de credit și styling specific tipului de document (banner de disclaimer pe documentele non-fiscale, etichete „Valabil până la” pe oferte, „Total rambursat” pe notele de credit, blocul de plată ascuns pe ofertă și pe nota de credit).
• Câmpuri de billing specifice fiecărei țări din UE-27, înregistrate atât pe checkout-ul legacy cu shortcode, cât și pe block checkout-ul WooCommerce 8.6+ (prin Additional Checkout Fields API).
• Randare PDF prin mPDF, folosind unul dintre cele trei template-uri incluse (Minimal, Classic, Modern), cu selector pentru culoarea de accent, culoarea textului, family de font și logo-ul vânzătorului.
• Unsprezece writere XML, dispatch-uite automat în funcție de țara cumpărătorului: 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), cu UBL 2.1 / PEPPOL BIS 3.0 ca fallback universal.
• Lanț de validare TVA care combină serviciul SOAP european VIES cu validare offline prin regex per țară, un cache pe baza de date și un cron orar care revalidează intrările expirate.
• Șase integrări de contabilitate — SmartBill, Fatture in Cloud, Xero, QuickBooks Online, Fortnox și Sage — fiecare cu credențiale criptate, operații push / status / void și un queue de retry. Tabul de setări Integrations folosește un selector de provider sticky, ca panoul pe care îl configurai să rămână deschis după salvări.
• Strat AI opțional cu cinci furnizori (Anthropic, OpenAI, Google Gemini, DeepSeek, Grok xAI) care acoperă smart-fill, verificare de conformitate, traducere a liniilor și căutare în limbaj natural; plugin-ul funcționează complet fără cheie API.
• Dashboard cu selector de perioadă, cinci carduri KPI și două grafice de trend; un Integration Log separat înregistrează fiecare push și fiecare eșec.
• Suport WordPress Multisite — fiecare sub-site are propriile tabele, propriile setări și propriile contoare de numerotare, plus o pagină de network admin care agregă statisticile.

Cerințe

Integrarea cu block checkout-ul este înregistrată pe WooCommerce Additional Checkout Fields API (introdus în WooCommerce 8.6). Pe versiuni mai vechi de WooCommerce, filtrul legacy woocommerce_billing_fields continuă să adauge câmpurile pentru TVA, cod fiscal și câmpurile specifice țării pe checkout-ul cu shortcode, deci plugin-ul degradează elegant.

Instalare

1. Descarcă cea mai recentă arhivă ZIP Invoice Pilot din pagina Releases  de pe GitHub.
2. În WordPress, deschide Plugins → Add New → Upload Plugin.
3. Alege ZIP-ul și apasă Install Now.
4. Apasă Activate Plugin.
5. Deschide Invoice Pilot → Settings pentru a configura vânzătorul, seriile de numerotare și integrările opționale.

Activarea creează tabelele de bază de date ale plugin-ului, instalează setările default și inițializează cinci serii de numerotare (una per tip de document): INV (factură, default), REC (chitanță), CN (notă de credit), PRO (proformă) și Q (ofertă), toate folosind pattern-ul YYYY-NNNN cu reset anual. Sunt programate și patru job-uri cron: cleanup zilnic pentru log, retry la fiecare cincisprezece minute pentru push-urile eșuate de integrare, revalidare orară VIES și refresh zilnic al token-ului Fatture in Cloud.

Pe WordPress Multisite, același bootstrap per site rulează automat când e creat un sub-site nou (wp_initialize_site).

Configurare

Toate ecranele Invoice Pilot sunt sub meniul de top-level Invoice Pilot din sidebar-ul de admin WordPress:

• Dashboard — carduri KPI și grafice de trend.
• Documents — grilă de date modernă, care listează fiecare document emis (factură, notă de credit, proformă, ofertă, chitanță), cu o bară de unelte unificată (căutare AI + filtru pe tip), pastile de status colorate (paid / void / converted / draft / issued), paginare 20 de rânduri și acțiuni inline pentru PDF / XML / Delete.
• Settings — pagină de configurare cu opt taburi (documentate mai jos).
• Log — intrări de log de integrare, cu retenție și o acțiune manuală de cleanup.

Pagina de Settings este împărțită în următoarele taburi, în ordinea în care apar în UI:

1. General
2. Serii
3. Tipuri de document
4. Template-uri
5. Validare TVA
6. Integrări
7. AI
8. Avansat

General

Tabul General este împărțit în trei carduri: License, Datele vânzătorului și Default-uri document.

License

Datele vânzătorului conține identitatea tipărită pe fiecare document emis; Default-uri document conține un număr mic de default-uri la nivel WooCommerce.

Serii

Tabul Serii este un tabel CRUD peste seriile de numerotare stocate în tabelul propriu series al plugin-ului. Fiecare rând controlează cum sunt numerotate documentele de un anumit tip.

Coloane: Slug, Pattern, Contor, Reset, Default, Activă, Acțiuni (Edit / Delete).

Formularul de Add / Edit expune:

Redenumirea unui slug actualizează rândul de serie pe loc (păstrând id-ul întreg și toate referințele) și migrează automat setarea default_series dacă pointa pe slug-ul vechi. Ștergerea unei serii nu elimină documentele existente; își păstrează numerele.

Tipuri de document

Tabul Tipuri de document comută tipurile opționale de document și expune setările specifice FatturaPA pentru bollo și ritenuta.

Cardul Tipuri de document

Cardul FatturaPA — B2B italian

Template-uri

Alege unul dintre cele trei template-uri PDF incluse și personalizează-i culorile și tipografia.

Câmpuri suplimentare:

Tabul include și o previzualizare PDF live (randată pe endpoint-ul REST /wp-json/invoice-pilot/v1/preview-template), ca să poți compara template-urile alăturat înainte să salvezi. Schimbarea radio-ului înlocuiește imediat iframe-ul; alegerea persistă doar când apeși Save template.

Deasupra iframe-ului se află un selector de Tip document, ca să poți previzualiza cum este randat fiecare din cele patru tipuri de document — invoice, credit_note, proforma, quote — cu același template, același vânzător sample și același cumpărător sample. Diferențele aplicate per tip sunt:

Ofertele renumesc, în plus, celulele proeminente „Issued” / „Due date” în Valid until și totalul hero în Estimated total; notele de credit îl renumesc în Refund total. Aceste diferențe vin dintr-un map de override de label-uri per tip și dintr-un helper doc_type_context() injectat în engine-ul de template-uri, astfel încât cele trei design-uri incluse (Minimal / Classic / Modern) să păstreze o identitate vizuală consistentă între tipurile de document, fără să dublezi fișierele de template.

Footer-ul afișează mereu țara cumpărătorului în forma completă în engleză (de ex. Germany, nu DE) — codul ISO de pe comandă este rezolvat prin Locale::getDisplayRegion() din PHP înainte de randare, ceea ce păstrează factura randată lizibilă atât pentru cumpărători umani, cât și pentru auditori fiscali. TVA-ul vânzătorului în sine este tipărit conform setării Format număr TVA pe PDF din General → Default-uri document — default-ul fiind forma prefixată în stil VIES (VAT IT04032690614), cu o opțiune Brut pentru jurisdicțiile care preferă numărul fără prefix.

Dispatcher-ul care alege plicul XML corect per țară a cumpărătorului este filtrul invoice_pilot_xml_writer_for_country, deci codul host poate suprascrie per ISO (vezi Hooks și filtre).

Validare TVA

Codurile de TVA introduse la checkout (și pe orice ecran de adresă care expune câmpul) trec printr-un lanț de validatori. Fiecare validator este activat de un comutator independent și rulează în ordine, până când unul returnează un rezultat pozitiv; atât răspunsurile pozitive, cât și cele negative sunt cache-uite pentru TTL-ul configurat.

Un rând read-only Starea cache-ului raportează numărul de intrări cache-uite și câte au expirat și așteaptă eviction.

Testează validarea TVA — un card mic de tester sub setări rulează fiecare provider direct pe un singur TVA, ocolind ordinea lanțului și cache-ul, ca să poți vedea dacă VIES a confirmat efectiv numărul sau dacă doar verificarea de format offline a făcut-o.

Inițializează cotele standard de TVA UE-27 — cardul de jos populează WooCommerce → Settings → Tax → Standard rates cu cota standard de TVA curentă pentru fiecare stat membru 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%). Implicit se inserează doar țările lipsă; bifează Suprascrie cotele existente pentru a forța fiecare rând la valoarea canonică (util după o creștere națională a TVA-ului). Cardul listează și fiecare pereche (ISO, cotă) ca să vezi exact ce va fi scris înainte să apeși butonul.

Integrări

Tabul Integrări randează un panou per furnizor de integrare înregistrat, în spatele unui selector unic Furnizor de sus — alegi furnizorul pe care vrei să-l configurezi și doar cardul lui este vizibil, restul rămân ascunse în DOM. Selectorul este sticky între salvări de formular: când salvezi formularul unui furnizor (sau aterizezi pe tab cu ?integration=<id> în URL), următoarea randare păstrează acel furnizor selectat, ca să nu fii aruncat înapoi pe primul furnizor activ din ordinea de înregistrare.

Din start, Invoice Pilot vine cu șase furnizori; codul terț poate înregistra încă unii prin filtrul invoice_pilot_integration_providers.

Fiecare panou de furnizor este închis de un card Connection Status cu un buton Test Connection. Butonul emite o cerere ușoară pe credențialele salvate și tipărește răspunsul upstream — salvează mai întâi formularul dacă tocmai ai lipit token-uri noi.

SmartBill

Furnizorul românesc de facturare. Credențialele sunt criptate at rest folosind stratul de criptografie simetrică al plugin-ului.

Când e activă, Invoice Pilot apelează POST /SBORO/api/v2/invoice la emitere, apoi pull_status pentru reconciliere și void când o factură este anulată.

Fatture in Cloud

Furnizor italian de facturare. Token-urile OAuth sunt stocate criptate at rest. Cron-ul zilnic invoice_pilot_refresh_fic_token reîmprospătează access token-ul automat atunci când integrarea este activă.

Conform politicii produsului Fatture in Cloud, Invoice Pilot nu trimite FatturaPA în SDI în numele tău. Trimiterea către SDI este lăsată unui pas manual separat, din contul tău FIC.

Xero

Platformă globală de contabilitate. Token-urile OAuth 2.0 sunt criptate at rest. Tabul de setări este aranjat cu Connection (status + butoane Connect / Disconnect) sus și Settings (credențiale de app + comportament la push) dedesubt.

Conectare

Invoice Pilot vine cu un flow OAuth integrat — nu mai trebuie să faci dansul în Postman și să lipești patru string-uri în formular. Configurarea end-to-end este:

1. Creează un app Web pe developer.xero.com  cu URI-ul de redirect afișat în panoul Connection — copiază-l verbatim, Xero îl compară caracter cu caracter. Aplicațiile create după 2 martie 2026 pot cere doar setul granular de scope-uri; Invoice Pilot îl alege automat pe cel corect.
2. Generează un Client secret pe pagina aplicației Xero (Xero îl afișează o singură dată), apoi lipește Client ID și Client secret în formularul Settings și salvează.
3. Apasă Connect to Xero. Vei fi trimis prin ecranul standard de consimțământ și, dacă pe contul tău autorizezi mai mult de o organizație, vei fi redirecționat către un picker in-card ca să alegi tenant-ul țintă. Token-urile sunt schimbate și salvate automat.
4. Disconnect șterge access + refresh token-urile și tenant id-ul, păstrând în același timp credențialele aplicației pentru o reconectare ușoară.

Push-urile folosesc POST /Invoices cu antetul standard Idempotency-Key derivat din id-ul + numărul facturii locale, deci o reluare de rețea se reduce la același Xero InvoiceID în loc să creeze un duplicat. Refresh token-ul se rotește automat la 401; dacă expiră vreodată (Xero invalidează refresh token-urile după 60 de zile de inactivitate), apasă din nou Connect.

Câmpuri

QuickBooks Online

Intuit QuickBooks Online — US / CA / UK / global. Token-urile OAuth 2.0 sunt criptate at rest. Tabul de setări este aranjat cu Connection (status + butoane Connect / Disconnect) sus și Settings (credențiale de app + comportament la push) dedesubt.

Conectare

Invoice Pilot vine cu un flow OAuth integrat — nu mai trebuie să faci dansul în Postman și să lipești cinci string-uri în formular. Configurarea end-to-end este:

1. Creează un app pe developer.intuit.com  cu QuickBooks Online and Payments ca platformă și scope-ul com.intuit.quickbooks.accounting. Deschide tabul Keys & OAuth și comută între Development și Production în funcție de mediul țintă — fiecare are propria pereche client_id + secret.
2. Adaugă URI-ul de redirect afișat în panoul Connection în lista Redirect URIs și apasă Save — Intuit acceptă http://localhost pentru aplicațiile Development.
3. Lipește Client ID și Client secret în formularul Settings, alege Environment-ul potrivit (Sandbox / Production) și salvează.
4. Apasă Connect to QuickBooks. Ecranul de consimțământ al Intuit îți permite să alegi compania în care integrarea va scrie; realmId-ul ales este returnat în URL-ul de callback și salvat automat — nu există un picker separat de tenant.
5. Disconnect șterge access + refresh token-urile și realm id-ul, păstrând în același timp credențialele aplicației pentru o reconectare ușoară.

Fiecare push folosește POST /v3/company/{realmId}/invoice cu parametrul de query requestid setat pe o valoare stabilă per factură — QBO reduce POST-urile reluate la răspunsul original, deci o reluare de rețea nu va crea niciodată un duplicat. Push-urile poartă de asemenea minorversion=75 astfel încât QBO să returneze formele actuale ale entităților (fără el, API-ul retrogradează tacit la contractul său din 2017). Refresh token-urile au o durată de viață de 100 de zile de la emitere și se rotesc la fiecare utilizare; plugin-ul gestionează rotația transparent la 401.

Câmpuri

Fortnox

Platformă suedeză de contabilitate. Credențiale OAuth 2.0 criptate at rest.

Sage

Platformă de contabilitate OAuth 2.0 (Sage Accounting / Business Cloud).

AI

Tabul AI este împărțit în două carduri: Provider Configuration și Features. Plugin-ul funcționează complet fără cheie API; acest tab adaugă capabilități opționale alimentate de AI.

Provider Configuration

Modele oferite per furnizor:

Features

Avansat

Retenție și dezinstalare

Acțiuni de mentenanță

• Rulează cleanup log acum — declanșează imediat acțiunea invoice_pilot_cleanup_logs, fără să aștepți cron-ul zilnic.
• Șterge cache-ul de validare — șterge fiecare rând din tabelul de cache al validării TVA.

Un mic rând Versiuni la final tipărește versiunea curentă a plugin-ului și versiunea schemei de bază de date.

Utilizare

Emiterea automată a unei facturi dintr-o comandă WooCommerce

Flow-ul implicit nu cere nicio acțiune manuală.

1. Un client plasează o comandă în WooCommerce. Checkout-ul expune câmpurile VAT number și Tax code, plus orice câmpuri specifice țării înregistrate pentru țara de billing (de exemplu, SDI recipient code și Certified email (PEC) pe comenzile IT). Câmpul TVA este validat live pe măsură ce clientul tastează — un badge ✓ verde apare în interiorul inputului când lanțul confirmă numărul, ✕ roșu când eșuează. Dacă cumpărătorul este într-un alt stat membru UE și TVA-ul este valid, WooCommerce reduce automat TVA-ul din coș la zero (reverse charge B2B intra-UE — vezi Settings → Validare TVA).
2. Când comanda ajunge la statusul trigger definit sub Settings → General → Trigger status (processing din start), Invoice Pilot emite o factură folosind seria default (INV din start), persistă un snapshot JSON imutabil al comenzii, randează PDF-ul, generează plicul XML pentru țara cumpărătorului și face push către orice integrare activă.
3. Ecranul comenzii primește un meta box Invoice Pilot care listează documentele emise, cu linkuri către PDF și XML, plus butoane de acțiune pentru Regenerează, Re-emite, Anulează, Creează notă de credit, Creează proformă, Creează ofertă și Trimite la furnizor.

Meta box-ul Invoice Pilot expune, pentru ultimul document neanulat al comenzii: numărul documentului (de ex. INV-2026-0063), pastila de status (Issued / Paid / Void), butoanele de descărcare PDF și XML (linkuri REST semnate cu token), o acțiune Regenerează documentul care re-randează artefactele pe template-ul curent și setările vânzătorului fără să modifice numărul documentului, și o secțiune Alte documente care expune butoane de un click Creează proformă și Creează ofertă. Când o integrare este activă, lângă linkurile PDF / XML apare un buton Trimite la furnizor care reia apelul de integrare către destinația configurată.

Emitere manuală

Dacă emiterea automată este dezactivată sau comanda încă nu a ajuns la statusul trigger, meta box-ul comenzii expune un buton Issue now. Se aplică același flow — snapshot, PDF, XML, push de integrare — dar rulează la cerere.

Note de credit din refund-uri

Când Emite automat notă de credit la refund WC este on (default-ul), orice refund WooCommerce creat pentru o comandă cu o factură existentă declanșează o notă de credit în seria CN. Nota de credit face link înapoi către factura părinte și o referențiază în XML. PDF-ul randat afișează un banner de disclaimer „Refund of INV-…” sus, o pastilă de status CREDIT NOTE, Total rambursat în celula hero și ascunde footer-ul de IBAN / metodă de plată (flow-ul de plată original nu se mai aplică). Poți emite o notă de credit și manual — completă sau parțială — din cardul Acțiuni de pe ecranul de editare al facturii, atâta timp cât factura părinte este în statusul issued.

Proforme și oferte

Când comutatoarele corespunzătoare sunt on, ecranul comenzii expune și butoanele Creează proformă și Creează ofertă. Ambele produc documente non-fiscale — un PDF este randat, dar nu se generează XML pentru oferte. PDF-ul randat poartă un tratament vizual specific tipului: un banner de disclaimer sus („Proforma — not a fiscal document.” / „Quote — not a fiscal document, subject to acceptance.”), o pastilă de status „QUOTE” / „PROFORMA” în loc de „ISSUED”, iar pe oferte eticheta proeminentă de dată se schimbă în Valid until, iar totalul hero în Estimated total. Ofertele ascund blocul de IBAN / metodă de plată, fiindcă încă nu există nicio plată scadentă.

O proformă poate fi convertită în factură cu acțiunea Convert, care renumără documentul sub seria de factură configurată.

Trimiterea unei facturi către client

Plugin-ul înregistrează o acțiune de comandă Send Invoice Pilot invoice to customer sub dropdown-ul standard de order-actions al WooCommerce, care trimite PDF-ul prin email către cumpărător folosind wp_mail() din WordPress.

Descărcarea documentelor

PDF-urile și plicurile XML sunt servite dintr-un endpoint REST adresabil public, dar semnat cu token:

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

{format} este pdf sau xml. Token-ul este generat când documentul este emis și este tipărit în meta box-ul comenzii și în tabelul de listă a facturilor.

Dashboard

Invoice Pilot → Dashboard deschide un card Activity overview deasupra unui card Trends. Activity overview expune o bară de perioadă cu patru ferestre — 7 zile, 14 zile, 30 zile (default) și 90 zile — și cinci carduri KPI:

• Facturi — numărul total de documente emise în perioadă.
• Venit net — suma totalurilor nete în moneda magazinului, randată cu simbolul de monedă al locale-ului și două zecimale (de ex. €3,876.09 sau 3.876,09 € în funcție de locale-ul administratorului).
• TVA colectat — suma totalurilor de TVA din snapshot-ul imutabil. Aceeași formatare de monedă conștientă de locale ca la Venit net. O migrație de schemă separată completează retroactiv această valoare pentru facturile emise înainte de versiunea de schemă 1.3.1, unde coloana nu era populată la momentul scrierii.
• Valoare medie — venitul net împărțit la numărul de facturi, de asemenea formatat ca monedă.
• B2B / B2C — split-ul între facturile B2B (cumpărătorul are un cod de TVA) și B2C pe aceeași perioadă.

Sub KPI-uri, cardul Trends randează două grafice alăturate — Invoices over time (un grafic cu dublu ax, linie + arie, având numărul de facturi pe axa stângă și trendul venitului net umplut pe axa dreaptă) și By buyer country (un grafic donut al codurilor ISO de top ale cumpărătorilor, cu legenda de culori dedesubt). Toate cifrele sunt hidratate din /wp-json/invoice-pilot/v1/dashboard?days=N.

Lista de documente

Invoice Pilot → Documents listează fiecare document emis, cu pastile de status (paid / void / converted / draft / issued — colorate după starea ciclului de viață), o coloană Compliance care poartă badge-ul colorat produs de verificarea AI pre-emitere și acțiuni inline pentru PDF / XML / Delete per rând. Pagina paginează 20 de rânduri o dată și expune o bară de unelte unificată care combină căutarea AI în text liber cu un filtru pe tipul de document (invoice / credit_note / proforma / quote / receipt), plus un contor live în dreapta. Când căutarea AI este activă, câmpul de căutare acceptă query-uri în text liber (de exemplu, „facturile germane de luna trecută peste 1.000 EUR”) pe care furnizorul configurat le traduce într-un query de listă; chip-urile de filtru rezolvate apar deasupra tabelului, ca să vezi exact cum a parsat modelul fraza ta.

Lista de comenzi WooCommerce

Invoice Pilot adaugă o singură coloană Invoice la lista standard de comenzi WooCommerce (/wp-admin/admin.php?page=wc-orders), astfel încât proprietarul magazinului să vadă dintr-o privire ce comenzi au fost deja documentate și care nu, fără să părăsească ecranul Orders. Coloana se află între Order și Date și afișează numărul de document atribuit de seria configurată (de exemplu INV-2026-0063), citit ca atare din coloana imutabilă number, cu o mică pictogramă de preview în formă de ochi lângă număr, care deschide PDF-ul randat inline într-un tab nou.

Comenzile fără document emis afișează o liniuță (em-dash) — util când depanezi nepotriviri de status trigger sau filtrezi comenzile care au nevoie de o rulare manuală wp invoice-pilot issue. Același renderer cablează atât coloana legacy din tabelul de posts (manage_edit-shop_order_columns), cât și coloana HPOS (manage_woocommerce_page_wc-orders_columns), așa încât experiența este identică indiferent de stocarea de comenzi pe care o folosește magazinul tău.

Log de integrare

Invoice Pilot → Log înregistrează fiecare push de integrare, răspuns și eșec. Bara de unelte din partea de sus combină un selector Bulk actions + buton Apply (deocamdată un singur bulk-delete), un dropdown de furnizor și un dropdown de acțiune — ambele populate cu valorile efectiv întâlnite în log, așa că arată doar filtre care se potrivesc cu un rând real — și un contor live de intrări în dreapta.

Grila de date are opt coloane:

Câmpurile sensibile din payload sunt redactate la scriere de Core\Logger-ul plugin-ului, deci body-urile de request și de răspuns sunt sigure de păstrat în log. Intrările vechi sunt curățate de cron-ul zilnic invoice_pilot_cleanup_logs conform setării Retenție log (zile) din tabul Avansat.

Network admin (Multisite)

Pe o rețea Multisite, în sidebar-ul de network admin apare o pagină suplimentară Invoice Pilot Network. Agregă numerele de facturi și totalurile de pe fiecare sub-site care are Invoice Pilot activ.

Facturare UE-27

Invoice Pilot livrează un registru de câmpuri de billing specifice fiecăruia dintre cele 27 de state membre UE. Fiecare câmp este opțional la checkout (plugin-ul nu forțează date doar-B2B pe o comandă B2C); validarea se declanșează doar când țara cumpărătorului se potrivește cu ISO-ul câmpului.

Registrul acoperă momentan:

Integrarea cu block checkout-ul înregistrează câmpurile sub namespace-ul invoice-pilot/... prin Additional Checkout Fields API. Din start, în block checkout sunt expuse doar câmpurile italiene, pentru a nu copleși cumpărătorii non-italieni; comutatorul Toate cele 27 de câmpuri UE la checkout din General activează setul complet. Checkout-ul legacy cu shortcode randează mereu registrul complet, filtrat după țara de billing selectată.

Câmpurile de țară sunt persistate pe comandă, copiate în snapshot-ul imutabil al facturii și consumate de writere-le XML — de exemplu, ei_recipient_code-ul italian devine CodiceDestinatario / PECDestinatario în plicul FatturaPA, iar leitweg_id-ul german devine BuyerReference / EndpointID 0204 în XRechnung.

Integrări

SmartBill

SmartBill (România) este conectat la IntegrationManager-ul plugin-ului prin filtrul invoice_pilot_integration_providers și expune interfața standard de furnizor: push, pull_status, void și test_connection.

• Push mapează snapshot-ul facturii pe schema JSON a SmartBill și apelează POST /SBORO/api/v2/invoice cu CIF-ul și seria configurate.
• Status sync reconciliază stările draft / issued / paid când rulează cron-ul de retry de cincisprezece minute.
• Void anulează în SmartBill o factură trimisă anterior, atunci când factura sursă este anulată în WordPress.

Toate acțiunile sunt logate în Integration log. Eșecurile sunt puse în queue și reîncercate de cron-ul invoice_pilot_retry_integrations.

Fatture in Cloud

Fatture in Cloud (Italia) urmează aceeași interfață de furnizor și mapează snapshot-ul facturii pe forma entity / items_list așteptată de endpoint-ul de issued-document al FIC. Câmpurile italiene specifice țării sunt mapate explicit:

• ei_recipient_code → ei_code
• ei_certified_email → certified_email
• TVA / cod fiscal / provincie / țară ale cumpărătorului → cheile entity corespunzătoare

Credențialele OAuth sunt criptate at rest. Cron-ul zilnic invoice_pilot_refresh_fic_token reîmprospătează access token-ul atunci când integrarea este activă. Setarea Create customers pe on face ca integrarea să creeze o înregistrare nouă de client în FIC la prima factură pentru un cumpărător.

Invoice Pilot nu trimite FatturaPA în SDI în numele tău. Trimiterea în SDI este lăsată unui pas manual separat, din contul tău Fatture in Cloud.

AI smart-fill

Stratul AI este complet opțional. Fără cheie API configurată, plugin-ul emite în continuare facturi, randează PDF-uri și XML, validează TVA și face push către integrări — doar cele patru feature-uri AI de mai jos nu sunt disponibile.

Sunt suportați cinci furnizori:

Cheia API este stocată criptată at rest folosind stratul de criptografie simetrică al plugin-ului. Apăsarea Test Connection emite un request minimal către endpoint-ul ales și aduce la suprafață eroarea upstream dacă credențialele sunt greșite.

Patru funcționalități pot fi comutate independent după ce o cheie este pe disc:

• Smart-fill la checkout — la checkout apare un textarea „Lipește datele de billing”. Modelul parsează textul liber și completează formularul structurat de billing WooCommerce, inclusiv câmpurile specifice fiecărei țări. Cu rate limit per sesiune.
• Verificare conformitate pre-emitere — fiecare factură este trecută prin model chiar înainte de emitere, cu opțiunea de a bloca emiterea pe findings de nivel eroare când e detectată o problemă critică (de exemplu, o factură italiană B2B fără codul destinatarului SDI).
• Auto-traducere a liniilor — descrierile liniilor de factură sunt traduse în limba cumpărătorului. Când plugin-ul companion Polyglot  este instalat, pipeline-ul de traducere este delegat lui.
• Căutare documente în limbaj natural — câmpul de căutare de pe pagina admin Documents acceptă query-uri în text liber pe care modelul le traduce într-un query de listă.

Fiecare feature are propriul rate limit per oră.

Hooks și filtre

Numele de hooks-uri centralizate sunt în clasa \InvoicePilot\Core\Hooks. Lista completă:

Înregistrarea unui writer XML custom:

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

Înregistrarea unui furnizor de integrare custom:

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

Ascunderea sau extinderea câmpurilor de checkout specifice țării (de exemplu, pentru a elimina solicitările ei_certified_email (PEC) și fiscal_regime (cod RF) ale Italiei când magazinul tău nu are niciodată nevoie de ele — fără fork al plugin-ului):

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

Filtrul rulează atât pe calea de validare submit PHP, cât și pe snapshot-ul JS servit checkout-ului WC Blocks, astfel încât cele două straturi rămân sincronizate. Nume mașină ale câmpurilor furnizate în prezent (folosește-le în filtru):

Registrul complet pe țară este definit în CountryFieldRegistry::install_defaults() și acoperă toate ISO-urile UE-27.

FAQ

Trimite Invoice Pilot FatturaPA în SDI?

Nu. Invoice Pilot generează XML-ul FatturaPA și îl stochează pe comandă; trimiterea în SDI este lăsată intenționat unui pas manual separat (sau integrării Fatture in Cloud din contul tău).

Pot adăuga un writer pentru o țară care nu e inclusă?

Da. Conectează-te pe invoice_pilot_xml_writer_for_country și returnează propria ta implementare a \InvoicePilot\Modules\Xml\XmlWriterInterface.

Funcționează pe block checkout-ul WooCommerce?

Da. Câmpurile specifice țării sunt înregistrate prin Additional Checkout Fields API din WooCommerce 8.6+, deci apar atât în block checkout, cât și în checkout-ul legacy cu shortcode. Pe versiuni de WooCommerce mai vechi de 8.6, se folosește doar calea legacy prin filtru.

Funcționează pe WordPress Multisite?

Da. Fiecare sub-site are propriile tabele, propriile setări și propriile contoare de numerotare. O pagină de network admin sub Network Admin → Invoice Pilot Network agregă numerele de facturi pe toată rețeaua. Pe sub-site-urile noi, tabelele și seriile default sunt create automat prin hook-ul wp_initialize_site.

Sunt credențialele criptate?

Da. Token-urile SmartBill, token-urile OAuth Fatture in Cloud și cheia API AI sunt criptate at rest prin \InvoicePilot\Core\Crypto. Lăsarea unui câmp de token gol la următoarea salvare păstrează valoarea stocată existentă.

Ce se întâmplă cu datele mele dacă șterg plugin-ul?

Nimic, decât dacă optezi explicit pentru asta. Default-ul pentru Avansat → Șterge datele la dezinstalare este off, deci tabelele, opțiunile, log-ul de integrare și cache-ul de validare sunt păstrate între dezactivare / reactivare. Pornește opțiunea dacă vrei ca rutina uninstall.php să șteargă tot când WordPress șterge plugin-ul.

De unde pot obține o cheie API pentru funcționalitățile AI?

Fiecare furnizor are propria consolă: Anthropic la console.anthropic.com , OpenAI la platform.openai.com , Google AI Studio la aistudio.google.com , DeepSeek la platform.deepseek.com , iar Grok la console.x.ai . Tabul AI face link direct către consola furnizorului ales.

Am nevoie de o cheie AI ca plugin-ul să funcționeze?

Nu. Funcționalitățile AI (smart-fill, verificare de conformitate, traducere de linii, căutare în limbaj natural) sunt opționale. Motorul de facturare în sine — ciclu de viață al documentelor, generare PDF și XML, validare TVA, integrări, dashboard — rulează fără cheie API.

Depanare

Factura nu este emisă când comanda trece pe Processing

Verifică Settings → General → Trigger status. Default-ul este processing; dacă l-ai customizat (de exemplu pe completed), rutina de emitere automată se declanșează doar pe statusul configurat. Poți și să apeși Issue now din meta box-ul comenzii ca să emiți manual, indiferent de trigger.

Checkout-ul afișează prea multe (sau prea puține) câmpuri de țară

Default-ul expune doar câmpurile italiene SDI. Deschide Settings → General → Document defaults → Câmpuri de facturare specifice țării și alege scope-ul:

• Off — sunt afișate doar câmpurile universale TVA și cod fiscal.
• Doar Italia (SDI / PEC / regim fiscal) — default.
• Toate câmpurile UE-27 specifice țării — fiecare ISO din registru.

Setarea se aplică atât block checkout-ului, cât și checkout-ului legacy cu shortcode. Câmpurile specifice țării sunt ascunse în continuare client-side când țara de billing nu corespunde.

Validarea TVA se blochează sau face timeout

Serviciul VIES este uneori lent sau indisponibil. Plugin-ul ține un cache per TVA pe TTL-ul configurat (24 de ore din start) și revalidează intrările expirate orar prin cron-ul invoice_pilot_revalidate_vies. Dacă VIES este offline, validatorul Format per țară acceptă în continuare numerele bine formate. Poți și să mărești TTL-ul cache-ului sub Settings → Validare TVA.

Dashboard-ul nu afișează date

SQL-ul dashboard-ului se bazează pe JSON_EXTRACT / JSON_UNQUOTE peste coloana de snapshot imutabil al facturii. Asigură-te că server-ul tău de bază de date este MySQL 5.7+ sau MariaDB 10.2+. Dacă bara de perioadă afișează fereastra corectă, dar cardurile rămân pe --, deschide direct /wp-json/invoice-pilot/v1/dashboard?days=30 și verifică răspunsul — eșecurile de autentificare REST apar ca rest_forbidden.

Push-ul de integrare eșuează

Deschide Invoice Pilot → Log și localizează intrarea eșuată — coloana HTTP marchează răspunsurile non-2xx cu un badge colorat, iar coloana Error afișează mesajul de eroare upstream cu roșu. Intrarea eșuată este reîncercată automat de cron-ul invoice_pilot_retry_integrations la fiecare cincisprezece minute; poți și să apeși Trimite la furnizor din meta box-ul comenzii ca să reîncerci imediat. Folosește acțiunea Delete pe un rând pentru a curăța o intrare punctuală, fără să aștepți cron-ul de retenție.

Test Connection în tabul AI raportează o eroare

Mesajul returnat cu roșu vine direct de la endpoint-ul furnizorului. Cauze uzuale:

• O cheie API invalidă sau revocată — generează una nouă și lipește-o în câmpul API Key, apoi salvează.
• Un nume de model la care contul nu are acces — alege alt model în dropdown.
• Ieșirea în rețea blocată de host — confirmă că HTTPS-ul de ieșire este permis către api.anthropic.com, api.openai.com, generativelanguage.googleapis.com, api.deepseek.com sau api.x.ai.

Email-urile de alertă către client nu sosesc

Email-urile cu factura către client sunt trimise prin funcția wp_mail() din WordPress. Dacă nu sosește niciun email, problema ține aproape mereu de configurarea de mail a site-ului, nu de Invoice Pilot. Instalează un plugin de mail tranzacțional (de exemplu, unul care rutează mail-ul WordPress prin SMTP) și declanșează din nou acțiunea Send Invoice Pilot invoice to customer dintr-o comandă de test.