From 12f1dde081fb22e4c91eba9628ad1e6958c67cba Mon Sep 17 00:00:00 2001 From: deboragracio Date: Fri, 11 Sep 2026 12:14:52 +0200 Subject: [PATCH 1/3] docs(pl): add E-Invoicing Overview + Setup pages for Poland MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Apply the approved standard (Germany) to Poland, adapted to its specifics, and place the pages under the now-merged middleware-pl folder (its existing Country-Specific Guides block): - Overview: slimmed to market-specific (regulatory status, terminology), links the generic page. Centralised KSeF clearance, FA(3), mandate live since Feb/Apr 2026, KSeF number. - Setup: prerequisites (incl. the PLN-currency requirement — Poland is not a euro market), Portal enablement (draft), and a real /sign -> /issue example (B2B invoice case codes, PL buyer, VAT 23, Currency PLN top-level and per item), status polled via GET /issue/{queueId}/{queueItemId} until cleared by KSeF. Marked as preview, with developer-platform Try-it links. Co-Authored-By: Claude Opus 4.8 --- .../middleware-pl/e-invoicing/overview.md | 39 ++++++ .../middleware-pl/e-invoicing/setup.md | 114 ++++++++++++++++++ poscreators/toc.js | 9 ++ 3 files changed, 162 insertions(+) create mode 100644 poscreators/middleware-doc/middleware-pl/e-invoicing/overview.md create mode 100644 poscreators/middleware-doc/middleware-pl/e-invoicing/setup.md diff --git a/poscreators/middleware-doc/middleware-pl/e-invoicing/overview.md b/poscreators/middleware-doc/middleware-pl/e-invoicing/overview.md new file mode 100644 index 00000000..28273e7b --- /dev/null +++ b/poscreators/middleware-doc/middleware-pl/e-invoicing/overview.md @@ -0,0 +1,39 @@ +--- +slug: /poscreators/middleware-doc/poland/e-invoicing/overview +title: Overview +--- + +# eInvoicing in Poland — Overview + +eInvoicing works the same way across fiskaltrust markets — the shared model, the `/sign` + `/issue` flow, and the no-webhook rule are described in **[eInvoicing — Overview](../../e-invoicing/overview.md)**. This page covers only what's specific to the **Polish (PL)** market. + +## Regulatory status + +| Aspect | Current status | +| --- | --- | +| Scope | **B2B.** | +| Regulatory model | **Centralised clearance** — KSeF validates every invoice and assigns a **KSeF number** before it is legally effective. | +| Live since | **1 February 2026** (turnover above 200 million PLN); **1 April 2026** for everyone else. Both waves have passed. | +| Next changes | KSeF number required in payment transfer titles from **August 2026**; penalties begin **January 2027**. | +| Format | **KSeF FA(3)** — Poland's national invoice schema. | + +:::info The mandate is already live +Both waves of the B2B mandate have passed (turnover above 200 million PLN from 1 February 2026; everyone else from 1 April 2026). From **August 2026** the KSeF number must be carried in payment transfer titles, and **penalties begin January 2027**. +::: + +## Terminology + +| Term | Meaning | +| --- | --- | +| **KSeF** | *Krajowy System e-Faktur*, Poland's centralised national clearance platform. | +| **FA(3)** | The current version of Poland's national invoice schema. | +| **KSeF number** | The identifier assigned on clearance, required in payment transfer titles from August 2026. | +| **Peppol BIS** | A separate Polish track from KSeF — not a candidate syntax for the domestic B2B mandate. | + +## Related pages + +- [eInvoicing — Overview](../../e-invoicing/overview.md) — the shared model, integration flow, and prerequisites across markets. +- [Set up and test eInvoicing (Poland)](./setup.md) — prerequisites, Portal enablement, and the end-to-end sandbox example. +- [Delivery (`/issue` Endpoint)](../../experience-middleware/delivery.md) — the product-level eInvoicing and e-Delivery concept across all markets. +- [Migrating from API v0 to PosSystem API (v2)](../../possystem-api/migration-guide.md) — eInvoicing is a PosSystem API (v2) feature. +- [Appendix: PL](../appendix-pl.md) — Poland fiscalization details. diff --git a/poscreators/middleware-doc/middleware-pl/e-invoicing/setup.md b/poscreators/middleware-doc/middleware-pl/e-invoicing/setup.md new file mode 100644 index 00000000..60180b09 --- /dev/null +++ b/poscreators/middleware-doc/middleware-pl/e-invoicing/setup.md @@ -0,0 +1,114 @@ +--- +slug: /poscreators/middleware-doc/poland/e-invoicing/setup +title: "Setup & testing" +--- + +# Set up and test eInvoicing (Poland) + +This page covers the prerequisites for eInvoicing in the Polish (PL) market, how to enable it in the fiskaltrust.Portal, and how to validate the flow against a sandbox before production. For scope, regulatory status, and the delivery flow, see the [Overview](./overview.md). + +:::note What setup means in Poland +eInvoicing rides on calls you already make. Setup is about **configuration** — KSeF FA(3) output and the fiskaltrust.Middleware's Polish locale. Delivery via `/issue` to KSeF is **optional**. There is **no new connection or credential**. +::: + +:::caution Poland eInvoicing is in preview +The Poland eInvoicing path is available in **preview** on the developer platform. Confirm production availability and the exact KSeF clearance behaviour with your fiskaltrust contact before going live. +::: + +## Prerequisites + +| Requirement | Detail | +| --- | --- | +| fiskaltrust account + fiskaltrust.Middleware | An active account with a configured fiskaltrust.Middleware. See [Portal registration](../../../getting-started/portal-registration.md). | +| Existing fiscalization integration | Your POS already fiscalizes in Poland via `/sign`. | +| fiskaltrust.Middleware country configuration | The fiskaltrust.Middleware's country configuration is set to the **Polish locale**. | +| PosSystem API (v2) | eInvoicing features are exposed through the **PosSystem API (v2)**. If you are on the v0 interface, plan your [migration](../../possystem-api/migration-guide.md) first. | +| Currency | Poland is **not a euro market** — every request must set `"Currency": "PLN"` (at the top level and on each charge and pay item). | +| Payment process | Confirm the merchant's payment process can carry the **KSeF number** into transfer titles (mandatory from August 2026). | + +## Enable eInvoicing in the Portal + +eInvoicing is enabled by **configuration**: KSeF FA(3) output and the fiskaltrust.Middleware's Polish locale. No new integration is required on the POS side. + +:::caution Draft — Portal steps to be confirmed +The exact steps to enable eInvoicing in the fiskaltrust.Portal (KSeF FA(3) output, Polish locale) are being verified and will be documented here. Do not treat this section as final until the flow has been confirmed. +::: + +## Sandbox validation + +Validate the end-to-end flow against a sandbox-scoped fiskaltrust.Middleware — using non-production `x-cashbox-id` and `x-cashbox-accesstoken` credentials — before enabling it on a production fiskaltrust.Middleware. **Run one document through the sandbox end to end before the first live document.** + +1. Provision a **sandbox fiskaltrust.Middleware** in the fiskaltrust.Portal — this yields the `x-cashbox-id` and `x-cashbox-accesstoken` used on every request. See [Portal registration](../../../getting-started/portal-registration.md). +2. Confirm your integration against the [Integration checklist](../../../getting-started/integration-checklist.md). +3. Run one invoice through the full flow below: `/sign` → (optionally) `/issue` → poll until **cleared by KSeF**. + +### End-to-end example + +Run it against the sandbox at `https://possystem-api-sandbox.fiskaltrust.eu/v2`. The API is request/response and **idempotent — there is no status webhook**; the `x-operation-id` header is the idempotency key that makes retries safe. Every request carries the standard headers: + +``` +x-cashbox-id: +x-cashbox-accesstoken: +x-possystem-id: +x-operation-id: +``` + +**Step 1 — Sign (`/sign`)** — produces the eInvoice + +Call `/sign` as you do today, with the buyer's master data, using the **B2B invoice** receipt case. Poland is not a euro market, so set `"Currency": "PLN"` explicitly. The response carries the fiscalized receipt and the KSeF FA(3) document. + +```json +// POST https://possystem-api-sandbox.fiskaltrust.eu/v2/sign +{ + "ftReceiptCase": 35184372092930, + "cbReceiptReference": "PL-EINV-SANDBOX-0001", + "cbReceiptMoment": "2026-09-01T10:00:00Z", + "Currency": "PLN", + "cbCustomer": { + "CustomerVATId": "PL1234567890", + "CustomerName": "Przykład Sp. z o.o.", + "CustomerStreet": "ul. Przykładowa 1", + "CustomerZip": "00-001", + "CustomerCity": "Warszawa", + "CustomerCountry": "PL" + }, + "cbChargeItems": [ + { "Quantity": 1, "Description": "Consulting services", "Amount": 1230.00, "VATRate": 23, "ftChargeItemCase": 35184372088851, "Currency": "PLN" } + ], + "cbPayItems": [ + { "Description": "Bank transfer", "Amount": 1230.00, "ftPayItemCase": 35184372088842, "Currency": "PLN" } + ] +} +``` + +> **Try it:** [developer.fiskaltrust.eu → PL → sign → B2BInvoice](https://developer.fiskaltrust.eu/#/pos-system/PL?endpoint=sign&businesscase=SignRequestReceipt_B2BInvoice_1). The KSeF FA(3) output comes from the fiskaltrust.Middleware configuration, not this payload — see [Enable eInvoicing in the Portal](#enable-einvoicing-in-the-portal). + +**Step 2 — Issue (`/issue`)** — optional, register for delivery + +To make the receipt available for delivery, call `/issue` with the **original `/sign` request and its response** (`ReceiptRequest` + `ReceiptResponse`). The response returns the `ftQueueID` / `ftQueueItemID` used by the delivery and status calls. + +```json +// POST https://possystem-api-sandbox.fiskaltrust.eu/v2/issue +{ + "ReceiptRequest": { "...": "the /sign request from Step 1" }, + "ReceiptResponse": { "...": "the /sign response from Step 1" } +} +``` + +> **Try it:** [developer.fiskaltrust.eu → PL → issue](https://developer.fiskaltrust.eu/#/pos-system/PL?endpoint=issue). + +**Step 3 — Deliver to a channel** — optional + +Deliver the document with `PUT /issue/{queueId}/{queueItemId}`, choosing a delivery method: `IssueUpdateSend` (email/SMS), `IssueUpdatePrint`, `IssueUpdateDownload`, `IssueUpdateUpload`, or `IssueUpdateLink`. Submission to KSeF uses one of the upload/send methods — confirm the exact delivery target with product. + +**Step 4 — Check clearance status** + +Poll `GET /issue/{queueId}/{queueItemId}` for the status until KSeF returns the **clearance number**. There is **no callback or webhook**. + +See the [POS System API reference](https://docs.fiskaltrust.cloud/apis/pos-system-api) for the full `/issue` request/response schemas. + +## Related pages + +- [Overview](./overview.md) — scope, regulatory status, and the integration flow. +- [Delivery (`/issue` Endpoint)](../../experience-middleware/delivery.md) — the product-level eInvoicing and e-Delivery concept. +- [Migrating from API v0 to PosSystem API (v2)](../../possystem-api/migration-guide.md) — eInvoicing is a PosSystem API (v2) feature. diff --git a/poscreators/toc.js b/poscreators/toc.js index c7a4857d..ae6c6bc7 100644 --- a/poscreators/toc.js +++ b/poscreators/toc.js @@ -388,6 +388,15 @@ module.exports = [ "poscreators/middleware-doc/middleware-pl/reference-tables/type-of-journal-ftjournaltype", ], }, + { + type: "category", + collapsed: true, + label: "E-Invoicing", + items: [ + "poscreators/middleware-doc/middleware-pl/e-invoicing/overview", + "poscreators/middleware-doc/middleware-pl/e-invoicing/setup", + ], + }, ], }, { From 835fe6b207f2904d8ad6e79c7f5fab54a8af0f96 Mon Sep 17 00:00:00 2001 From: deboragracio Date: Fri, 11 Sep 2026 12:53:46 +0200 Subject: [PATCH 2/3] docs(pl): add EU Digital Building Blocks country factsheet link Co-Authored-By: Claude Opus 4.8 --- poscreators/middleware-doc/middleware-pl/e-invoicing/overview.md | 1 + 1 file changed, 1 insertion(+) diff --git a/poscreators/middleware-doc/middleware-pl/e-invoicing/overview.md b/poscreators/middleware-doc/middleware-pl/e-invoicing/overview.md index 28273e7b..14935311 100644 --- a/poscreators/middleware-doc/middleware-pl/e-invoicing/overview.md +++ b/poscreators/middleware-doc/middleware-pl/e-invoicing/overview.md @@ -37,3 +37,4 @@ Both waves of the B2B mandate have passed (turnover above 200 million PLN from 1 - [Delivery (`/issue` Endpoint)](../../experience-middleware/delivery.md) — the product-level eInvoicing and e-Delivery concept across all markets. - [Migrating from API v0 to PosSystem API (v2)](../../possystem-api/migration-guide.md) — eInvoicing is a PosSystem API (v2) feature. - [Appendix: PL](../appendix-pl.md) — Poland fiscalization details. +- [eInvoicing in Poland (European Commission)](https://ec.europa.eu/digital-building-blocks/sites/spaces/DIGITAL/pages/467108896/eInvoicing+in+Poland) — the EU Digital Building Blocks country factsheet. From df2faaf27ad81ad2261eceb099e62fd073e0a6bb Mon Sep 17 00:00:00 2001 From: deboragracio Date: Fri, 11 Sep 2026 13:26:01 +0200 Subject: [PATCH 3/3] docs: normalize eInvoicing category label spelling in TOC Rename the Poland "E-Invoicing" category to "eInvoicing" to match the agreed spelling used across the docs (also flips the shared DE label). Co-Authored-By: Claude Opus 4.8 --- poscreators/toc.js | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/poscreators/toc.js b/poscreators/toc.js index ae6c6bc7..d7b410fb 100644 --- a/poscreators/toc.js +++ b/poscreators/toc.js @@ -214,7 +214,7 @@ module.exports = [ { type: "category", collapsed: true, - label: "E-Invoicing", + label: "eInvoicing", items: [ "poscreators/middleware-doc/middleware-de-kassensichv/e-invoicing/overview", "poscreators/middleware-doc/middleware-de-kassensichv/e-invoicing/setup", @@ -391,7 +391,7 @@ module.exports = [ { type: "category", collapsed: true, - label: "E-Invoicing", + label: "eInvoicing", items: [ "poscreators/middleware-doc/middleware-pl/e-invoicing/overview", "poscreators/middleware-doc/middleware-pl/e-invoicing/setup",