=== Fiscalo for WooCommerce ===
Contributors: fiscalo
Tags: woocommerce, invoicing, invoice, portugal, billing
Requires at least: 6.5
Tested up to: 7.0
Requires PHP: 8.1
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html
Requires Plugins: woocommerce

Issue Fiscalo fiscal documents from WooCommerce orders with secure API keys, PDF sync, logs, and manual or bulk billing flows.

== Description ==

Declared compatibility:

* WordPress 6.5 or higher
* WooCommerce 8.0 or higher
* PHP 8.1 or higher
* HPOS (Custom Order Tables) compatibility declared for the current architecture
* WooCommerce Blocks compatibility prepared for the order-event driven workflow
* Admin UI defaults to pt_PT, with translation files prepared for additional locales

Fiscalo for WooCommerce connects your store to the Fiscalo public API so you can:

* test the connection against sandbox or production
* create or sync customers from WooCommerce orders
* list pending orders in `Fiscalo > Encomendas`
* issue documents manually or in bulk
* create draft documents
* add lines based on order items
* issue Fiscalo documents
* generate and store the document PDF locally
* browse emitted documents and PDFs directly from WordPress admin
* inspect technical integration logs
* choose the tax number meta field used by the checkout flow
* create Fiscalo items automatically and reuse SKU-based mappings
* keep API keys, tokens, and sensitive headers masked

The plugin is intended for stores operating in Portugal that want to delegate fiscal document logic to Fiscalo without rebuilding invoicing rules inside WordPress.

Official links:

* Website: `https://www.fiscalo.pt`
* Docs: `https://docs.fiscalo.pt/integrations/woocommerce`
* Support: `https://www.fiscalo.pt/suporte`

== Installation ==

1. Download the `fiscalo-for-woocommerce.zip` package.
2. In WordPress, open `Plugins > Add New > Upload Plugin`.
3. Confirm WooCommerce is installed and active.
4. Upload the `.zip` file and activate the plugin.
5. Open `Fiscalo > Configurações`.
6. Configure the environment, API key, and automatic billing rules.
7. Click `Testar ligação` before enabling every automatic trigger.
8. Emit the first order manually to validate the end-to-end flow.
9. Open `Fiscalo > Encomendas` to review the operational queue, correct the tax number when needed, and generate documents in bulk.
10. Open `Fiscalo > Documentos` to track emitted documents, local PDFs, and linked WooCommerce orders.

Official base URL:

* `https://api.fiscalo.pt/api/v1`
* Sandbox API keys start with `fisc_test_*`
* Production API keys start with `fisc_live_*`

== Frequently Asked Questions ==

= Does the plugin require WooCommerce to be active? =

Yes. The plugin depends on WooCommerce hooks, order screens, and order data structures.

= What happens if I activate the plugin without WooCommerce? =

The plugin does not fatal. It shows an admin notice and blocks operational configuration until WooCommerce is installed and active.

= Where do I find the API key? =

In the Fiscalo dashboard, inside the API Keys area for the selected environment.

= Where can I get support? =

Use the official support channel at `https://www.fiscalo.pt/suporte` and keep the integration logs available when reporting an issue.

= Does the connection test use the values currently shown in the form? =

Yes. The test uses the environment, base URL, and API key currently visible on screen, even before saving.

= Does the connection test validate the API key? =

Yes. The test performs an authenticated request against a lightweight Fiscalo endpoint to confirm that the base URL and API key can access the configured environment.

= What should I do if I get cURL error 60 in a local environment? =

Confirm the configured Fiscalo base URL and trust the certificate used by the current environment in your operating system.

= Is the API key stored in plain text? =

No. The key is encrypted in `wp_options` and is always shown masked in the admin UI.

= Does the plugin communicate directly with the Portuguese tax authority? =

No. The plugin talks to the Fiscalo public API. Fiscal logic and compliance roadmap belong to the Fiscalo platform itself.

= Does the plugin create duplicate documents? =

The workflow uses `Idempotency-Key` values per order and per critical step. Even so, you should validate the integration in sandbox and review the logs before automating the whole store.

= Can I consult documents and PDFs without opening app.fiscalo.pt? =

Yes. `Fiscalo > Documentos` lets you list emitted documents, inspect fiscal details, open the linked WooCommerce order, and download the PDF directly from WordPress.

= Where do I configure the customer tax number field? =

In `Fiscalo > Configurações`, under `Campo NIF / Contribuinte`. The default is `_billing_nif`, and the plugin also tries known fallbacks such as `billing_nif`, `_billing_vat`, and `billing_tax_number`.

= Does the plugin need another plugin to collect the tax number? =

No. By default Fiscalo adds a `NIF / Contribuinte` field to WooCommerce checkout and stores it in `_billing_nif`. If another plugin already exposes a known field, Fiscalo switches to compatibility mode and avoids duplicates.

= Is there manual or bulk issuance? =

Yes. `Fiscalo > Encomendas` lists orders that are not yet billed and allows manual issuance, bulk issuance, or marking an order to be ignored.

= Is there a local end-to-end test? =

Yes. The project includes the `scripts/fiscalo-e2e-order-sync.php` helper to create a product, create a test order, write `_billing_nif = 999999990`, and execute the real `OrderSyncService::syncOrder()` flow.

== Screenshots ==

1. Dashboard with integration status, recent activity, API health, and quick actions.
2. Settings screen with environment, API key, connection test, automatic billing triggers, and cleanup controls.
3. Documents screen with filters, WooCommerce order links, and direct PDF access.
4. Orders queue with manual issuance, bulk issuance, operational status, and tax number visibility.
5. Technical logs with sanitized request/response payloads and operational events.
6. Help and onboarding screen with setup checklist and documentation links.

== Changelog ==

= 1.0.0 =

* First WordPress.org release of Fiscalo for WooCommerce.
* Commercial plugin header, readme, screenshots, and WordPress.org assets finalized for submission.
* Compatibility validated for WordPress 6.5+, WooCommerce 8.0+, and translation files prepared.
* Operational order queue, configurable tax number handling, and local end-to-end helper flow.

== Upgrade Notice ==

= 1.0.0 =

First WordPress.org release of Fiscalo for WooCommerce, including sandbox support, automatic billing triggers, operational logs, and direct document consultation inside WordPress.
