=== Yzukar B2B Invoice Fields for KSeF ===
Contributors: rakuzy
Tags: ksef, nip, faktura, e-faktura, faktura b2b
Requires at least: 6.3
Tested up to: 7.1
Requires PHP: 7.4
Requires Plugins: woocommerce
Stable tag: 0.4.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Collect the Polish NIP and B2B invoice data at checkout, validate the NIP checksum locally, export orders to CSV. Classic and block checkout.

== Description ==

Polish B2B customers need an invoice, and an invoice needs the buyer NIP (the Polish tax ID). This plugin collects that data in WooCommerce checkout, checks the NIP checksum before the order is placed, shows the NIP as a column in your order list, and exports the whole set to CSV for your accountant.

= Works in both checkouts: classic and block =

Since version 0.3.0 the fields appear in the classic checkout (shortcode) **and** in the block checkout (Cart & Checkout Blocks, the default in new WooCommerce installs). The plugin declares `cart_checkout_blocks` compatibility, so WooCommerce no longer shows an incompatibility warning. Both paths write exactly the same order data, so the NIP column and the CSV export do not care which checkout your store uses.

= NIP validation without calling anyone =

The NIP is checked **locally**: length, format and the 10-digit checksum. The plugin never sends the number anywhere. No VIES lookup, no whitelist API, no SDK, no telemetry, no external HTTP request of any kind. Zero outbound calls is a deliberate design decision, not a missing feature.

= CSV export for your accountant =

The **WooCommerce > KSeF/NIP Export** screen downloads recent orders as CSV: order number, date, status, whether the customer asked for an invoice, NIP, NIP validation status, company name, billing email, e-invoice email, total and currency. Open it in a spreadsheet or hand it to your accounting office.

= What this plugin does NOT do =

It does not issue invoices, does not generate the FA(3) XML structure, does not connect to the KSeF API, does not authenticate with a certificate and does not download official confirmations. It is a tool for cleaning up invoice data **before** it reaches accounting, not an invoicing application.

The plugin adds:

* A company invoice checkbox in checkout (classic and block).
* A Polish NIP field with checksum validation.
* An optional e-invoice email field.
* Order meta for invoice request, NIP, e-invoice email, and validation status.
* A NIP column in WooCommerce order lists (legacy and HPOS).
* A WooCommerce > KSeF/NIP Export page for recent order CSV export.

The plugin stores data locally in WooCommerce order meta. It does not call external APIs, does not send data to KSeF, and does not include tracking scripts.

Yzukar B2B Invoice Fields for KSeF is a workflow and data-cleanup tool. It does not provide legal, tax, accounting, or KSeF compliance advice and does not guarantee compliance with any law, schema, tax process, platform rule, or accounting requirement.

= Documentation and the optional add-on =

The plugin home page is [ksef.aphexcoding.tech](https://ksef.aphexcoding.tech/): guides on the NIP field, checkout validation and CSV export for accounting, an FAQ, and a free KSeF readiness pack (spreadsheet with an FA(3) field map, a printable checklist and starter CSV templates, all in Polish). The same page describes the optional paid add-on, which is distributed outside WordPress.org and is not required for anything this plugin does.

== Installation ==

1. Upload the `yzukar-b2b-invoice-fields-for-ksef` folder to `/wp-content/plugins/`.
2. Activate the plugin through the Plugins screen in WordPress.
3. Make sure WooCommerce is active.
4. Go to WooCommerce > KSeF/NIP Export to review settings and download CSV exports.
5. Place a test checkout order and confirm the invoice fields appear in the order admin screen.

== Frequently Asked Questions ==

= Does this plugin work with the block checkout (Cart & Checkout Blocks)? =

Yes, since version 0.3.0. The fields are registered through the official WooCommerce Additional Checkout Fields API and appear in the additional order information block. The plugin also declares compatibility with the `cart_checkout_blocks` feature, so WooCommerce no longer shows an incompatibility warning. The classic checkout is unchanged, and both paths save the same order data.

= Where exactly does the NIP field appear in the block checkout? =

In the additional order information block, below the address fields. Validation is identical to the classic checkout: ticking "I need a company invoice" requires a NIP, the NIP must pass the checksum test, and if you require a company name in the settings, it must be filled in.

= Do both checkouts store the data in the same place? =

Yes. Whether the order came from the classic or the block checkout, the NIP, the invoice request, the e-invoice email and the validation status end up in the same order fields. The NIP column in the order list and the CSV export do not distinguish the source.

= Does the plugin send any data anywhere? =

No. Zero external requests, no SDK, no telemetry. The NIP is validated locally and the data stays in your own store database. The links on the plugin screen (the paid add-on and the free readiness pack) are plain links: they carry a marker telling us which screen they were clicked from, they carry nothing about you, and they open only when you click them.

= Does this plugin connect to KSeF or issue invoices? =

No. It does not connect to KSeF, issue invoices, generate FA(3) XML, authenticate with certificates, or download official confirmations. It only helps collect and export invoice-related order data before it reaches your invoicing software or accounting office.

= Does this plugin validate the NIP through an official government API? =

No. The free plugin validates the 10-digit Polish NIP format and checksum locally. It does not verify VAT status or bank account assignment on the official whitelist.

= Which WordPress and WooCommerce versions are supported? =

WordPress 6.3 or newer, PHP 7.4 or newer, and WooCommerce 8.9 or newer. The plugin declares compatibility with HPOS (High-Performance Order Storage) and with the block checkout. WooCommerce 8.9 is the release that introduced the Additional Checkout Fields API the block checkout support is built on; below it the block checkout would silently show no invoice fields, so the plugin declares that floor instead.

= What is the free KSeF readiness pack on the plugin screen? =

A separate ZIP hosted on the plugin's landing page, downloaded only if you click the link. It holds a spreadsheet workbook with an FA(3) field map, a printable KSeF checklist and starter CSV templates for an invoice register and a contractor NIP list. The documents are in Polish. It is planning material, not an invoicing tool, and nothing in the plugin depends on it.

= Is there a paid version? =

Yes. The free plugin is fully usable on its own for collecting and exporting invoice fields, and nothing here is time-limited or locked behind a trial. A separate paid add-on, distributed outside WordPress.org, adds saved export profiles, XLSX export with FA(3) field mapping, and bulk actions.

= The plugin screen offers a trial. What is on trial, and does it need a card? =

The trial covers the paid add-on only, never this plugin: everything the free plugin does stays free and unlimited whether you start a trial or not. It runs for 14 days, starts without a card or PayPal details, and expires on its own if you do nothing, so nothing can be charged automatically. The link is a plain link on the plugin's own screen and it opens only when you click it.

== Screenshots ==

1. WooCommerce > KSeF/NIP Export screen: export orders to CSV for your accountant.
2. WooCommerce checkout with B2B fields: invoice request, NIP, and e-invoice email.
3. Invoice data panel in the order view (NIP, company, validation status).
4. WooCommerce order list with the NIP column.

== Changelog ==

= 0.4.0 =
* Added a free KSeF readiness pack section on the plugin's own screen: a spreadsheet with an FA(3) field map, a printable checklist and starter CSV templates, as a plain download link.
* The add-on box now offers the 14-day trial directly, next to the existing link to the add-on page. The trial needs no card and expires on its own; nothing in the free plugin becomes limited.
* Outbound links on the plugin screen carry a source marker so the destination page can tell which screen they were clicked from. No identifier, no cookie, no fingerprint, and still zero requests made by the plugin itself.
* Added the `Plugin URI` header and a link to the plugin home page in this readme.
* Declared the supported WooCommerce range through the `WC requires at least` (8.9) and `WC tested up to` (11.0) headers. WooCommerce 8.9 introduced the Additional Checkout Fields API that the block checkout support needs.
* Replaced the `invoice fields` tag with `faktura b2b`, which is what Polish stores actually search for.

= 0.3.0 =
* Block checkout support: invoice request, NIP, and e-invoice email are now registered through the WooCommerce Additional Checkout Fields API and appear in Cart & Checkout Blocks.
* Declared compatibility with the `cart_checkout_blocks` feature, so WooCommerce no longer shows an incompatibility warning.
* Both checkout paths write the same order meta, so the NIP column and the CSV export are unchanged.
* Same validation rules in both checkouts: NIP checksum, NIP required when the invoice box is ticked, optional company name requirement, e-invoice email format.
* Added a "Settings" link next to the plugin on the Plugins screen.
* Added a one-line, permanently dismissible review link on the plugin's own screen only.
* Rewrote the readme in English per the WordPress.org readme language policy, with new FAQ entries about the block checkout.

= 0.2.0 =
* Added a discreet, permanently dismissible add-on notice on the plugin's own screen only. No SDK, no telemetry, no external requests, and no free feature is limited.
* Documented in the FAQ that the plugin makes no external calls.

= 0.1.1 =
* Renamed per WordPress.org plugin review (trademark). New name and slug: Yzukar B2B Invoice Fields for KSeF / yzukar-b2b-invoice-fields-for-ksef. No functional changes.

= 0.1.0 =
* Initial local build with checkout fields, NIP checksum validation, order meta, order column, settings, and CSV export.
