FreeInvoice API
| 开发者 | cloudfinance |
|---|---|
| 更新时间 | 2026年7月29日 17:43 |
| PHP版本: | 7.2 及以上 |
| WordPress版本: | 6.9 |
| 版权: | GPLv2 or later |
| 版权网址: | 版权信息 |
详情介绍:
- SDI Invoices — Generate FatturaPA XML and send invoices through the SDI (Sistema di Interscambio) with full status tracking (states 4–9).
- FreeInvoice Documents — Send ordini and ricevute through the FreeInvoice document flow with status tracking (states 17 and 33).
- Ricevute for non-invoice private customers — Private customers who do not opt in to an invoice are routed to ricevute using the FreeInvoice Lead receiver — no fake fiscal code needed.
- WooCommerce Checkout Block support — Full compatibility with the WooCommerce Checkout Block via the Additional Checkout Fields API, including conditional fiscal fields based on customer type. In Blocks, the fiscal section uses the supported
orderlocation. - Classic checkout support — Works with both the traditional WooCommerce checkout and the Checkout Block.
- Explicit invoice opt-in for private customers — "Richiedo fattura" is the opt-in for private customers. For companies/entities/professionals the invoice is mandatory: the checkbox is hidden/forced on and saved fiscal data is shown directly in a preview card with "Modifica".
- HPOS compatible — Full support for WooCommerce High-Performance Order Storage.
- Auto-send on order completion — Optionally send invoices or documents automatically when an order is marked as completed.
- Manual send from admin — Send invoices or documents on demand from the order admin screen with dedicated actions.
- Webhook status tracking — SDI invoices receive real-time status updates from the FreeInvoice service via webhook integration. Ordini and ricevute reach their final state as soon as they are sent.
- Conditional checkout fields — Private customers see fiscal fields only after selecting "Richiedo fattura"; companies/entities/professionals use the mandatory fiscal section directly, with fields adapting to "Individual" or "Company/Entity/Professional".
- Guest checkout — Fiscal fields are collected during checkout and stored on the order; no user account required.
- Sandbox mode — Test the entire flow in the FreeInvoice sandbox environment before going live.
- Invoice numbering — Automatic or manual invoice numbering with configurable settings.
- 0% VAT rate management — Configure natura codes for 0% VAT rates according to FatturaPA requirements.
- Admin order list — View invoice/document status directly in the WooCommerce orders list with clear labels and Auto/Manual badges.
- Italian interface — The plugin interface is in Italian, matching the Italian e-invoicing workflow it automates.
- An active FreeInvoice API account
- WooCommerce installed and active
安装:
- WordPress 5.2 or later
- PHP 7.2 or later
- WooCommerce installed and active
- An active FreeInvoice API account
- Go to Plugins → Add New in your WordPress admin.
- Search for "FreeInvoice API".
- Click Install Now and then Activate.
- Download the plugin zip file.
- Go to Plugins → Add New → Upload Plugin.
- Choose the zip file and click Install Now.
- Click Activate.
- Download and unzip the plugin.
- Upload the
freeinvoice-apifolder to/wp-content/plugins/. - Activate the plugin from the Plugins menu.
- Go to WooCommerce → Settings → FreeInvoice API.
- Enter your FreeInvoice API credentials.
- Configure your seller data, tax regime, and VAT rates.
- Choose whether to use sandbox or production mode.
屏幕截图:
常见问题:
What do I need to use this plugin?
You need a WordPress site with WooCommerce installed and an active FreeInvoice API account. You can sign up at cloudfinance.it.
Does this plugin support the WooCommerce Checkout Block?
Yes. The plugin uses the WooCommerce Additional Checkout Fields API to add the private-customer invoice opt-in and fiscal fields to both the classic checkout and the WooCommerce Checkout Block. For private customers, fiscal fields appear when "Richiedo fattura" is selected and then adapt by customer type. For companies/entities/professionals, invoicing is mandatory: the opt-in checkbox is hidden/forced on and saved fiscal data is shown directly in a preview card with "Modifica". WooCommerce Blocks currently expose only the contact, address, and order Additional Checkout Fields locations, so the plugin places these fields in the supported order location rather than forcing an unsupported slot between shipping and payment.
What is HPOS and is it supported?
HPOS (High-Performance Order Storage) is WooCommerce's modern order data storage system. This plugin fully supports HPOS and works correctly with it enabled or disabled.
What types of documents can I send?
The plugin supports three document types:
- SDI Invoices (fatture elettroniche) — sent through the SDI, for companies and private individuals with a fiscal code.
- Ordini (orders) — sent through the FreeInvoice document flow, for companies and private individuals with a fiscal code.
- Ricevute (receipts) — sent through the FreeInvoice document flow, for private individuals without a fiscal code.
How does the ricevute flow work for private customers without invoice opt-in?
When a private customer leaves "Richiedo fattura" off at checkout, the plugin can route the document as a ricevuta. The FreeInvoice backend creates or matches a Lead receiver using the customer's email address — no fake fiscal code is used. If the customer turns "Richiedo fattura" on as a private customer, a valid fiscal code is required.
When are fiscal fields used for the current order?
For private customers, only when they select the dedicated "Richiedo fattura" checkbox at checkout. When a private customer leaves it off, saved fiscal profile data such as CF, PIVA, SDI, or PEC is not used for current order routing, and the order remains eligible for the safe ricevuta/non-invoice path. For companies/entities/professionals, invoicing is mandatory and the fiscal data is used for the order.
Can I test the plugin before going live?
Yes. Enable sandbox mode in the plugin settings to test the entire invoice and document flow against the FreeInvoice sandbox environment. No real invoices will be transmitted.
Does the plugin send invoices automatically?
Yes, if auto-send is enabled in the settings, the plugin will automatically send the appropriate invoice or document when a WooCommerce order is marked as completed. You can also send manually from the order admin screen at any time; the admin selector can choose between SDI invoice, ordine, and ricevuta when the order fiscal data supports those send types.
How do I track invoice status?
Invoice and document status is updated in real time via webhook. You can see the current status in the WooCommerce order admin screen and in the orders list.
Can I disable invoicing for private individuals?
Yes. In the plugin settings you can enable or disable electronic invoicing for private individuals. When disabled, the fiscal fields will not appear for private customers during checkout.
Where can I manage the tax regime?
In the plugin settings (WooCommerce → Settings → FreeInvoice API) you can select your business tax regime from a drop-down list.
Does the plugin generate PDF invoices?
No. The plugin generates FatturaPA XML and transmits it through the FreeInvoice service. PDF invoices are available on your FreeInvoice account.
Can I manage 0% VAT rates?
Yes. The plugin settings include a dedicated section for managing 0% VAT rates with their corresponding FatturaPA natura codes.
Where can I configure invoice numbering?
Invoice numbering settings are available in the plugin settings. You can choose between automatic or manual numbering.
更新日志:
- Auto-send "Fattura o Ricevuta": when the invoice cannot be issued, the fallback now always issues a receipt. It previously issued an order document ("Ordine cliente") whenever the customer had valid fiscal data, leaving an open document in the management system for a sale that was already closed.
- Order list and order metabox: FreeInvoice documents are now labelled "Ordine inviato" / "Ricevuta inviata" instead of "consegnato/a". Only SDI invoices have a delivery state, so the "Fattura ..." badges are unchanged.
- Database migration made non-destructive: the order-to-document link table is now rebuilt through a new table and an atomic rename, with recovery of rows written meanwhile. The previous migration emptied the table and reinserted its rows from a temporary table, which could lose the order-to-invoice mapping if the request was interrupted.
- Uninstall now also removes the migration side tables, which hold order-to-document mappings.
- Order meta writes now persist metadata only instead of saving the whole order object on every field.
- Checkout Block: fiscal preview fields are now hidden also on browsers without CSS
:has()support. - Documentation: corrected the claim of an English interface (the plugin UI is Italian) and clarified that webhook status updates apply to SDI invoices.
- B2B: invoice is now issued for companies with a valid VAT number even without the "Richiedo fattura" opt-in (art. 21 DPR 633/72); private customers unchanged (invoice on request).
- IVA Natura: no more guessed default (N1/N4) on 0% lines. If a 0% tax class has no Natura mapped, emission is blocked with a clear message (invoices, orders and receipts alike). Foreign customers keep the country override (N3.1/N3.2).
- Add configurable default VAT chargeability (EsigibilitaIVA I/D); split payment (S) remains out of scope.
- Codice Destinatario: 6-char PA (IPA) codes now return a clear "PA not supported in this version" message.
- Auto-send: failures on order completion now show an admin notice (not only the log), with the specific reason; de-duplicated; status re-check skipped inside the completed hook to avoid false "not completed".
- Checkout: fiscal fields (including customer type) are hidden until "Richiedo fattura" is selected.
- Fix: fiscal field intentionally cleared at checkout is no longer restored from the customer profile.
- Add dedicated checkout "Richiedo fattura" opt-in: default off, hides fiscal fields until selected, and prevents saved fiscal profile data from routing a non-opt-in order as an invoice.
- Fix FatturaPA XML line pricing when WooCommerce product prices are entered inclusive of tax and catalog sale prices are used.
- Improve admin order metabox fiscal data handling: saved customer fiscal fields prefill empty order fields and are saved before manual send.
- Fix incorrect split payment flag on zero-VAT/Natura XML summaries sent to SDI
- Add WooCommerce Checkout Block support via Additional Checkout Fields API
- Add HPOS (High-Performance Order Storage) compatibility
- Add FreeInvoice document flow: ordini and ricevute
- Add automatic routing of private customers without fiscal code to ricevute via Lead receiver
- Add auto-send on order completion with tracking
- Add manual send for both SDI invoices and FreeInvoice documents from order admin
- Add webhook status tracking for invoices and documents
- Add conditional checkout fields based on customer type (individual/company)
- Add guest checkout support for fiscal fields
- Add customer email to API payload for document sending
- Improve admin metabox with route-aware labels (Invia Fattura / Invia Ricevuta / Invia Ordine)
- Improve order list status display with single primary label and Auto/Manual badge
- Fix shipping data in XML generation
- Fix admin error messages: separate SDI and document errors, no false CF blocker for ricevute
- Update Plugin URI to owner site
- Rename README.txt to readme.txt for WordPress.org compliance
- Fix invoice sending errors and WordPress 6.9 compatibility
- Fix 0% VAT rate handling
- Add user-configurable API endpoints
- Add sandbox/production endpoint toggle
- Improve invoice error display in admin UI
- Fix address/province error when PEC destinatario is missing
- First public release of the FreeInvoice API plugin
- Generation and sending of FatturaPA XML electronic invoices
- Fiscal checkout fields (VAT number, fiscal code, recipient code/PEC)
- Customer data persistence on orders
- Enable/disable invoicing for private individuals
- Dynamic checkout field management
- VAT number and fiscal code validation
- Invoice numbering (automatic/manual)
- 0% VAT rate management with natura codes
- Payment method configuration
- Sandbox mode for testing