=== FreeInvoice API ===
Contributors: cloudfinance
Tags: fatturazione elettronica, fattura elettronica, fattura xml, codice destinatario, woocommerce, invoice, sdi, ricevute, ordini
Requires at least: 5.2
Tested up to: 6.9
Requires PHP: 7.2
Stable tag: 1.1.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Generate and send Italian electronic invoices (FatturaPA) and FreeInvoice documents (ordini, ricevute) from WooCommerce orders via the FreeInvoice API.

== Description ==

**FreeInvoice API** connects your WooCommerce store to the [FreeInvoice](https://www.cloudfinance.it/free-invoice-api.html) service, automating the generation and transmission of Italian electronic invoices and commercial documents.

= Key Features =

* **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 private customers** — Private customers without a fiscal code are automatically 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.
* **Classic checkout support** — Works with both the traditional WooCommerce checkout and the Checkout Block.
* **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** — Receive real-time status updates from the FreeInvoice service via webhook integration.
* **Conditional checkout fields** — Fiscal fields (VAT number, fiscal code, recipient code / PEC) appear dynamically based on whether the customer selects "Individual" or "Company/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 and English UI** — The plugin interface is available in both Italian and English.

= Prerequisites =

* An active [FreeInvoice API](https://www.cloudfinance.it/free-invoice-api.html) account
* WooCommerce installed and active

= Documentation =

* [FreeInvoice Plugin Documentation](https://help.cloudfinance.it/guida-online-category/plugin-freeinvoice-wordpress-woocommerce/)

== Installation ==

= Minimum requirements =

* WordPress 5.2 or later
* PHP 7.2 or later
* WooCommerce installed and active
* An active FreeInvoice API account

= Automatic installation =

1. Go to Plugins → Add New in your WordPress admin.
1. Search for "FreeInvoice API".
1. Click Install Now and then Activate.

= Manual installation via WordPress admin =

1. Download the plugin zip file.
1. Go to Plugins → Add New → Upload Plugin.
1. Choose the zip file and click Install Now.
1. Click Activate.

= Manual installation via FTP =

1. Download and unzip the plugin.
1. Upload the `freeinvoice-api` folder to `/wp-content/plugins/`.
1. Activate the plugin from the Plugins menu.

= After activation =

1. Go to WooCommerce → Settings → FreeInvoice API.
1. Enter your FreeInvoice API credentials.
1. Configure your seller data, tax regime, and VAT rates.
1. Choose whether to use sandbox or production mode.

== Frequently Asked Questions ==

= 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](https://www.cloudfinance.it/free-invoice-api.html).

= Does this plugin support the WooCommerce Checkout Block? =

Yes. The plugin uses the WooCommerce Additional Checkout Fields API to add fiscal fields to both the classic checkout and the WooCommerce Checkout Block. Fields appear conditionally based on customer type.

= 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 a fiscal code? =

When a private customer does not provide a fiscal code at checkout, the plugin automatically routes 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.

= 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.

= 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.

== Screenshots ==

1. General plugin settings
2. Seller data configuration
3. Invoice management setup
4. 0% VAT rate management
5. Payment method configuration
6. Invoice/document send dialog
7. Invoice batch purchase
8. Invoice numbering settings
9. Fiscal fields during WooCommerce checkout
10. Fiscal data in WooCommerce order detail
11. Invoice/document status in WooCommerce orders list

== Changelog ==

= 1.1.0 =
* 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

= 1.0.3 =
* 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

= 1.0.0 =
* 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

== Upgrade Notice ==

= 1.1.0 =
Major update: adds WooCommerce Checkout Block support, HPOS compatibility, FreeInvoice document flow (ordini/ricevute), auto-send on order completion, and ricevute for private customers without fiscal code. Please review your plugin settings after upgrading.