=== Factulit VeriFactu ===
Contributors: factulit
Tags: verifactu, invoices, woocommerce, aeat, spain
Requires at least: 6.1
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 2.3.3
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Free WooCommerce connector for Factulit: turn orders and refunds into VeriFactu invoices and submit billing records to the AEAT.

== Description ==

Factulit VeriFactu is the free plugin that connects WooCommerce to [Factulit](https://factulit.es), a Spanish VeriFactu invoicing service. Keep managing orders and refunds in WooCommerce while Factulit generates the invoices, chained billing records and AEAT submissions.

**What the plugin does**

* Syncs orders, customers and the order-status catalog with your Factulit account.
* Lets you decide which WooCommerce statuses invoice, cancel or refund before explicitly activating invoicing.
* Generates hash-chained billing records in Factulit and submits them to the Spanish Tax Agency (AEAT).
* Tracks full and partial refunds against the corresponding invoice, with per-line detail.
* Keeps pending work in a local retry queue and shows connection health and exact progress.
* Gives eligible customers a protected "View invoices" action in WooCommerce My Account and order views.
* Declares compatibility with WooCommerce High-Performance Order Storage (HPOS / custom order tables).

**Who it is for**

Spanish WooCommerce stores that issue invoices for online sales and want Factulit to handle billing-record generation, hash chaining and AEAT submission.

**An account with Factulit is required**

This plugin is free, but it is a client for the Factulit SaaS. Without a Factulit account and a valid API key, it will not generate invoices or send anything to AEAT; it only prepares and queues data locally. [Create your account](https://factulit.es) and follow the guided connection, series and activation steps. The service has a Free plan for up to 50 invoices per month and paid plans for higher volume; see the [current plans and limits](https://factulit.es/precios).

= External services =

This plugin relies on the external **Factulit** SaaS (https://factulit.es) to generate invoices, billing records and AEAT submissions. It has a free tier and paid plans (https://factulit.es/precios). Configuring the plugin means accepting the Factulit Terms and Conditions and Privacy Policy.

The plugin communicates only with the two fixed Factulit API endpoints: `https://api.sandbox-factulit.es/api` for Demo and `https://api.factulit.es/api` for Production. The active endpoint is part of the server-issued, versioned connection binding; it changes atomically together with the binding generation and the environment-specific API credential. The settings screen never accepts an arbitrary API URL, and a queued row always keeps the endpoint and binding under which it was created. Moving from Demo to Production uses this same installed plugin and never redirects old Demo rows to Production. It sends:

* **Customer data**, when a customer record is synced: first name, last name, email, phone, tax ID (NIF/NIE/CIF), address, postal code and city.
* **Order data**, when an order is synced: the order and its line items, needed to generate the corresponding invoice.
* **Invoice-link data**, when a customer opens the WooCommerce order list or an order: up to 50 WooCommerce order IDs are sent through `invoice-availability`. When the customer selects "View invoices", that order ID is sent through `invoice-access` and Factulit returns a short-lived viewer URL. The browser is redirected only to the HTTPS viewer for the active Factulit environment (`vf.factulit.es` in Production or `sandbox-factulit.es` in Demo); the plugin never exposes the API key to the browser.
* **Order-status catalog data**: the list of WooCommerce order statuses used in your store, so their fiscal classification (which statuses trigger an invoice, a cancellation or a refund) can be configured on the Factulit side.
* **Connection and version data**, at most once every 12 hours: the installed plugin version, the WooCommerce/CMS version, the store's site URL, the URL of this store's sync (cron) endpoint and the bearer token that protects that endpoint. The version data is used to tell you when a newer plugin version is available. The endpoint URL and its token are what allow Factulit to call your store back to run a sync; without them the service cannot reach your store. That token is generated by the plugin, is specific to your store, and can be rotated at any time from the plugin's settings screen, which invalidates the previous one.

This data exchange is required for the plugin to function: it is how your store's orders become VeriFactu invoices and billing records. No data is sent to Factulit before you configure a valid API key.

Terms and Conditions: https://factulit.es/condiciones-de-contratacion
Privacy Policy: https://factulit.es/politica-de-privacidad

== Installation ==

1. Install and activate WooCommerce if it is not already active.
2. Install the plugin through the WordPress plugins screen, or upload the plugin files to `/wp-content/plugins/factulit-verifactu/`.
3. Activate Factulit VeriFactu through the "Plugins" screen.
4. Go to the "Factulit VeriFactu" menu and enter your Factulit API key. If you do not have a Factulit account yet, sign up at https://factulit.es.
5. Configure the fiscal classification of your order statuses from your Factulit account (which statuses generate an invoice, a cancellation or a refund).
6. Use "Sync now" for an initial manual sync. From then on, Factulit triggers the synchronisation of your store automatically while the connection is active — you do not need to set up any server cron.

== Frequently Asked Questions ==

= How does synchronisation work? Do I need to set up a cron job? =

Synchronisation works without one, but scheduling it is strongly recommended. There are three channels:

* **Automatic.** Factulit calls the protected store endpoint while the connection is active.
* **Store cron (recommended fallback).** Your hosting calls the same endpoint, so it continues working if a firewall blocks incoming Factulit calls. The settings screen provides the protected URL for wget or curl.
* **Manual.** "Sync now" processes pending data in batches and shows live progress.

The settings screen records the last successful run of each channel.

= Do I need a Factulit account to use this plugin? =

Yes. The plugin only prepares and queues WooCommerce data locally; invoices, billing records and AEAT submissions are generated by the Factulit service, which requires an account and a valid API key.

= What data does the plugin send to Factulit? =

Customer data needed to issue an invoice (name, email, phone, tax ID, address, postal code, city), order data, up to 50 order IDs when checking invoice availability, the selected order ID when opening its invoices, your store's order-status catalog, and, at most once every 12 hours, connection and version data: installed plugin version, WooCommerce/CMS version, site URL, the sync endpoint URL and the bearer token protecting it. See the "External services" section above for the full disclosure.

= Is it compatible with WooCommerce High-Performance Order Storage (HPOS)? =

Yes. The plugin explicitly declares compatibility with the `custom_order_tables` feature, and it is tested with HPOS both enabled and disabled.

= In which languages is the plugin available? =

The source language is English. The direct-download build includes a Spanish (es_ES) translation. The WordPress.org build uses language packs from translate.wordpress.org, so Spanish availability there depends on the translation project.

= How do customers open their invoices? =

When Factulit reports invoices for an order, WooCommerce shows a protected "View invoices" action to the order owner. The plugin requests a short-lived viewer link without exposing the API key to the browser.

== Screenshots ==

1. Settings screen: connection status, API key field, and the fiscal-classification notice pointing to the Factulit panel.
2. Sync screen: synchronisation health, exact order progress, the three sync channels, the "Sync now" action and recovery actions when needed.
3. Update notice: the inline admin notice shown when a newer plugin version is available, with release notes.
4. Cron block: the read-only cron endpoint URL and the "Rotate cron token" action.
5. Factulit dashboard with demo sales, invoicing and VeriFactu status.
6. AEAT registration and invoice status in Factulit, using demo data.

== Changelog ==

= 2.3.3 =
* Adds privacy-safe demo screenshots of the Factulit dashboard and AEAT invoice status.

= 2.3.2 =
* Improves the WordPress.org listing with clearer plugin-versus-service wording, customer outcomes, onboarding and invoice-access information.

= 2.3.1 =
* Restricts customer invoice redirects to the exact HTTPS Factulit viewer host and capability path for the active environment.
* Expands the external-service disclosure for invoice-availability and invoice-access requests, and clarifies WordPress.org language-pack availability.
* Makes release packages reproducible when source files use different line endings.

= 2.3.0 =
* A refund that includes shipping now reports the refunded shipping as a fiscal line with its own base, tax amount and tax rate, so the corrective invoice can rectify it. The rate is taken from the tax lines WooCommerce declares for the refunded shipping and corroborated against the shipping of the original order; when it cannot be derived without ambiguity, the refund keeps its previous form and is reviewed manually.

= 2.2.0 =
* Adds secure customer invoice links to the WooCommerce account and order views when Factulit provides them.

= 2.1.0 =
* Onboarding in 3 steps: the plugin reports its order inventory when connecting, before syncing any order.

Older release history is included in `changelog.txt`.
