=== Invoicing Integration for wFirma and WooCommerce ===
Contributors: devikit
Tags: wfirma, invoice, woocommerce, accounting, faktura
Requires at least: 5.8
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.0.20
License: GPLv3
License URI: https://www.gnu.org/licenses/gpl-3.0.html

Seamless integration between WooCommerce and wFirma accounting system for Polish businesses.

== Description ==

**Invoicing Integration for wFirma and WooCommerce** connects your WooCommerce store with the popular wFirma accounting system used by thousands of Polish businesses.

https://youtu.be/HtXbBeJH9aU

= Key Features (FREE) =

* **Manual Invoice Generation** - Create invoices directly from WooCommerce order edit screen
* **Customer Synchronization** - Automatically sync customer data with wFirma contractors
* **NIP Field Support** - Add VAT number field to checkout (compatible with nip-field-woocommerce plugin)
* **WooCommerce Blocks Support** - Full compatibility with Gutenberg checkout blocks
* **Advanced VAT Mapping** - Map WooCommerce tax classes to wFirma VAT codes (23%, 8%, 5%, zw, np, 0%)
* **Invoice Download** - Download invoices directly from WordPress admin
* **Customer Download** - Allow customers to download their invoices from My Account page
* **Global Invoice Notes** - Set default notes (uwagi) for all invoices and proformas with variable placeholders ({order_number}, {customer_name}, etc.)
* **Detailed Logging** - Track all API communications for debugging
* **HPOS Compatible** - Full support for WooCommerce High-Performance Order Storage

= PRO Features =

* **Automatic Invoice Generation** - Create invoices automatically on order status change
* **Automatic Proforma Invoices** - Issue proformas automatically for pending orders
* **Receipt (Paragon) Support** - Automatic receipt generation for retail customers, including fiscal receipts (paragony fiskalne) and sales receipts (dowody sprzedaży / paragony niefiskalne)
* **Receipt Notes** - Set default notes (uwagi) for all receipts with variable placeholders ({order_number}, {customer_name}, etc.)
* **Email with PDF Attachments** - Send invoices directly to customers as PDF attachments
* **Bulk Document Generation** - Generate invoices, proformas, and receipts for multiple orders at once with progress tracking
* **Bulk Email Sending** - Send invoices and proformas by email to multiple customers in bulk operations
* **MOSS / EU VAT OSS Support** - Automatic MOSS handling for digital services sold to EU customers with proper VAT evidence
* **Advanced Automation** - Configure multiple trigger statuses and conditions
* **Ryczałt ewidencjonowany** - Global and per-product flat-rate tax (ryczałt) settings with automatic lumpcode on invoices and receipts
* **Dekretacja** - Accounting classification for invoices
* **Warehouse Integration** - Bi-directional stock sync between WooCommerce and wFirma
* **Real-time Webhooks** - Instant stock updates from wFirma
* **WooCommerce Subscriptions** - Full support for recurring invoices
* **Priority Support** - Direct access to our support team
* **Automatic Updates** - Get new features and fixes automatically

[**Get PRO Version**](https://devikit.pl/produkt/wfirma-woocommerce-pro/)

= Requirements =

* WordPress 5.8 or higher
* WooCommerce 5.0 or higher
* PHP 7.4 or higher
* Active wFirma account with API access

== Installation ==

1. Upload the plugin files to `/wp-content/plugins/invoicing-integration-for-wfirma-and-woocommerce/`
2. Activate the plugin through the 'Plugins' menu in WordPress
3. Go to WooCommerce → wFirma
4. Enter your wFirma Access Key and Secret Key
5. Test the connection and configure settings

== Frequently Asked Questions ==

= Where do I find my wFirma API keys? =

Log in to your wFirma account, go to Settings → Applications → API Keys, and generate your Access and Secret keys.

= Does this work with WooCommerce Blocks? =

Yes, the plugin is compatible with both classic checkout and WooCommerce Blocks checkout.

= Can customers download their invoices? =

Yes, customers can download invoices from the My Account → View Order page.

= Is this compatible with nip-field-woocommerce plugin? =

Yes! The plugin automatically detects if nip-field-woocommerce is active and uses it instead of adding its own NIP field.

== External services ==

This plugin relies on the wFirma API, a third-party accounting service, to generate invoices and manage customer data.

= What is wFirma API? =

wFirma is a Polish online accounting system that provides invoicing and accounting services for businesses. This plugin uses their official API to:
*   Create and manage customers (contractors) in your wFirma account.
*   Generate invoices and proforma invoices (PRO version).
*   Generate receipts (paragony fiskalne) and sales receipts (dowody sprzedaży / paragony niefiskalne) for retail customers (PRO version).
*   Retrieve bank accounts, VAT codes, and other accounting data from your wFirma account.
*   Download invoice PDFs.
*   Synchronize warehouse stock between WooCommerce and wFirma (PRO version).

= What data is sent and when? =

The plugin sends the following data to wFirma API (https://api2.wfirma.pl/) in these situations:

**When you click "Create Invoice" or when automatic invoice generation is triggered (PRO version):**
*   Customer billing information: first name, last name, company name, VAT number (NIP), email, phone number, billing address (street, city, postal code, country).
*   Order information: order items (product names, quantities, prices, VAT rates), shipping details, payment method, order date, order total.

**When the plugin connects to wFirma API (on settings page load or when needed):**
*   Your wFirma Access Key and Secret Key (for authentication).
*   Requests to retrieve your account settings: bank accounts, VAT codes, income categories, warehouse data (PRO version).

**No data is sent automatically without your action.** The plugin only communicates with wFirma API when:
*   You manually create an invoice from the order screen.
*   You enable automatic invoice generation in PRO version.
*   You open the plugin settings page (to load account configuration).
*   Warehouse synchronization is enabled in PRO version (webhook).

= Service provider information =

*   **Service name:** wFirma API
*   **Service URL:** https://www.wfirma.pl/
*   **API documentation:** https://doc.wfirma.pl/
*   **Terms of Service:** https://pomoc.wfirma.pl/-regulamin-swiadczenia-uslug
*   **Privacy Policy:** https://pomoc.wfirma.pl/-polityka-prywatnosci

By using this plugin, you acknowledge that customer and order data will be transmitted to wFirma for invoice generation purposes. You are responsible for ensuring compliance with applicable data protection laws (including GDPR) and informing your customers about this data processing.

== Screenshots ==

1. Plugin settings
2. Plugin settings
3. Plugin settings
4. Plugin settings
5. Plugin settings
6. Plugin settings
7. Plugin settings
8. Plugin settings
9. Plugin settings
10. Plugin settings
11. Plugin settings
12. Plugin settings
13. Plugin settings


== Changelog ==

= 1.0.20 =
* Add: Devikit Care banner in WordPress admin with dismiss options
* Add: Devikit Care sidebar widget on plugin settings page
* Add: Devikit Care dashboard widget
* Fix: Pro upgrade banner restyled to match Care banner style

= 1.0.19 =
* Fixed: OSS/MOSS invoices with decimal VAT rates (e.g. Finland 25.5%) no longer round to a whole percent when resolving wFirma VAT codes.

= 1.0.18 =
* Fixed: MOSS and VAT mapping tax class fields now save WooCommerce "Standard rate" (empty slug) instead of resetting to None.

= 1.0.17 =
* Fixed: OSS/MOSS invoices now use the WooCommerce order VAT rate and wFirma VAT code for the buyer's EU country (e.g. 19% for DE) instead of default Polish 23%.
* Fixed: MOSS sale type code WO for distance selling of goods (wFirma API; UI label WSTO).
* Added: Full built-in list of wFirma OSS sale type codes (WO, SA–TK, BA, BB, INNE).

= 1.0.16 =
* Fixed: PRO upgrade banner styling after WordPress 7.0 admin refresh (button borders and notice link styles).
* Improved: Banner layout with dedicated CSS and increased top padding.

= 1.0.15 =
* Fix: NIP field now saves correctly in WP Admin user profile and synchronises with My Account edit address (bidirectional sync).
* Fix: NIP is now populated when selecting a customer or clicking "Load billing address" in admin order edit screen.

= 1.0.14 =
* Changed: Tested up to WordPress 7.0

= 1.0.13 =
* Added: Demo video (YouTube) in readme description
* Improved: Highlighted PRO purchase link in readme

= 1.0.12 =
* Fixed: save_admin_order_nip - WooCommerce may pass WP_Post instead of WC_Order; use instanceof WC_Order check to avoid "Call to undefined method WP_Post::update_meta_data()"

= 1.0.11 =
* Added: NIP is now editable in order admin (billing section) - same as address fields
* Improved: Removed duplicate read-only NIP display when editing order

= 1.0.10 =
* Fixed: Prevent duplicate invoices when create_invoice_for_order is called multiple times (e.g. bulk generation)

= 1.0.9 =
* Added: Total mismatch warning (order vs invoice/proforma sum) now displayed in wFirma column on orders list, not just in order metabox
* Improved: Bulk invoice generation - mismatch detection visible at a glance in orders list

= 1.0.7 =
* Improved: Polish translations for Invoice Notes and receipt-related strings
* Improved: Receipt Notes section grayed out in FREE version (PRO feature)
* Improved: Readme documentation - global invoice notes, receipt notes, ryczałt

= 1.0.6 =
* Added: Global invoice notes (uwagi) in settings - default notes for all invoices and proforma invoices
* Added: Global receipt notes in settings - default notes for non-fiscal receipts (dowody sprzedaży)
* Added: Variable placeholders for notes: {order_id}, {order_number}, {customer_name}, {order_total}, etc. (same as Fakturownia)

= 1.0.5 =
* Added: 5-minute delayed email sending for automatic invoices to allow KSeF (National e-Invoice System) processing
* Added: Action Scheduler handler for delayed invoice email delivery
* Improved: Manual email sending from admin panel and proforma/receipt emails remain instant
* Added: Polish translations for new KSeF delay messages

= 1.0.4 =
* Added: Screenshots added to plugin assets folder and readme documentation

= 1.0.3 =
* Added: Information about sales receipts (dowody sprzedaży / paragony niefiskalne) support in PRO version to readme
* Improved: FREE version UI now shows all PRO features including email sending, payment deadline, and bank account settings for receipts
* Fixed: Added missing translations for receipt email functionality

= 1.0.2 =
* Dev: Release automation for WordPress.org SVN (no functional changes)

= 1.0.1 =
* Fixed: Added support for non-VAT invoice series (bill type) in addition to VAT invoices (normal type)
* Fixed: Users can now select from all available invoice series, not just VAT invoices
* Fixed: Invoice type is now correctly set based on selected series type to prevent errors for non-VAT businesses

= 1.0.0 =
* Initial release
* Manual invoice generation
* Customer synchronization
* Advanced VAT mapping
* Customer invoice download
* NIP field support with compatibility

== Upgrade Notice ==

= 1.0.20 =
Added Devikit Care promotional widgets: admin banner, settings page sidebar, and dashboard widget.

= 1.0.19 =
Fixed OSS/MOSS decimal VAT rates (e.g. 25.5% for Finland) when matching wFirma VAT codes.

= 1.0.18 =
Fixed saving WooCommerce Standard tax class for MOSS/VAT mapping fields.

= 1.0.17 =
OSS/MOSS invoices now apply the correct EU destination VAT rate; use sale type WO (WSTO) for physical goods.

= 1.0.16 =
Fixed PRO upgrade banner styling for WordPress 7.0 admin refresh.

= 1.0.14 =
Tested up to WordPress 7.0.

= 1.0.13 =
Readme: demo video and clearer PRO upgrade link.

= 1.0.12 =
Fixed WP_Post vs WC_Order compatibility when saving NIP in order admin.

= 1.0.11 =
NIP can now be edited in the order admin billing section, just like the address fields.

= 1.0.10 =
Fixed duplicate invoice creation when bulk generating invoices.

= 1.0.9 =
Total mismatch (order vs invoice sum) is now visible in the wFirma column on the orders list for quick identification.

= 1.0.7 =
Polish translations for invoice notes. Receipt notes are now a PRO-only feature (grayed out in FREE).

= 1.0.6 =
Added global notes for invoices, proformas and receipts with variable placeholders (e.g. order number, customer name).

= 1.0.5 =
Automatic invoice emails are now delayed by 5 minutes to allow KSeF processing before sending to customers.

= 1.0.4 =
Added screenshots to plugin documentation.

= 1.0.3 =
Improved UI and documentation. Updated information about PRO features including sales receipts (dowody sprzedaży) support.

= 1.0.2 =
Dev: Release automation for WordPress.org SVN (no functional changes)

= 1.0.1 =
Fixed issue where only VAT invoice series were available for selection. Now supports both VAT and non-VAT invoice series.

= 1.0.0 =
Initial release of the plugin.

