From b7f904c93e01a9de65a133e82844a5b1326d5531 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 30 Apr 2026 08:41:56 +0000 Subject: [PATCH 01/10] docs: add v0 to PosSystem API (v2) migration guide and cross-links Agent-Logs-Url: https://github.com/fiskaltrust/docs/sessions/b1475a47-bd10-46a5-bdc9-dcc1fc252b0a Co-authored-by: deboragracio <63159404+deboragracio@users.noreply.github.com> --- .../general/communication/communication.md | 6 + .../function-structures.md | 6 + .../general/migration/v0-to-possystemapi.md | 162 ++++++++++++++++++ .../middleware-at-rksv/appendix-at-rksv.md | 6 + .../appendix-fr-boi-tva-decla-30-10-30.md | 6 + poscreators/toc.js | 9 + .../middleware/helper-possystemapi.md | 6 + 7 files changed, 201 insertions(+) create mode 100644 poscreators/middleware-doc/general/migration/v0-to-possystemapi.md diff --git a/poscreators/middleware-doc/general/communication/communication.md b/poscreators/middleware-doc/general/communication/communication.md index ab51961..63cfb60 100644 --- a/poscreators/middleware-doc/general/communication/communication.md +++ b/poscreators/middleware-doc/general/communication/communication.md @@ -5,6 +5,12 @@ title: Communication # Communication +:::info Migrating to PosSystem API (v2)? + +If you are an Austria (AT) or France (FR) customer currently using the v0 WCF or REST interface and planning to move to the new PosSystem API, see the [v0 → PosSystem API migration guide](../migration/v0-to-possystemapi.md). + +::: + The fiskaltrust.Middleware supports different communication protocols, effectively giving our users the possibility to use it on all currently available platforms and implement the interface in all state-of-the-art programming languages. This enables our users to choose the communication type that suits their scenario best. The communication protocol is specified by setting the respective URL in the package configuration of the fiskaltrust.Portal. The buttons to the right of the URL field can be used to quickly insert the respective URL: diff --git a/poscreators/middleware-doc/general/function-structures/function-structures.md b/poscreators/middleware-doc/general/function-structures/function-structures.md index f541748..6c9c389 100644 --- a/poscreators/middleware-doc/general/function-structures/function-structures.md +++ b/poscreators/middleware-doc/general/function-structures/function-structures.md @@ -5,6 +5,12 @@ title: Function Structures # Function Structures +:::info Migrating to PosSystem API (v2)? + +If you are an Austria (AT) or France (FR) customer currently using the v0 synchronous `Sign`/`Echo`/`Journal` calls and planning to move to the new PosSystem API, see the [v0 → PosSystem API migration guide](../migration/v0-to-possystemapi.md). + +::: + ## iPOS Interface This interface is a communication channel for interacting with the fiskaltrust.Middleware. It provides three basic functions: "echo", "sign", and "journal". The functions "echo" and "sign" return bare-objects, the function "journal" returns a wrapped-object. diff --git a/poscreators/middleware-doc/general/migration/v0-to-possystemapi.md b/poscreators/middleware-doc/general/migration/v0-to-possystemapi.md new file mode 100644 index 0000000..1b3ff2e --- /dev/null +++ b/poscreators/middleware-doc/general/migration/v0-to-possystemapi.md @@ -0,0 +1,162 @@ +--- +slug: /poscreators/middleware-doc/general/migration/v0-to-possystemapi +title: Migrating from v0 to PosSystem API (v2) +--- + +# Migrating from v0 to PosSystem API (v2) + +:::info summary + +After reading this guide, you will understand the differences between the legacy `ifPOS.v0` interface and the new PosSystem API (v2), and be able to migrate your integration to the v2 stack. + +::: + +## Why migrate? + +The `ifPOS.v0` interface is the original, synchronous fiskaltrust.Middleware API used primarily in Austria (AT) and France (FR). While it remains functional, **it will not receive new features**. All current and future development — including e-invoicing support and upcoming compliance features — is available exclusively through the **PosSystem API (v2)**. + +Migrating to v2 gives you: + +- Access to e-invoicing features and all future compliance capabilities +- A modern, standard HTTP/REST API that works with any programming language or framework +- PIN-based pairing for simpler, more secure authentication setup +- Active support and ongoing development + +## Prerequisites + +Before starting the migration, ensure you have: + +- Access to the **fiskaltrust.Portal** to reconfigure CashBoxes +- **Launcher 2.0** (minimum version `2.0.0-rc.25`) — the PosSystem API requires Launcher 2.0 +- Familiarity with the [Local PosSystem API Helper setup guide](../../../../posdealers/technical-operations/middleware/helper-possystemapi.md) + +:::caution Market availability + +The PosSystem API via Launcher 2.0 has market-specific constraints: + +- **Austria (AT):** Launcher 2.0 is not enabled by default. Contact fiskaltrust support to enable it for your account. +- **France (FR):** Launcher 2.0 is not yet supported. French customers should contact fiskaltrust for the current roadmap before planning a migration. + +::: + +## Architecture overview + +The following table summarises the key architectural differences between the two integration approaches: + +| Aspect | v0 (legacy) | v2 — PosSystem API | +|-------------------------|-------------------------------------------------------------------|------------------------------------------------------------------| +| **Protocol** | WCF (SOAP) or REST `/v0/` | HTTP REST `/possystemapi/` | +| **Communication style** | Synchronous (blocking) | Modern REST (JSON) | +| **Middleware component**| Queue package directly | LocalPosSystemApi Helper in front of the Queue | +| **Launcher** | Launcher 1.x | Launcher 2.0 (min. `2.0.0-rc.25`) | +| **Authentication** | CashboxID + AccessToken (per request / in service binding) | CashboxID + AccessToken in HTTP headers, PIN pairing via Portal | +| **Client libraries** | .NET `ifPOS.v0` NuGet package, WCF proxies, or REST HTTP calls | Any HTTP client; official devkit available | +| **New feature support** | None — no new features planned | All new features (e-invoicing, etc.) | + +**v0 data flow:** + +``` +POS System → WCF or REST (/v0/) → fiskaltrust Queue +``` + +**v2 data flow:** + +``` +POS System → HTTP REST (/possystemapi/) → LocalPosSystemApi Helper → fiskaltrust Queue +``` + +## Configuration steps + +The portal-side configuration requires adding a **LocalPosSystemApi Helper** to your CashBox and rebuilding it with Launcher 2.0. Rather than duplicating those steps here, follow the [Local PosSystem API Helper guide](../../../../posdealers/technical-operations/middleware/helper-possystemapi.md), which covers: + +1. Adding a `fiskaltrust.Middleware.Helper.LocalPosSystemApi` Helper in the Portal +2. Configuring the Helper URL +3. Assigning the Helper to the relevant CashBox +4. Rebuilding the CashBox configuration +5. Downloading and running Launcher 2.0 + +## API changes + +### Method mapping + +The three core operations map directly from v0 to v2, but the calling convention changes from a .NET WCF/REST client to standard HTTP POST requests: + +| v0 call | v2 HTTP endpoint | Notes | +|--------------------------------------------------|-----------------------------------|-----------------------------------------------------------------------| +| `proxy.Echo("message")` | `POST /api/v2/echo` | Request/response body is a JSON object `{"message": "..."}` | +| `proxy.Sign(receiptRequest)` | `POST /api/v2/sign` | Request body is the JSON-serialised `ReceiptRequest`; response is `ReceiptResponse` | +| `proxy.Journal(ftJournalType, from, to)` | `POST /api/v2/journal` | Request body carries `ftJournalType`, `from`, and `to` as ISO 8601 date-time strings (see [Timestamps](#timestamps)) | + +#### Authentication + +All v2 requests must include the following HTTP headers: + +``` +cashboxid: +accesstoken: +``` + +Both values are available on the CashBox page in the fiskaltrust.Portal. On first use, you also need to **pair** the client via the PIN displayed in the Portal (see the [Helper setup guide](../../../../posdealers/technical-operations/middleware/helper-possystemapi.md#test-the-possystem-api-helper)). + +### ReceiptRequest changes + +The v2 `ReceiptRequest` is a superset of the v0 model. Most existing fields are directly reusable; the key differences are: + +| Field | v0 | v2 | +|-----------------------------|-------------------------------------|-------------------------------------------------------| +| `cbReceiptReference` | Optional in some flows | **Required** — must be a unique string per request | +| `Currency` | Not present | Added — ISO 4217 currency code (default: `EUR`) | +| `DecimalPrecisionMultiplier`| Not present | Added — controls integer vs. floating-point amounts (default: `1`, i.e. floating-point) | +| `ftPosSystemID` | Optional | Recommended — identifies your POS software | + +All other fields (`ftCashBoxID`, `cbTerminalID`, `cbReceiptMoment`, `cbChargeItems`, `cbPayItems`, `ftReceiptCase`, etc.) carry over unchanged. + +### ReceiptResponse changes + +The `ReceiptResponse` structure is largely compatible. Verify that your receipt printing logic correctly handles: + +- `ftSignatures` — format and type values are unchanged; ensure all entries are printed as required by national regulations +- `ftState` — error flag interpretation is unchanged; check your error-handling code still covers all states + +### Timestamps + +The v0 Journal call used **.NET Ticks** for the `from` and `to` parameters: + +``` +// v0 example +proxy.Journal(ftJournalType, 0, DateTime.UtcNow.Ticks); +``` + +The v2 Journal request uses **ISO 8601 UTC date-time strings** in the JSON body: + +```json +{ + "ftJournalType": 8301034833876213761, + "from": "2020-01-01T00:00:00Z", + "to": "2024-12-31T23:59:59Z" +} +``` + +If you need to convert existing .NET Tick values, use the formulas from the [Function Structures reference](../function-structures/function-structures.md#timestamps). + +## Testing the migration + +The easiest way to validate your v2 integration is the **[fiskaltrust Developer Portal](https://developer.fiskaltrust.eu/)**, which provides an interactive interface for sending requests to a running Middleware instance. + +For code samples and a full API reference, see the **[PosSystem API Development Kit](https://github.com/fiskaltrust/possystemapi-devkit)** on GitHub. + +## Cutover considerations + +:::caution No parallel operation + +Running the v0 and v2 interfaces in parallel on the same CashBox is not recommended. Perform the migration as a **clean cutover** per CashBox: reconfigure the CashBox with the LocalPosSystemApi Helper, rebuild it, deploy the new Launcher 2.0 package, then switch your POS system to use the new v2 endpoint. Ensure any buffered or in-flight v0 receipts are processed and closed before switching. + +::: + +A recommended cutover sequence: + +1. Complete all open transactions / close the current business day in the POS system +2. Reconfigure the CashBox in the Portal (add Helper, rebuild) +3. Deploy Launcher 2.0 to the POS terminal +4. Update the POS system to call the v2 endpoint +5. Send a test Echo request to confirm connectivity before going live diff --git a/poscreators/middleware-doc/middleware-at-rksv/appendix-at-rksv.md b/poscreators/middleware-doc/middleware-at-rksv/appendix-at-rksv.md index 716816f..ae70f99 100644 --- a/poscreators/middleware-doc/middleware-at-rksv/appendix-at-rksv.md +++ b/poscreators/middleware-doc/middleware-at-rksv/appendix-at-rksv.md @@ -17,4 +17,10 @@ https://www.lindeverlag.at/onlineprodukt/handbuch-registrierkassen-und-belegerte Ritz/Koran/Kutschera/Knasmüller, Handbuch Registrierkassen- und Belegerteilungspflicht, 2. Auflage 2019, Linde Verlag Wien. ISBN: 9783707335910 +:::info Upgrading to PosSystem API (v2) + +New features such as e-invoicing are available exclusively through the **PosSystem API (v2)**. If you are currently using the v0 interface (WCF/REST), see the [v0 → PosSystem API migration guide](../general/migration/v0-to-possystemapi.md) for step-by-step instructions. + +::: + diff --git a/poscreators/middleware-doc/middleware-fr-boi-tva-decla-30-10-30/appendix-fr-boi-tva-decla-30-10-30.md b/poscreators/middleware-doc/middleware-fr-boi-tva-decla-30-10-30/appendix-fr-boi-tva-decla-30-10-30.md index bc27bd8..8ebacda 100644 --- a/poscreators/middleware-doc/middleware-fr-boi-tva-decla-30-10-30/appendix-fr-boi-tva-decla-30-10-30.md +++ b/poscreators/middleware-doc/middleware-fr-boi-tva-decla-30-10-30/appendix-fr-boi-tva-decla-30-10-30.md @@ -23,4 +23,10 @@ The technical specification of the data interface described in this document pro The interface specification is provided by fiskaltrust.Interface NuGet package, which can be found at https://www.nuget.org/packages/fiskaltrust.interface. +:::info Upgrading to PosSystem API (v2) + +New features such as e-invoicing are available exclusively through the **PosSystem API (v2)**. If you are currently using the v0 interface (WCF/REST), see the [v0 → PosSystem API migration guide](../general/migration/v0-to-possystemapi.md) for step-by-step instructions. + +::: + diff --git a/poscreators/toc.js b/poscreators/toc.js index 079bc64..d1aa723 100644 --- a/poscreators/toc.js +++ b/poscreators/toc.js @@ -370,6 +370,15 @@ module.exports = [ }, ], }, + + { + type: "category", + label: "Migration Guides", + collapsed: true, + items: [ + "poscreators/middleware-doc/general/migration/v0-to-possystemapi", + ], + }, ], }, { diff --git a/posdealers/technical-operations/middleware/helper-possystemapi.md b/posdealers/technical-operations/middleware/helper-possystemapi.md index 9403573..1f9fb48 100644 --- a/posdealers/technical-operations/middleware/helper-possystemapi.md +++ b/posdealers/technical-operations/middleware/helper-possystemapi.md @@ -16,6 +16,12 @@ After reading this, you can set up and configure the local PosSystem API Helper ::: +:::info Migrating from v0? + +If your POS system currently uses the v0 interface (WCF/REST) and you are migrating to the PosSystem API, see the [v0 → PosSystem API migration guide](../../../poscreators/middleware-doc/general/migration/v0-to-possystemapi.md) for a full overview of API and data model changes. + +::: + ## Introduction The local PosSystem API Helper is a Middleware component that exposes a local endpoint through which the POS System communicates with the fiskaltrust Middleware. It acts as a bridge between the POS System and the underlying Queue, and is required for Launcher 2.0 deployments. From 210db98b71fa286093b21ec89941c62c61317355 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 30 Apr 2026 08:45:35 +0000 Subject: [PATCH 02/10] docs: address review feedback - echo example and toc indentation Agent-Logs-Url: https://github.com/fiskaltrust/docs/sessions/b1475a47-bd10-46a5-bdc9-dcc1fc252b0a Co-authored-by: deboragracio <63159404+deboragracio@users.noreply.github.com> --- .../general/migration/v0-to-possystemapi.md | 21 ++++++++++++++++++- poscreators/toc.js | 1 - 2 files changed, 20 insertions(+), 2 deletions(-) diff --git a/poscreators/middleware-doc/general/migration/v0-to-possystemapi.md b/poscreators/middleware-doc/general/migration/v0-to-possystemapi.md index 1b3ff2e..cc594e2 100644 --- a/poscreators/middleware-doc/general/migration/v0-to-possystemapi.md +++ b/poscreators/middleware-doc/general/migration/v0-to-possystemapi.md @@ -83,7 +83,7 @@ The three core operations map directly from v0 to v2, but the calling convention | v0 call | v2 HTTP endpoint | Notes | |--------------------------------------------------|-----------------------------------|-----------------------------------------------------------------------| -| `proxy.Echo("message")` | `POST /api/v2/echo` | Request/response body is a JSON object `{"message": "..."}` | +| `proxy.Echo("message")` | `POST /api/v2/echo` | Request body: `{"message": "..."}` — response mirrors the same structure: `{"message": "..."}` | | `proxy.Sign(receiptRequest)` | `POST /api/v2/sign` | Request body is the JSON-serialised `ReceiptRequest`; response is `ReceiptResponse` | | `proxy.Journal(ftJournalType, from, to)` | `POST /api/v2/journal` | Request body carries `ftJournalType`, `from`, and `to` as ISO 8601 date-time strings (see [Timestamps](#timestamps)) | @@ -98,6 +98,25 @@ accesstoken: Both values are available on the CashBox page in the fiskaltrust.Portal. On first use, you also need to **pair** the client via the PIN displayed in the Portal (see the [Helper setup guide](../../../../posdealers/technical-operations/middleware/helper-possystemapi.md#test-the-possystem-api-helper)). +#### Echo example + +**Request:** + +```json +POST /api/v2/echo +{ + "message": "test" +} +``` + +**Response:** + +```json +{ + "message": "test" +} +``` + ### ReceiptRequest changes The v2 `ReceiptRequest` is a superset of the v0 model. Most existing fields are directly reusable; the key differences are: diff --git a/poscreators/toc.js b/poscreators/toc.js index d1aa723..71e8ecb 100644 --- a/poscreators/toc.js +++ b/poscreators/toc.js @@ -370,7 +370,6 @@ module.exports = [ }, ], }, - { type: "category", label: "Migration Guides", From 632e4f6d62272515ec66eb7b26cb8eccf6b832dc Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 30 Apr 2026 15:45:38 +0000 Subject: [PATCH 03/10] =?UTF-8?q?docs:=20add=20cloud=20URL,=20case=20value?= =?UTF-8?q?s,=20and=20ftReceiptCaseData=20format=20sections=20to=20v0?= =?UTF-8?q?=E2=86=92v2=20migration=20guide?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Agent-Logs-Url: https://github.com/fiskaltrust/docs/sessions/a565d3f7-633c-43cc-96d2-170582c3c307 Co-authored-by: deboragracio <63159404+deboragracio@users.noreply.github.com> --- .../general/migration/v0-to-possystemapi.md | 72 ++++++++++++++++++- 1 file changed, 71 insertions(+), 1 deletion(-) diff --git a/poscreators/middleware-doc/general/migration/v0-to-possystemapi.md b/poscreators/middleware-doc/general/migration/v0-to-possystemapi.md index cc594e2..97b8b96 100644 --- a/poscreators/middleware-doc/general/migration/v0-to-possystemapi.md +++ b/poscreators/middleware-doc/general/migration/v0-to-possystemapi.md @@ -65,6 +65,29 @@ POS System → WCF or REST (/v0/) → fiskaltrust Queue POS System → HTTP REST (/possystemapi/) → LocalPosSystemApi Helper → fiskaltrust Queue ``` +## Cloud CashBox: base URL change + +If your integration targets a **cloud CashBox** (i.e. your POS system calls the fiskaltrust cloud endpoint rather than a locally-running Middleware), the base URL changes as part of the migration: + +| Environment | v0 base URL | v2 base URL | +|-------------|----------------------------------------------------------|------------------------------------------------------| +| Sandbox | `https://signaturcloud-sandbox.fiskaltrust.fr` (FR) | `https://possystem-api-sandbox.fiskaltrust.eu/v2` | +| Sandbox | `https://signaturcloud-sandbox.fiskaltrust.at` (AT) | `https://possystem-api-sandbox.fiskaltrust.eu/v2` | +| Sandbox | `https://signaturcloud-sandbox.fiskaltrust.de` (DE) | `https://possystem-api-sandbox.fiskaltrust.eu/v2` | +| Production | `https://signaturcloud.fiskaltrust.fr` (FR) | `https://possystem-api.fiskaltrust.eu/v2` | +| Production | `https://signaturcloud.fiskaltrust.at` (AT) | `https://possystem-api.fiskaltrust.eu/v2` | +| Production | `https://signaturcloud.fiskaltrust.de` (DE) | `https://possystem-api.fiskaltrust.eu/v2` | + +Note that the v2 cloud endpoint is a **single, market-agnostic URL** — the market is determined by the `ftReceiptCase` value and your CashBox configuration, not the host. + +The path structure changes accordingly: + +| Operation | v0 path | v2 path | +|-----------|--------------------------------------------|--------------------------| +| Sign | `/[json|xml]/v0/sign` | `/api/v2/sign` | +| Echo | `/[json|xml]/v0/echo` | `/api/v2/echo` | +| Journal | `/[json|xml]/v0/journal` | `/api/v2/journal` | + ## Configuration steps The portal-side configuration requires adding a **LocalPosSystemApi Helper** to your CashBox and rebuilding it with Launcher 2.0. Rather than duplicating those steps here, follow the [Local PosSystem API Helper guide](../../../../posdealers/technical-operations/middleware/helper-possystemapi.md), which covers: @@ -130,6 +153,53 @@ The v2 `ReceiptRequest` is a superset of the v0 model. Most existing fields are All other fields (`ftCashBoxID`, `cbTerminalID`, `cbReceiptMoment`, `cbChargeItems`, `cbPayItems`, `ftReceiptCase`, etc.) carry over unchanged. +### Case value changes + +The integer values used for `ftReceiptCase`, `ftChargeItemCase`, and `ftPayItemCase` differ between the v0 and v2 interfaces. **Updating these values is the most substantial part of the migration.** Each receipt and item type has a corresponding v2 value, and sending v0 values to the v2 endpoint will result in incorrect processing. + +:::info Developer Portal + +The authoritative source for v2 case values and their mapping to v0 cases is the **[fiskaltrust Developer Portal](https://developers.fiskaltrust.eu/#/pos-system)**. It provides market-specific business case examples (AT, FR, DE) with the correct v2 `ftReceiptCase`, `ftChargeItemCase`, and `ftPayItemCase` values for each scenario. Use these examples as your reference when updating your integration. + +::: + +A systematic approach to updating case values: + +1. List every `ftReceiptCase`, `ftChargeItemCase`, and `ftPayItemCase` value currently used in your integration +2. For each value, find the corresponding business case in the Developer Portal for your market +3. Replace the v0 value with the v2 value shown in the portal example +4. Repeat for all receipt types (including special receipts such as Start-Receipt, Stop-Receipt, daily/shift closings, and Zero-Receipts) + +### `ftReceiptCaseData` format change + +The `ftReceiptCaseData` field changes from a **JSON-encoded string** in v0 to a **market-keyed JSON object** in v2. + +**v0 format** — the entire value is a JSON string embedded as a string field: + +```json +{ + "ftReceiptCase": "...", + "ftReceiptCaseData": "{\"Code\":\"20\", \"Message\":\"Archivage fiscal de période\", \"Information\":\"\"}" +} +``` + +**v2 format** — the value is a plain JSON object with a market key (`"FR"`, `"AT"`, `"DE"`) whose value is a JSON-encoded string: + +```json +{ + "ftReceiptCase": "...", + "ftReceiptCaseData": { + "FR": "{\"Code\": \"20\", \"Message\": \"Archivage fiscal de période\", \"Information\": \"\"}" + } +} +``` + +Key points: +- The outer field is now a **JSON object**, not a string +- The inner value (per market key) remains a **JSON-encoded string** of the market-specific payload +- Use the two-letter ISO market code as the key (`"FR"`, `"AT"`, `"DE"`) +- If `ftReceiptCaseData` is not needed for a particular receipt type, the field can be omitted entirely + ### ReceiptResponse changes The `ReceiptResponse` structure is largely compatible. Verify that your receipt printing logic correctly handles: @@ -160,7 +230,7 @@ If you need to convert existing .NET Tick values, use the formulas from the [Fun ## Testing the migration -The easiest way to validate your v2 integration is the **[fiskaltrust Developer Portal](https://developer.fiskaltrust.eu/)**, which provides an interactive interface for sending requests to a running Middleware instance. +The easiest way to validate your v2 integration is the **[fiskaltrust Developer Portal](https://developers.fiskaltrust.eu/)**, which provides an interactive interface for sending requests to a running Middleware instance. For code samples and a full API reference, see the **[PosSystem API Development Kit](https://github.com/fiskaltrust/possystemapi-devkit)** on GitHub. From 1c1ace05c597cc253270bb0fcb19f22c67534aba Mon Sep 17 00:00:00 2001 From: deboragracio Date: Tue, 5 May 2026 16:25:02 +0200 Subject: [PATCH 04/10] Created draft (in progress) https://github.com/fiskaltrust/engineering/issues/1116 --- .../general/migration/v0-to-possystemapi.md | 363 ++++++++++++++---- 1 file changed, 286 insertions(+), 77 deletions(-) diff --git a/poscreators/middleware-doc/general/migration/v0-to-possystemapi.md b/poscreators/middleware-doc/general/migration/v0-to-possystemapi.md index 97b8b96..09abcd9 100644 --- a/poscreators/middleware-doc/general/migration/v0-to-possystemapi.md +++ b/poscreators/middleware-doc/general/migration/v0-to-possystemapi.md @@ -1,34 +1,35 @@ --- slug: /poscreators/middleware-doc/general/migration/v0-to-possystemapi -title: Migrating from v0 to PosSystem API (v2) +title: Migrating from API v0 to PosSystem API (v2) --- -# Migrating from v0 to PosSystem API (v2) +# Migrating from API v0 to PosSystem API (v2) -:::info summary - -After reading this guide, you will understand the differences between the legacy `ifPOS.v0` interface and the new PosSystem API (v2), and be able to migrate your integration to the v2 stack. - -::: - -## Why migrate? +## Introduction The `ifPOS.v0` interface is the original, synchronous fiskaltrust.Middleware API used primarily in Austria (AT) and France (FR). While it remains functional, **it will not receive new features**. All current and future development — including e-invoicing support and upcoming compliance features — is available exclusively through the **PosSystem API (v2)**. Migrating to v2 gives you: -- Access to e-invoicing features and all future compliance capabilities -- A modern, standard HTTP/REST API that works with any programming language or framework -- PIN-based pairing for simpler, more secure authentication setup -- Active support and ongoing development +- **E-invoicing support** - Access to e-invoicing features and all future compliance capabilities +- **Alignment with fiskaltrust Middleware v2** — the POSSystemAPI interface is designed to remain largely stable when the middleware transitions from v1.2 to v2, making this migration valuable preparation. +- **Long-term supportability** — v0 is considered deprecated; customers are encouraged to migrate as soon as possible. +- **Simpler authentication** - PIN-based pairing for simpler, more secure authentication setup. +- **Modern and flexible API design** - A modern, standard HTTP/REST API that works with any programming language or framework. +This guide is primarily targeted at POS Creators integrating **cloud cashboxes** in the **AT, FR, and DE** markets. + ## Prerequisites Before starting the migration, ensure you have: -- Access to the **fiskaltrust.Portal** to reconfigure CashBoxes -- **Launcher 2.0** (minimum version `2.0.0-rc.25`) — the PosSystem API requires Launcher 2.0 -- Familiarity with the [Local PosSystem API Helper setup guide](../../../../posdealers/technical-operations/middleware/helper-possystemapi.md) +- An active **fiskaltrust account** (sandbox and/or production). +- Access to the **fiskaltrust.Portal** to reconfigure CashBoxes. +- An existing integration that successfully produces receipts against the v0 SignatureCloud API. +- Access to a **sandbox cashbox** for testing your migrated integration before going live. +- **Launcher 2.0** (minimum version `2.0.0-rc.25`) — the PosSystem API requires Launcher 2.0. +- Familiarity with the [Local PosSystem API Helper setup guide](../../../../posdealers/technical-operations/middleware/helper-possystemapi.md). +- Familiarity with the **POSSystemAPI business case examples**, which serve as the reference for the new request format: [https://developers.fiskaltrust.eu/#/pos-system](https://developers.fiskaltrust.eu/#/pos-system) :::caution Market availability @@ -65,9 +66,9 @@ POS System → WCF or REST (/v0/) → fiskaltrust Queue POS System → HTTP REST (/possystemapi/) → LocalPosSystemApi Helper → fiskaltrust Queue ``` -## Cloud CashBox: base URL change +## Step 1: Cloud CashBox - Change the base URL -If your integration targets a **cloud CashBox** (i.e. your POS system calls the fiskaltrust cloud endpoint rather than a locally-running Middleware), the base URL changes as part of the migration: +If your integration targets a **Cloud CashBox** (for example, your POS system calls the fiskaltrust cloud endpoint rather than a locally-running Middleware), the base URL changes as part of the migration: | Environment | v0 base URL | v2 base URL | |-------------|----------------------------------------------------------|------------------------------------------------------| @@ -78,8 +79,16 @@ If your integration targets a **cloud CashBox** (i.e. your POS system calls the | Production | `https://signaturcloud.fiskaltrust.at` (AT) | `https://possystem-api.fiskaltrust.eu/v2` | | Production | `https://signaturcloud.fiskaltrust.de` (DE) | `https://possystem-api.fiskaltrust.eu/v2` | +:::info + +The new endpoint is **market-agnostic** — the same base URL is used for AT, FR, and DE. The market is determined by the `ftCashBoxID` and queue configuration, not the URL. + Note that the v2 cloud endpoint is a **single, market-agnostic URL** — the market is determined by the `ftReceiptCase` value and your CashBox configuration, not the host. +::: + +Replace all occurrences of the per-market v0 base URL in your integration with the single new URL above. Make sure to append `/v2` to the path. + The path structure changes accordingly: | Operation | v0 path | v2 path | @@ -88,89 +97,218 @@ The path structure changes accordingly: | Echo | `/[json|xml]/v0/echo` | `/api/v2/echo` | | Journal | `/[json|xml]/v0/journal` | `/api/v2/journal` | -## Configuration steps +## Step 2: Change Case Values -The portal-side configuration requires adding a **LocalPosSystemApi Helper** to your CashBox and rebuilding it with Launcher 2.0. Rather than duplicating those steps here, follow the [Local PosSystem API Helper guide](../../../../posdealers/technical-operations/middleware/helper-possystemapi.md), which covers: +The integer values used for `ftReceiptCase`, `ftChargeItemCase`, and `ftPayItemCase` differ between the v0 and v2 interfaces. Updating these values is the most substantial part of the migration. You must remap all case values in your requests. -1. Adding a `fiskaltrust.Middleware.Helper.LocalPosSystemApi` Helper in the Portal -2. Configuring the Helper URL -3. Assigning the Helper to the relevant CashBox -4. Rebuilding the CashBox configuration -5. Downloading and running Launcher 2.0 +:::info Developer Portal -## API changes +The authoritative source for v2 case values and their mapping to v0 cases is the **[fiskaltrust Developer Portal](https://developers.fiskaltrust.eu/#/pos-system)**. It provides market-specific business case examples (AT, FR, DE) with the correct v2 `ftReceiptCase`, `ftChargeItemCase`, and `ftPayItemCase` values for each scenario. Use these examples as your reference when updating your integration. -### Method mapping +::: -The three core operations map directly from v0 to v2, but the calling convention changes from a .NET WCF/REST client to standard HTTP POST requests: +A systematic approach to updating case values: -| v0 call | v2 HTTP endpoint | Notes | -|--------------------------------------------------|-----------------------------------|-----------------------------------------------------------------------| -| `proxy.Echo("message")` | `POST /api/v2/echo` | Request body: `{"message": "..."}` — response mirrors the same structure: `{"message": "..."}` | -| `proxy.Sign(receiptRequest)` | `POST /api/v2/sign` | Request body is the JSON-serialised `ReceiptRequest`; response is `ReceiptResponse` | -| `proxy.Journal(ftJournalType, from, to)` | `POST /api/v2/journal` | Request body carries `ftJournalType`, `from`, and `to` as ISO 8601 date-time strings (see [Timestamps](#timestamps)) | +1. List every `ftReceiptCase`, `ftChargeItemCase`, and `ftPayItemCase` value currently used in your integration. +2. For each value, find the corresponding business case in the Developer Portal for your market. +3. Replace the v0 value with the v2 value shown in the portal example. +4. Repeat for all receipt types (including special receipts such as Start-Receipt, Stop-Receipt, daily/shift closings, and Zero-Receipts). -#### Authentication +### ftReceiptCase Mapping -All v2 requests must include the following HTTP headers: +
+Austria (AT) -``` -cashboxid: -accesstoken: -``` +| Business Case | v0 Value | POSSystemAPI v2 Value | +|---------------|----------|-----------------------| +| Cash sales / POS receipt | `0x4154000000000001` | TODO | +| Zero receipt | `0x4154000000000002` | TODO | +| Initial operation / start receipt | `0x4154000000000003` | TODO | +| Out of operation / stop receipt | `0x4154000000000004` | TODO | +| Monthly closing | `0x4154000000000005` | TODO | +| Yearly closing | `0x4154000000000006` | TODO | -Both values are available on the CashBox page in the fiskaltrust.Portal. On first use, you also need to **pair** the client via the PIN displayed in the Portal (see the [Helper setup guide](../../../../posdealers/technical-operations/middleware/helper-possystemapi.md#test-the-possystem-api-helper)). +:::caution TODO -#### Echo example +The POSSystemAPI v2 values for AT `ftReceiptCase` must be verified by the integration owners (Paul / Leila) against the internal mapping document. -**Request:** +::: -```json -POST /api/v2/echo -{ - "message": "test" -} -``` +
-**Response:** +
+France (FR) -```json -{ - "message": "test" -} -``` +| Business Case | v0 Value | POSSystemAPI v2 Value | +|---------------|----------|-----------------------| +| Cash sales / POS receipt | `0x4652000000000001` | TODO | +| Zero receipt | `0x465200000000000F` | TODO | +| Initial operation / start receipt | `0x4652000000000010` | TODO | +| Out of operation / stop receipt | `0x4652000000000011` | TODO | +| Daily closing | `0x4652000000000005` | TODO | +| Monthly closing | `0x4652000000000006` | TODO | +| Yearly closing | `0x4652000000000007` | TODO | +| Archives / fiscal period archive | `0x4652000000000015` | TODO | -### ReceiptRequest changes +:::caution TODO -The v2 `ReceiptRequest` is a superset of the v0 model. Most existing fields are directly reusable; the key differences are: +The POSSystemAPI v2 values for FR `ftReceiptCase` must be verified by the integration owners (Paul / Leila) against the internal mapping document. -| Field | v0 | v2 | -|-----------------------------|-------------------------------------|-------------------------------------------------------| -| `cbReceiptReference` | Optional in some flows | **Required** — must be a unique string per request | -| `Currency` | Not present | Added — ISO 4217 currency code (default: `EUR`) | -| `DecimalPrecisionMultiplier`| Not present | Added — controls integer vs. floating-point amounts (default: `1`, i.e. floating-point) | -| `ftPosSystemID` | Optional | Recommended — identifies your POS software | +::: -All other fields (`ftCashBoxID`, `cbTerminalID`, `cbReceiptMoment`, `cbChargeItems`, `cbPayItems`, `ftReceiptCase`, etc.) carry over unchanged. +
-### Case value changes +
+Germany (DE) -The integer values used for `ftReceiptCase`, `ftChargeItemCase`, and `ftPayItemCase` differ between the v0 and v2 interfaces. **Updating these values is the most substantial part of the migration.** Each receipt and item type has a corresponding v2 value, and sending v0 values to the v2 endpoint will result in incorrect processing. +| Business Case | v0 Value | POSSystemAPI v2 Value | +|---------------|----------|-----------------------| +| Cash sales / POS receipt | `0x4445000100000001` | TODO | +| Zero receipt | `0x4445000000000002` | TODO | +| Initial operation / start receipt | `0x4445000000000003` | TODO | +| Out of operation / stop receipt | `0x4445000000000004` | TODO | +| Daily closing | `0x4445000000000007` | TODO | +| Start-transaction receipt | `0x4445000000000008` | TODO | +| Update-transaction receipt | `0x4445000000000009` | TODO | +| Fail-transaction receipt (single) | `0x444500000000000B` | TODO | +| Initiate SCU switch | `0x4445000000000017` | TODO | +| Finish SCU switch | `0x4445000000000018` | TODO | -:::info Developer Portal +:::caution TODO -The authoritative source for v2 case values and their mapping to v0 cases is the **[fiskaltrust Developer Portal](https://developers.fiskaltrust.eu/#/pos-system)**. It provides market-specific business case examples (AT, FR, DE) with the correct v2 `ftReceiptCase`, `ftChargeItemCase`, and `ftPayItemCase` values for each scenario. Use these examples as your reference when updating your integration. +The POSSystemAPI v2 values for DE `ftReceiptCase` must be verified by the integration owners (Paul / Leila) against the internal mapping document. ::: -A systematic approach to updating case values: +
+ +--- + +### ftChargeItemCase Mapping + +
+Austria (AT) + +| Business Case | v0 Value | POSSystemAPI v2 Value | +|---------------|----------|-----------------------| +| Unknown type of service/product — normal rate | `0x4154000000000003` | TODO | +| Unknown type of service/product — discounted-1 | `0x4154000000000001` | TODO | +| Unknown type of service/product — discounted-2 | `0x4154000000000002` | TODO | + +:::caution TODO + +The POSSystemAPI v2 values for AT `ftChargeItemCase` must be verified by the integration owners (Paul / Leila) against the internal mapping document. + +::: + +
+ +
+France (FR) + +| Business Case | v0 Value | POSSystemAPI v2 Value | +|---------------|----------|-----------------------| +| Unknown type of service/product — normal rate | `0x4652000000000003` | TODO | +| Unknown type of service/product — discounted-1 | `0x4652000000000001` | TODO | +| Unknown type of service/product — discounted-2 | `0x4652000000000002` | TODO | + +:::caution TODO + +The POSSystemAPI v2 values for FR `ftChargeItemCase` must be verified by the integration owners (Paul / Leila) against the internal mapping document. + +::: + +
+ +
+Germany (DE) + +| Business Case | v0 Value | POSSystemAPI v2 Value | +|---------------|----------|-----------------------| +| Unknown type of service/product — normal rate | `0x4445000000000001` | TODO | +| Unknown type of service/product — discounted-1 | `0x4445000000000002` | TODO | + +:::caution TODO + +The POSSystemAPI v2 values for DE `ftChargeItemCase` must be verified by the integration owners (Paul / Leila) against the internal mapping document. + +::: + +
+ +### ftPayItemCase Mapping + +
+Austria (AT) + +| Business Case | v0 Value | POSSystemAPI v2 Value | +|---------------|----------|-----------------------| +| Cash payment — national currency | `0x4154000000000001` | TODO | +| Cash payment — foreign currency | `0x4154000000000002` | TODO | +| Crossed cheque | `0x4154000000000003` | TODO | +| Debit card payment | `0x4154000000000004` | TODO | +| Credit card payment | `0x4154000000000005` | TODO | +| Online payment | `0x4154000000000007` | TODO | +| Customer card payment | `0x4154000000000008` | TODO | +| SEPA transfer | `0x415400000000000C` | TODO | +| Internal material consumption | `0x4154000000000011` | TODO | -1. List every `ftReceiptCase`, `ftChargeItemCase`, and `ftPayItemCase` value currently used in your integration -2. For each value, find the corresponding business case in the Developer Portal for your market -3. Replace the v0 value with the v2 value shown in the portal example -4. Repeat for all receipt types (including special receipts such as Start-Receipt, Stop-Receipt, daily/shift closings, and Zero-Receipts) +:::caution TODO -### `ftReceiptCaseData` format change +The POSSystemAPI v2 values for AT `ftPayItemCase` must be verified by the integration owners (Paul / Leila) against the internal mapping document. + +::: + +
+ +
+France (FR) + +| Business Case | v0 Value | POSSystemAPI v2 Value | +|---------------|----------|-----------------------| +| Cash payment — national currency | `0x4652000000000001` | TODO | +| Cash payment — foreign currency | `0x4652000000000002` | TODO | +| Crossed cheque | `0x4652000000000003` | TODO | +| Debit card payment | `0x4652000000000004` | TODO | +| Credit card payment | `0x4652000000000005` | TODO | +| Online payment | `0x4652000000000007` | TODO | +| Customer card payment | `0x4652000000000008` | TODO | +| SEPA transfer | `0x465200000000000C` | TODO | +| Internal material consumption | `0x4652000000000011` | TODO | + +:::caution TODO + +The POSSystemAPI v2 values for FR `ftPayItemCase` must be verified by the integration owners (Paul / Leila) against the internal mapping document. + +::: + +
+ +
+Germany (DE) + +| Business Case | v0 Value | POSSystemAPI v2 Value | +|---------------|----------|-----------------------| +| Cash payment — national currency | `0x4445000000000001` | TODO | +| Cash payment — foreign currency | `0x4445000000000002` | TODO | +| Crossed cheque | `0x4445000000000003` | TODO | +| Debit card payment | `0x4445000000000004` | TODO | +| Credit card payment | `0x4445000000000005` | TODO | +| Online payment | `0x4445000000000006` | TODO | +| Customer card payment | `0x4445000000000007` | TODO | +| SEPA transfer | `0x4445000000000008` | TODO | +| Internal material consumption | `0x444500000000000A` | TODO | + +:::caution TODO + +The POSSystemAPI v2 values for DE `ftPayItemCase` must be verified by the integration owners (Paul / Leila) against the internal mapping document. + +::: + +
+ + +### ftReceiptCaseData format change The `ftReceiptCaseData` field changes from a **JSON-encoded string** in v0 to a **market-keyed JSON object** in v2. @@ -195,10 +333,10 @@ The `ftReceiptCaseData` field changes from a **JSON-encoded string** in v0 to a ``` Key points: -- The outer field is now a **JSON object**, not a string -- The inner value (per market key) remains a **JSON-encoded string** of the market-specific payload -- Use the two-letter ISO market code as the key (`"FR"`, `"AT"`, `"DE"`) -- If `ftReceiptCaseData` is not needed for a particular receipt type, the field can be omitted entirely +- The outer field is now a **JSON object**, not a string. +- The inner value (per market key) remains a **JSON-encoded string** of the market-specific payload. +- Use the two-letter ISO market code as the key (`"FR"`, `"AT"`, `"DE"`). +- If `ftReceiptCaseData` is not needed for a particular receipt type, the field can be omitted entirely. ### ReceiptResponse changes @@ -249,3 +387,74 @@ A recommended cutover sequence: 3. Deploy Launcher 2.0 to the POS terminal 4. Update the POS system to call the v2 endpoint 5. Send a test Echo request to confirm connectivity before going live + + + + + + +## Configuration steps + +The portal-side configuration requires adding a **LocalPosSystemApi Helper** to your CashBox and rebuilding it with Launcher 2.0. Rather than duplicating those steps here, follow the [Local PosSystem API Helper guide](../../../../posdealers/technical-operations/middleware/helper-possystemapi.md), which covers: + +1. Adding a `fiskaltrust.Middleware.Helper.LocalPosSystemApi` Helper in the Portal +2. Configuring the Helper URL +3. Assigning the Helper to the relevant CashBox +4. Rebuilding the CashBox configuration +5. Downloading and running Launcher 2.0 + +## API changes + +### Method mapping + +The three core operations map directly from v0 to v2, but the calling convention changes from a .NET WCF/REST client to standard HTTP POST requests: + +| v0 call | v2 HTTP endpoint | Notes | +|--------------------------------------------------|-----------------------------------|-----------------------------------------------------------------------| +| `proxy.Echo("message")` | `POST /api/v2/echo` | Request body: `{"message": "..."}` — response mirrors the same structure: `{"message": "..."}` | +| `proxy.Sign(receiptRequest)` | `POST /api/v2/sign` | Request body is the JSON-serialised `ReceiptRequest`; response is `ReceiptResponse` | +| `proxy.Journal(ftJournalType, from, to)` | `POST /api/v2/journal` | Request body carries `ftJournalType`, `from`, and `to` as ISO 8601 date-time strings (see [Timestamps](#timestamps)) | + +#### Authentication + +All v2 requests must include the following HTTP headers: + +``` +cashboxid: +accesstoken: +``` + +Both values are available on the CashBox page in the fiskaltrust.Portal. On first use, you also need to **pair** the client via the PIN displayed in the Portal (see the [Helper setup guide](../../../../posdealers/technical-operations/middleware/helper-possystemapi.md#test-the-possystem-api-helper)). + +#### Echo example + +**Request:** + +```json +POST /api/v2/echo +{ + "message": "test" +} +``` + +**Response:** + +```json +{ + "message": "test" +} +``` + +### ReceiptRequest changes + +The v2 `ReceiptRequest` is a superset of the v0 model. Most existing fields are directly reusable; the key differences are: + +| Field | v0 | v2 | +|-----------------------------|-------------------------------------|-------------------------------------------------------| +| `cbReceiptReference` | Optional in some flows | **Required** — must be a unique string per request | +| `Currency` | Not present | Added — ISO 4217 currency code (default: `EUR`) | +| `DecimalPrecisionMultiplier`| Not present | Added — controls integer vs. floating-point amounts (default: `1`, i.e. floating-point) | +| `ftPosSystemID` | Optional | Recommended — identifies your POS software | + +All other fields (`ftCashBoxID`, `cbTerminalID`, `cbReceiptMoment`, `cbChargeItems`, `cbPayItems`, `ftReceiptCase`, etc.) carry over unchanged. + From b974faeb21ae5bb0166440a8ad19d422d2761089 Mon Sep 17 00:00:00 2001 From: deboragracio Date: Wed, 6 May 2026 16:59:45 +0200 Subject: [PATCH 05/10] Updated draft https://github.com/fiskaltrust/engineering/issues/1116 --- .../general/migration/v0-to-possystemapi.md | 179 ++++++++---------- 1 file changed, 83 insertions(+), 96 deletions(-) diff --git a/poscreators/middleware-doc/general/migration/v0-to-possystemapi.md b/poscreators/middleware-doc/general/migration/v0-to-possystemapi.md index 09abcd9..4f2f2d2 100644 --- a/poscreators/middleware-doc/general/migration/v0-to-possystemapi.md +++ b/poscreators/middleware-doc/general/migration/v0-to-possystemapi.md @@ -7,7 +7,7 @@ title: Migrating from API v0 to PosSystem API (v2) ## Introduction -The `ifPOS.v0` interface is the original, synchronous fiskaltrust.Middleware API used primarily in Austria (AT) and France (FR). While it remains functional, **it will not receive new features**. All current and future development — including e-invoicing support and upcoming compliance features — is available exclusively through the **PosSystem API (v2)**. +The legacy **v0 SignatureCloud API** (also referred to by its subdomain pattern `signaturcloud-sandbox.*`) and the original synchronous `ifPOS.v0` fiskaltrust.Middleware API - primarily used in Austria (AT) and France (FR) - remain functional but no longer receive new features. All current and future development, including e-invoicing support and upcoming compliance capabilities, is available exclusively through the **POSSystem API (v2)**, making migration strongly recommended. Migrating to v2 gives you: @@ -17,7 +17,7 @@ Migrating to v2 gives you: - **Simpler authentication** - PIN-based pairing for simpler, more secure authentication setup. - **Modern and flexible API design** - A modern, standard HTTP/REST API that works with any programming language or framework. -This guide is primarily targeted at POS Creators integrating **cloud cashboxes** in the **AT, FR, and DE** markets. +This guide is primarily targeted at PosCreators integrating **cloud cashboxes** in the **AT, FR, and DE** markets. ## Prerequisites @@ -40,7 +40,7 @@ The PosSystem API via Launcher 2.0 has market-specific constraints: ::: -## Architecture overview +## Architecture Overview The following table summarises the key architectural differences between the two integration approaches: @@ -66,7 +66,7 @@ POS System → WCF or REST (/v0/) → fiskaltrust Queue POS System → HTTP REST (/possystemapi/) → LocalPosSystemApi Helper → fiskaltrust Queue ``` -## Step 1: Cloud CashBox - Change the base URL +## Cloud CashBox (base URL change) If your integration targets a **Cloud CashBox** (for example, your POS system calls the fiskaltrust cloud endpoint rather than a locally-running Middleware), the base URL changes as part of the migration: @@ -97,13 +97,13 @@ The path structure changes accordingly: | Echo | `/[json|xml]/v0/echo` | `/api/v2/echo` | | Journal | `/[json|xml]/v0/journal` | `/api/v2/journal` | -## Step 2: Change Case Values +## Case Values The integer values used for `ftReceiptCase`, `ftChargeItemCase`, and `ftPayItemCase` differ between the v0 and v2 interfaces. Updating these values is the most substantial part of the migration. You must remap all case values in your requests. :::info Developer Portal -The authoritative source for v2 case values and their mapping to v0 cases is the **[fiskaltrust Developer Portal](https://developers.fiskaltrust.eu/#/pos-system)**. It provides market-specific business case examples (AT, FR, DE) with the correct v2 `ftReceiptCase`, `ftChargeItemCase`, and `ftPayItemCase` values for each scenario. Use these examples as your reference when updating your integration. +The authoritative source for v2 case values and their mapping to v0 cases is the [fiskaltrust Developer Portal](https://developers.fiskaltrust.eu/#/pos-system). It provides market-specific business case examples (AT, FR, DE) with the correct v2 `ftReceiptCase`, `ftChargeItemCase`, and `ftPayItemCase` values for each scenario. Use these examples as your reference when updating your integration. ::: @@ -114,7 +114,7 @@ A systematic approach to updating case values: 3. Replace the v0 value with the v2 value shown in the portal example. 4. Repeat for all receipt types (including special receipts such as Start-Receipt, Stop-Receipt, daily/shift closings, and Zero-Receipts). -### ftReceiptCase Mapping +### ftReceiptCase
Austria (AT) @@ -130,7 +130,7 @@ A systematic approach to updating case values: :::caution TODO -The POSSystemAPI v2 values for AT `ftReceiptCase` must be verified by the integration owners (Paul / Leila) against the internal mapping document. +The POSSystemAPI v2 values for AT `ftReceiptCase` must be verified. ::: @@ -152,7 +152,7 @@ The POSSystemAPI v2 values for AT `ftReceiptCase` must be verified by the integr :::caution TODO -The POSSystemAPI v2 values for FR `ftReceiptCase` must be verified by the integration owners (Paul / Leila) against the internal mapping document. +The POSSystemAPI v2 values for FR `ftReceiptCase` must be verified. ::: @@ -174,17 +174,9 @@ The POSSystemAPI v2 values for FR `ftReceiptCase` must be verified by the integr | Initiate SCU switch | `0x4445000000000017` | TODO | | Finish SCU switch | `0x4445000000000018` | TODO | -:::caution TODO - -The POSSystemAPI v2 values for DE `ftReceiptCase` must be verified by the integration owners (Paul / Leila) against the internal mapping document. - -::: -
---- - -### ftChargeItemCase Mapping +### ftChargeItemCase
Austria (AT) @@ -195,12 +187,6 @@ The POSSystemAPI v2 values for DE `ftReceiptCase` must be verified by the integr | Unknown type of service/product — discounted-1 | `0x4154000000000001` | TODO | | Unknown type of service/product — discounted-2 | `0x4154000000000002` | TODO | -:::caution TODO - -The POSSystemAPI v2 values for AT `ftChargeItemCase` must be verified by the integration owners (Paul / Leila) against the internal mapping document. - -::: -
@@ -212,12 +198,6 @@ The POSSystemAPI v2 values for AT `ftChargeItemCase` must be verified by the int | Unknown type of service/product — discounted-1 | `0x4652000000000001` | TODO | | Unknown type of service/product — discounted-2 | `0x4652000000000002` | TODO | -:::caution TODO - -The POSSystemAPI v2 values for FR `ftChargeItemCase` must be verified by the integration owners (Paul / Leila) against the internal mapping document. - -::: -
@@ -228,15 +208,9 @@ The POSSystemAPI v2 values for FR `ftChargeItemCase` must be verified by the int | Unknown type of service/product — normal rate | `0x4445000000000001` | TODO | | Unknown type of service/product — discounted-1 | `0x4445000000000002` | TODO | -:::caution TODO - -The POSSystemAPI v2 values for DE `ftChargeItemCase` must be verified by the integration owners (Paul / Leila) against the internal mapping document. - -::: -
-### ftPayItemCase Mapping +### ftPayItemCase
Austria (AT) @@ -253,12 +227,6 @@ The POSSystemAPI v2 values for DE `ftChargeItemCase` must be verified by the int | SEPA transfer | `0x415400000000000C` | TODO | | Internal material consumption | `0x4154000000000011` | TODO | -:::caution TODO - -The POSSystemAPI v2 values for AT `ftPayItemCase` must be verified by the integration owners (Paul / Leila) against the internal mapping document. - -::: -
@@ -276,12 +244,6 @@ The POSSystemAPI v2 values for AT `ftPayItemCase` must be verified by the integr | SEPA transfer | `0x465200000000000C` | TODO | | Internal material consumption | `0x4652000000000011` | TODO | -:::caution TODO - -The POSSystemAPI v2 values for FR `ftPayItemCase` must be verified by the integration owners (Paul / Leila) against the internal mapping document. - -::: -
@@ -299,16 +261,14 @@ The POSSystemAPI v2 values for FR `ftPayItemCase` must be verified by the integr | SEPA transfer | `0x4445000000000008` | TODO | | Internal material consumption | `0x444500000000000A` | TODO | -:::caution TODO - -The POSSystemAPI v2 values for DE `ftPayItemCase` must be verified by the integration owners (Paul / Leila) against the internal mapping document. - -::: -
+Key differences highlighted: +1. The base URL changes (see Step 1). +2. All `*Case` numeric values must be remapped (see mapping tables above). +3. `ftReceiptCaseData` is now an object keyed by market code instead of a raw string (see the section below). -### ftReceiptCaseData format change +### ftReceiptCaseData Format The `ftReceiptCaseData` field changes from a **JSON-encoded string** in v0 to a **market-keyed JSON object** in v2. @@ -338,7 +298,50 @@ Key points: - Use the two-letter ISO market code as the key (`"FR"`, `"AT"`, `"DE"`). - If `ftReceiptCaseData` is not needed for a particular receipt type, the field can be omitted entirely. -### ReceiptResponse changes +#### Examples by Market + +**Austria (AT)** + +```json +"ftReceiptCaseData": { + "AT": "{\"Code\": \"20\", \"Message\": \"Jahresbeleg\", \"Information\": \"\"}" +} +``` + +**France (FR)** + +```json +"ftReceiptCaseData": { + "FR": "{\"Code\": \"20\", \"Message\": \"Archivage fiscal de période\", \"Information\": \"\"}" +} +``` + +**Germany (DE)** + +```json +"ftReceiptCaseData": { + "DE": "{\"Code\": \"20\", \"Message\": \"Jahresabschluss\", \"Information\": \"\"}" +} +``` + +**Multi-market (combined)** + +```json +"ftReceiptCaseData": { + "AT": "{\"Code\": \"20\", \"Message\": \"Jahresbeleg\", \"Information\": \"\"}", + "FR": "{\"Code\": \"20\", \"Message\": \"Archivage fiscal de période\", \"Information\": \"\"}" +} +``` + +:::warning + +If `ftReceiptCaseData` is not needed for a particular receipt, pass an empty object (`{}`) or omit the field entirely. **Do not pass a bare empty string (`""`)** as the top-level value — that was valid in v0 but is no longer accepted at the outer level in v2. + +The inner string value for a given market key **may** be an empty string (`""`) when no additional case data is required for that market. + +::: + +### ReceiptResponse The `ReceiptResponse` structure is largely compatible. Verify that your receipt printing logic correctly handles: @@ -366,42 +369,40 @@ The v2 Journal request uses **ISO 8601 UTC date-time strings** in the JSON body: If you need to convert existing .NET Tick values, use the formulas from the [Function Structures reference](../function-structures/function-structures.md#timestamps). -## Testing the migration - -The easiest way to validate your v2 integration is the **[fiskaltrust Developer Portal](https://developers.fiskaltrust.eu/)**, which provides an interactive interface for sending requests to a running Middleware instance. - -For code samples and a full API reference, see the **[PosSystem API Development Kit](https://github.com/fiskaltrust/possystemapi-devkit)** on GitHub. - -## Cutover considerations - -:::caution No parallel operation - -Running the v0 and v2 interfaces in parallel on the same CashBox is not recommended. Perform the migration as a **clean cutover** per CashBox: reconfigure the CashBox with the LocalPosSystemApi Helper, rebuild it, deploy the new Launcher 2.0 package, then switch your POS system to use the new v2 endpoint. Ensure any buffered or in-flight v0 receipts are processed and closed before switching. - -::: +### ReceiptRequest -A recommended cutover sequence: +The v2 `ReceiptRequest` is a superset of the v0 model. Most existing fields are directly reusable; the key differences are: -1. Complete all open transactions / close the current business day in the POS system -2. Reconfigure the CashBox in the Portal (add Helper, rebuild) -3. Deploy Launcher 2.0 to the POS terminal -4. Update the POS system to call the v2 endpoint -5. Send a test Echo request to confirm connectivity before going live +| Field | v0 | v2 | +|-----------------------------|-------------------------------------|-------------------------------------------------------| +| `cbReceiptReference` | Optional in some flows | **Required** — must be a unique string per request | +| `Currency` | Not present | Added — ISO 4217 currency code (default: `EUR`) | +| `DecimalPrecisionMultiplier`| Not present | Added — controls integer vs. floating-point amounts (default: `1`, i.e. floating-point) | +| `ftPosSystemID` | Optional | Recommended — identifies your POS software | +All other fields (`ftCashBoxID`, `cbTerminalID`, `cbReceiptMoment`, `cbChargeItems`, `cbPayItems`, `ftReceiptCase`, etc.) carry over unchanged. +## Local CashBox +:::note Sandbox/admin access only +Local cashbox migration requires additional configuration steps that are currently only supported in sandbox environments under guidance from the fiskaltrust team. -## Configuration steps +::: The portal-side configuration requires adding a **LocalPosSystemApi Helper** to your CashBox and rebuilding it with Launcher 2.0. Rather than duplicating those steps here, follow the [Local PosSystem API Helper guide](../../../../posdealers/technical-operations/middleware/helper-possystemapi.md), which covers: -1. Adding a `fiskaltrust.Middleware.Helper.LocalPosSystemApi` Helper in the Portal -2. Configuring the Helper URL -3. Assigning the Helper to the relevant CashBox -4. Rebuilding the CashBox configuration -5. Downloading and running Launcher 2.0 +1. Adding a `fiskaltrust.Middleware.Helper.LocalPosSystemApi` Helper in the Portal. +2. Configuring the Helper URL. +3. Assigning the Helper to the relevant CashBox. +4. Rebuilding the CashBox configuration. +5. Downloading and running Launcher 2.0. + +For reference documentation on local cashbox configuration, see the country-specific middleware appendixes: +- [Austria - Middleware Documentation](/poscreators/middleware-doc/middleware-at-rksv/appendix-at-rksv) +- [France - Middleware Documentation](/poscreators/middleware-doc/middleware-fr-boi-tva-decla-30-10-30/appendix-fr-boi-tva-decla-30-10-30) +- [Germany - Middleware Documentation](/poscreators/middleware-doc/middleware-de-kassensichv/appendix-de-kassensichv) ## API changes @@ -444,17 +445,3 @@ POST /api/v2/echo "message": "test" } ``` - -### ReceiptRequest changes - -The v2 `ReceiptRequest` is a superset of the v0 model. Most existing fields are directly reusable; the key differences are: - -| Field | v0 | v2 | -|-----------------------------|-------------------------------------|-------------------------------------------------------| -| `cbReceiptReference` | Optional in some flows | **Required** — must be a unique string per request | -| `Currency` | Not present | Added — ISO 4217 currency code (default: `EUR`) | -| `DecimalPrecisionMultiplier`| Not present | Added — controls integer vs. floating-point amounts (default: `1`, i.e. floating-point) | -| `ftPosSystemID` | Optional | Recommended — identifies your POS software | - -All other fields (`ftCashBoxID`, `cbTerminalID`, `cbReceiptMoment`, `cbChargeItems`, `cbPayItems`, `ftReceiptCase`, etc.) carry over unchanged. - From 0c0bb30655a3705737f9043966c54535f01447cf Mon Sep 17 00:00:00 2001 From: deboragracio Date: Thu, 7 May 2026 14:48:24 +0200 Subject: [PATCH 06/10] Updated draft structure/other pages https://github.com/fiskaltrust/engineering/issues/1116 --- .../general/communication/communication.md | 4 +- .../function-structures.md | 4 +- .../general/migration/v0-to-possystemapi.md | 122 ++++++++---------- .../middleware-at-rksv/appendix-at-rksv.md | 2 +- .../appendix-de-kassensichv.md | 6 + .../appendix-fr-boi-tva-decla-30-10-30.md | 2 +- poscreators/toc.js | 10 +- 7 files changed, 65 insertions(+), 85 deletions(-) diff --git a/poscreators/middleware-doc/general/communication/communication.md b/poscreators/middleware-doc/general/communication/communication.md index 63cfb60..452513f 100644 --- a/poscreators/middleware-doc/general/communication/communication.md +++ b/poscreators/middleware-doc/general/communication/communication.md @@ -5,9 +5,9 @@ title: Communication # Communication -:::info Migrating to PosSystem API (v2)? +:::info PosSystem API (v2) Migration -If you are an Austria (AT) or France (FR) customer currently using the v0 WCF or REST interface and planning to move to the new PosSystem API, see the [v0 → PosSystem API migration guide](../migration/v0-to-possystemapi.md). +If you are an Austria (AT) or France (FR) customer currently using the v0 WCF or REST interface and planning to move to the new PosSystem API, see the Migrating from API v0 to PosSystem API (v2) guide. ::: diff --git a/poscreators/middleware-doc/general/function-structures/function-structures.md b/poscreators/middleware-doc/general/function-structures/function-structures.md index 6c9c389..c98dd5d 100644 --- a/poscreators/middleware-doc/general/function-structures/function-structures.md +++ b/poscreators/middleware-doc/general/function-structures/function-structures.md @@ -5,9 +5,9 @@ title: Function Structures # Function Structures -:::info Migrating to PosSystem API (v2)? +:::info PosSystem API (v2) Migration -If you are an Austria (AT) or France (FR) customer currently using the v0 synchronous `Sign`/`Echo`/`Journal` calls and planning to move to the new PosSystem API, see the [v0 → PosSystem API migration guide](../migration/v0-to-possystemapi.md). +If you are an Austria (AT) or France (FR) customer currently using the v0 synchronous `Sign`/`Echo`/`Journal` calls and planning to move to the new PosSystem API, see the Migrating from API v0 to PosSystem API (v2) guide. ::: diff --git a/poscreators/middleware-doc/general/migration/v0-to-possystemapi.md b/poscreators/middleware-doc/general/migration/v0-to-possystemapi.md index 4f2f2d2..755c45d 100644 --- a/poscreators/middleware-doc/general/migration/v0-to-possystemapi.md +++ b/poscreators/middleware-doc/general/migration/v0-to-possystemapi.md @@ -11,13 +11,17 @@ The legacy **v0 SignatureCloud API** (also referred to by its subdomain pattern Migrating to v2 gives you: -- **E-invoicing support** - Access to e-invoicing features and all future compliance capabilities +- **E-invoicing support** - Access to e-invoicing features and all future compliance capabilities. - **Alignment with fiskaltrust Middleware v2** — the POSSystemAPI interface is designed to remain largely stable when the middleware transitions from v1.2 to v2, making this migration valuable preparation. - **Long-term supportability** — v0 is considered deprecated; customers are encouraged to migrate as soon as possible. - **Simpler authentication** - PIN-based pairing for simpler, more secure authentication setup. - **Modern and flexible API design** - A modern, standard HTTP/REST API that works with any programming language or framework. +:::info + This guide is primarily targeted at PosCreators integrating **cloud cashboxes** in the **AT, FR, and DE** markets. + +::: ## Prerequisites @@ -28,8 +32,6 @@ Before starting the migration, ensure you have: - An existing integration that successfully produces receipts against the v0 SignatureCloud API. - Access to a **sandbox cashbox** for testing your migrated integration before going live. - **Launcher 2.0** (minimum version `2.0.0-rc.25`) — the PosSystem API requires Launcher 2.0. -- Familiarity with the [Local PosSystem API Helper setup guide](../../../../posdealers/technical-operations/middleware/helper-possystemapi.md). -- Familiarity with the **POSSystemAPI business case examples**, which serve as the reference for the new request format: [https://developers.fiskaltrust.eu/#/pos-system](https://developers.fiskaltrust.eu/#/pos-system) :::caution Market availability @@ -37,6 +39,7 @@ The PosSystem API via Launcher 2.0 has market-specific constraints: - **Austria (AT):** Launcher 2.0 is not enabled by default. Contact fiskaltrust support to enable it for your account. - **France (FR):** Launcher 2.0 is not yet supported. French customers should contact fiskaltrust for the current roadmap before planning a migration. +- **Germany (DE):** TBD ::: @@ -44,23 +47,23 @@ The PosSystem API via Launcher 2.0 has market-specific constraints: The following table summarises the key architectural differences between the two integration approaches: -| Aspect | v0 (legacy) | v2 — PosSystem API | +| Aspect | v0 (legacy) | v2 - PosSystem API | |-------------------------|-------------------------------------------------------------------|------------------------------------------------------------------| | **Protocol** | WCF (SOAP) or REST `/v0/` | HTTP REST `/possystemapi/` | | **Communication style** | Synchronous (blocking) | Modern REST (JSON) | | **Middleware component**| Queue package directly | LocalPosSystemApi Helper in front of the Queue | | **Launcher** | Launcher 1.x | Launcher 2.0 (min. `2.0.0-rc.25`) | -| **Authentication** | CashboxID + AccessToken (per request / in service binding) | CashboxID + AccessToken in HTTP headers, PIN pairing via Portal | -| **Client libraries** | .NET `ifPOS.v0` NuGet package, WCF proxies, or REST HTTP calls | Any HTTP client; official devkit available | -| **New feature support** | None — no new features planned | All new features (e-invoicing, etc.) | +| **Authentication** | Cashbox ID + AccessToken (per request / in service binding) | Cashbox ID + AccessToken in HTTP headers, PIN pairing via Portal | +| **Client libraries** | .NET `ifPOS.v0` NuGet package, WCF proxies, or REST HTTP calls | Any HTTP client +| **New feature support** | None - no new features planned | All new features (e-invoicing, etc.) | -**v0 data flow:** +- **v0 data flow:** ``` POS System → WCF or REST (/v0/) → fiskaltrust Queue ``` -**v2 data flow:** +- **v2 data flow:** ``` POS System → HTTP REST (/possystemapi/) → LocalPosSystemApi Helper → fiskaltrust Queue @@ -81,9 +84,7 @@ If your integration targets a **Cloud CashBox** (for example, your POS system ca :::info -The new endpoint is **market-agnostic** — the same base URL is used for AT, FR, and DE. The market is determined by the `ftCashBoxID` and queue configuration, not the URL. - -Note that the v2 cloud endpoint is a **single, market-agnostic URL** — the market is determined by the `ftReceiptCase` value and your CashBox configuration, not the host. +The v2 cloud endpoint uses a single, market-agnostic base URL for all markets (AT, FR, DE), with the actual market determined by values such as the `ftCashBoxID` / `ftReceiptCase` and your **CashBox and queue configuration**, not by the URL or host. ::: @@ -97,24 +98,24 @@ The path structure changes accordingly: | Echo | `/[json|xml]/v0/echo` | `/api/v2/echo` | | Journal | `/[json|xml]/v0/journal` | `/api/v2/journal` | -## Case Values +### Case Values The integer values used for `ftReceiptCase`, `ftChargeItemCase`, and `ftPayItemCase` differ between the v0 and v2 interfaces. Updating these values is the most substantial part of the migration. You must remap all case values in your requests. -:::info Developer Portal +:::info Development Plataform -The authoritative source for v2 case values and their mapping to v0 cases is the [fiskaltrust Developer Portal](https://developers.fiskaltrust.eu/#/pos-system). It provides market-specific business case examples (AT, FR, DE) with the correct v2 `ftReceiptCase`, `ftChargeItemCase`, and `ftPayItemCase` values for each scenario. Use these examples as your reference when updating your integration. +The authoritative source for v2 case values and their mapping to v0 cases is the **fiskaltrust** [Development Platform](https://developers.fiskaltrust.eu/#/pos-system). It provides market-specific business case examples (AT, FR, DE) with the correct v2 `ftReceiptCase`, `ftChargeItemCase`, and `ftPayItemCase` values for each scenario. Use these examples as your reference when updating your integration. ::: A systematic approach to updating case values: 1. List every `ftReceiptCase`, `ftChargeItemCase`, and `ftPayItemCase` value currently used in your integration. -2. For each value, find the corresponding business case in the Developer Portal for your market. -3. Replace the v0 value with the v2 value shown in the portal example. +2. For each value, find the corresponding business case in the [Development Platform](https://developers.fiskaltrust.eu/#/pos-system) for your market. +3. Replace the v0 value with the v2 value shown in the platform example. 4. Repeat for all receipt types (including special receipts such as Start-Receipt, Stop-Receipt, daily/shift closings, and Zero-Receipts). -### ftReceiptCase +#### ftReceiptCase
Austria (AT) @@ -128,12 +129,6 @@ A systematic approach to updating case values: | Monthly closing | `0x4154000000000005` | TODO | | Yearly closing | `0x4154000000000006` | TODO | -:::caution TODO - -The POSSystemAPI v2 values for AT `ftReceiptCase` must be verified. - -::: -
@@ -150,12 +145,6 @@ The POSSystemAPI v2 values for AT `ftReceiptCase` must be verified. | Yearly closing | `0x4652000000000007` | TODO | | Archives / fiscal period archive | `0x4652000000000015` | TODO | -:::caution TODO - -The POSSystemAPI v2 values for FR `ftReceiptCase` must be verified. - -::: -
@@ -176,7 +165,7 @@ The POSSystemAPI v2 values for FR `ftReceiptCase` must be verified.
-### ftChargeItemCase +#### ftChargeItemCase
Austria (AT) @@ -210,7 +199,7 @@ The POSSystemAPI v2 values for FR `ftReceiptCase` must be verified.
-### ftPayItemCase +#### ftPayItemCase
Austria (AT) @@ -264,15 +253,15 @@ The POSSystemAPI v2 values for FR `ftReceiptCase` must be verified.
Key differences highlighted: -1. The base URL changes (see Step 1). -2. All `*Case` numeric values must be remapped (see mapping tables above). -3. `ftReceiptCaseData` is now an object keyed by market code instead of a raw string (see the section below). +1. The base URL changes. +2. All case numeric values must be remapped. +3. `ftReceiptCaseData` is now an object keyed by market code instead of a raw string. -### ftReceiptCaseData Format +#### ftReceiptCaseData Format The `ftReceiptCaseData` field changes from a **JSON-encoded string** in v0 to a **market-keyed JSON object** in v2. -**v0 format** — the entire value is a JSON string embedded as a string field: +- **v0 format**: the entire value is a JSON string embedded as a string field. ```json { @@ -281,7 +270,7 @@ The `ftReceiptCaseData` field changes from a **JSON-encoded string** in v0 to a } ``` -**v2 format** — the value is a plain JSON object with a market key (`"FR"`, `"AT"`, `"DE"`) whose value is a JSON-encoded string: +- **v2 format**: the value is a plain JSON object with a market key (`"FR"`, `"AT"`, `"DE"`) whose value is a JSON-encoded string. ```json { @@ -296,9 +285,8 @@ Key points: - The outer field is now a **JSON object**, not a string. - The inner value (per market key) remains a **JSON-encoded string** of the market-specific payload. - Use the two-letter ISO market code as the key (`"FR"`, `"AT"`, `"DE"`). -- If `ftReceiptCaseData` is not needed for a particular receipt type, the field can be omitted entirely. -#### Examples by Market +##### Examples by Market **Austria (AT)** @@ -335,20 +323,33 @@ Key points: :::warning -If `ftReceiptCaseData` is not needed for a particular receipt, pass an empty object (`{}`) or omit the field entirely. **Do not pass a bare empty string (`""`)** as the top-level value — that was valid in v0 but is no longer accepted at the outer level in v2. +If `ftReceiptCaseData` is not needed for a particular receipt, pass an empty object (`{}`) or omit the field entirely. Do not pass a bare empty string (`""`) as the top-level value — that was valid in v0 but is no longer accepted at the outer level in v2. -The inner string value for a given market key **may** be an empty string (`""`) when no additional case data is required for that market. +The inner string value for a given market key may be an empty string (`""`) when no additional case data is required for that market. ::: -### ReceiptResponse +#### ReceiptRequest + +The v2 `ReceiptRequest` is a superset of the v0 model. Most existing fields are directly reusable. The key differences are: + +| Field | v0 | v2 | +|-----------------------------|-------------------------------------|-------------------------------------------------------| +| `cbReceiptReference` | Optional in some flows | **Required** — must be a unique string per request | +| `Currency` | Not present | Added — ISO 4217 currency code (default: `EUR`) | +| `DecimalPrecisionMultiplier`| Not present | Added — controls integer vs. floating-point amounts (default: `1`, i.e. floating-point) | +| `ftPosSystemID` | Optional | Recommended — identifies your POS software | + +All other fields (`ftCashBoxID`, `cbTerminalID`, `cbReceiptMoment`, `cbChargeItems`, `cbPayItems`, `ftReceiptCase`, etc.) carry over unchanged. + +#### ReceiptResponse The `ReceiptResponse` structure is largely compatible. Verify that your receipt printing logic correctly handles: -- `ftSignatures` — format and type values are unchanged; ensure all entries are printed as required by national regulations -- `ftState` — error flag interpretation is unchanged; check your error-handling code still covers all states +- `ftSignatures` — format and type values are unchanged; ensure all entries are printed as required by national regulations. +- `ftState` — error flag interpretation is unchanged; check your error-handling code still covers all states. -### Timestamps +#### Timestamps The v0 Journal call used **.NET Ticks** for the `from` and `to` parameters: @@ -369,20 +370,6 @@ The v2 Journal request uses **ISO 8601 UTC date-time strings** in the JSON body: If you need to convert existing .NET Tick values, use the formulas from the [Function Structures reference](../function-structures/function-structures.md#timestamps). -### ReceiptRequest - -The v2 `ReceiptRequest` is a superset of the v0 model. Most existing fields are directly reusable; the key differences are: - -| Field | v0 | v2 | -|-----------------------------|-------------------------------------|-------------------------------------------------------| -| `cbReceiptReference` | Optional in some flows | **Required** — must be a unique string per request | -| `Currency` | Not present | Added — ISO 4217 currency code (default: `EUR`) | -| `DecimalPrecisionMultiplier`| Not present | Added — controls integer vs. floating-point amounts (default: `1`, i.e. floating-point) | -| `ftPosSystemID` | Optional | Recommended — identifies your POS software | - -All other fields (`ftCashBoxID`, `cbTerminalID`, `cbReceiptMoment`, `cbChargeItems`, `cbPayItems`, `ftReceiptCase`, etc.) carry over unchanged. - - ## Local CashBox :::note Sandbox/admin access only @@ -391,7 +378,7 @@ Local cashbox migration requires additional configuration steps that are current ::: -The portal-side configuration requires adding a **LocalPosSystemApi Helper** to your CashBox and rebuilding it with Launcher 2.0. Rather than duplicating those steps here, follow the [Local PosSystem API Helper guide](../../../../posdealers/technical-operations/middleware/helper-possystemapi.md), which covers: +The portal-side configuration requires adding a **LocalPosSystemApi Helper** to your CashBox and rebuilding it with Launcher 2.0. Rather than duplicating those steps here, follow the [How to Configure the Local PosSystem API Helper with Launcher 2.0](../../../../posdealers/technical-operations/middleware/helper-possystemapi.md) guide, which covers: 1. Adding a `fiskaltrust.Middleware.Helper.LocalPosSystemApi` Helper in the Portal. 2. Configuring the Helper URL. @@ -399,14 +386,9 @@ The portal-side configuration requires adding a **LocalPosSystemApi Helper** to 4. Rebuilding the CashBox configuration. 5. Downloading and running Launcher 2.0. -For reference documentation on local cashbox configuration, see the country-specific middleware appendixes: -- [Austria - Middleware Documentation](/poscreators/middleware-doc/middleware-at-rksv/appendix-at-rksv) -- [France - Middleware Documentation](/poscreators/middleware-doc/middleware-fr-boi-tva-decla-30-10-30/appendix-fr-boi-tva-decla-30-10-30) -- [Germany - Middleware Documentation](/poscreators/middleware-doc/middleware-de-kassensichv/appendix-de-kassensichv) - -## API changes +### API changes -### Method mapping +#### Method mapping The three core operations map directly from v0 to v2, but the calling convention changes from a .NET WCF/REST client to standard HTTP POST requests: @@ -416,7 +398,7 @@ The three core operations map directly from v0 to v2, but the calling convention | `proxy.Sign(receiptRequest)` | `POST /api/v2/sign` | Request body is the JSON-serialised `ReceiptRequest`; response is `ReceiptResponse` | | `proxy.Journal(ftJournalType, from, to)` | `POST /api/v2/journal` | Request body carries `ftJournalType`, `from`, and `to` as ISO 8601 date-time strings (see [Timestamps](#timestamps)) | -#### Authentication +##### Authentication All v2 requests must include the following HTTP headers: @@ -427,7 +409,7 @@ accesstoken: Both values are available on the CashBox page in the fiskaltrust.Portal. On first use, you also need to **pair** the client via the PIN displayed in the Portal (see the [Helper setup guide](../../../../posdealers/technical-operations/middleware/helper-possystemapi.md#test-the-possystem-api-helper)). -#### Echo example +##### Echo example **Request:** diff --git a/poscreators/middleware-doc/middleware-at-rksv/appendix-at-rksv.md b/poscreators/middleware-doc/middleware-at-rksv/appendix-at-rksv.md index ae70f99..5715160 100644 --- a/poscreators/middleware-doc/middleware-at-rksv/appendix-at-rksv.md +++ b/poscreators/middleware-doc/middleware-at-rksv/appendix-at-rksv.md @@ -19,7 +19,7 @@ Ritz/Koran/Kutschera/Knasmüller, Handbuch Registrierkassen- und Belegerteilungs :::info Upgrading to PosSystem API (v2) -New features such as e-invoicing are available exclusively through the **PosSystem API (v2)**. If you are currently using the v0 interface (WCF/REST), see the [v0 → PosSystem API migration guide](../general/migration/v0-to-possystemapi.md) for step-by-step instructions. +New features such as e-invoicing are available exclusively through the **PosSystem API (v2)**. If you are currently using the v0 interface (WCF/REST), see the Migrating from API v0 to PosSystem API (v2) guide for instructions. ::: diff --git a/poscreators/middleware-doc/middleware-de-kassensichv/appendix-de-kassensichv.md b/poscreators/middleware-doc/middleware-de-kassensichv/appendix-de-kassensichv.md index 212dacd..da9e099 100644 --- a/poscreators/middleware-doc/middleware-de-kassensichv/appendix-de-kassensichv.md +++ b/poscreators/middleware-doc/middleware-de-kassensichv/appendix-de-kassensichv.md @@ -7,4 +7,10 @@ title: Introduction This appendix expands on the General Part's information by adding details specific to the German market. This additional information is provided only where applicable. The remaining chapters, for which there is no further information required, were omitted. +:::info Upgrading to PosSystem API (v2) + +New features such as e-invoicing are available exclusively through the **PosSystem API (v2)**. If you are currently using the v0 interface (WCF/REST), see the Migrating from API v0 to PosSystem API (v2) guide for instructions. + +::: + diff --git a/poscreators/middleware-doc/middleware-fr-boi-tva-decla-30-10-30/appendix-fr-boi-tva-decla-30-10-30.md b/poscreators/middleware-doc/middleware-fr-boi-tva-decla-30-10-30/appendix-fr-boi-tva-decla-30-10-30.md index 8ebacda..9236df1 100644 --- a/poscreators/middleware-doc/middleware-fr-boi-tva-decla-30-10-30/appendix-fr-boi-tva-decla-30-10-30.md +++ b/poscreators/middleware-doc/middleware-fr-boi-tva-decla-30-10-30/appendix-fr-boi-tva-decla-30-10-30.md @@ -25,7 +25,7 @@ The interface specification is provided by fiskaltrust.Interface NuGet package, :::info Upgrading to PosSystem API (v2) -New features such as e-invoicing are available exclusively through the **PosSystem API (v2)**. If you are currently using the v0 interface (WCF/REST), see the [v0 → PosSystem API migration guide](../general/migration/v0-to-possystemapi.md) for step-by-step instructions. +New features such as e-invoicing are available exclusively through the **PosSystem API (v2)**. If you are currently using the v0 interface (WCF/REST), see the Migrating from API v0 to PosSystem API (v2) guide for instructions. ::: diff --git a/poscreators/toc.js b/poscreators/toc.js index 71e8ecb..fbc3e11 100644 --- a/poscreators/toc.js +++ b/poscreators/toc.js @@ -370,15 +370,7 @@ module.exports = [ }, ], }, - { - type: "category", - label: "Migration Guides", - collapsed: true, - items: [ - "poscreators/middleware-doc/general/migration/v0-to-possystemapi", - ], - }, - ], + ], }, { type: "category", From 656786a1f59f1f05e6a1e2f46c101edc53bf5d7b Mon Sep 17 00:00:00 2001 From: deboragracio Date: Thu, 7 May 2026 15:11:14 +0200 Subject: [PATCH 07/10] fixed link --- .../middleware-doc/general/migration/v0-to-possystemapi.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/poscreators/middleware-doc/general/migration/v0-to-possystemapi.md b/poscreators/middleware-doc/general/migration/v0-to-possystemapi.md index 755c45d..138f035 100644 --- a/poscreators/middleware-doc/general/migration/v0-to-possystemapi.md +++ b/poscreators/middleware-doc/general/migration/v0-to-possystemapi.md @@ -104,14 +104,14 @@ The integer values used for `ftReceiptCase`, `ftChargeItemCase`, and `ftPayItemC :::info Development Plataform -The authoritative source for v2 case values and their mapping to v0 cases is the **fiskaltrust** [Development Platform](https://developers.fiskaltrust.eu/#/pos-system). It provides market-specific business case examples (AT, FR, DE) with the correct v2 `ftReceiptCase`, `ftChargeItemCase`, and `ftPayItemCase` values for each scenario. Use these examples as your reference when updating your integration. +The authoritative source for v2 case values and their mapping to v0 cases is the **fiskaltrust** [Development Platform](https://developers.fiskaltrust.eu/pos-system). It provides market-specific business case examples (AT, FR, DE) with the correct v2 `ftReceiptCase`, `ftChargeItemCase`, and `ftPayItemCase` values for each scenario. Use these examples as your reference when updating your integration. ::: A systematic approach to updating case values: 1. List every `ftReceiptCase`, `ftChargeItemCase`, and `ftPayItemCase` value currently used in your integration. -2. For each value, find the corresponding business case in the [Development Platform](https://developers.fiskaltrust.eu/#/pos-system) for your market. +2. For each value, find the corresponding business case in the [Development Platform](https://developers.fiskaltrust.eu/pos-system#/pos-system) for your market. 3. Replace the v0 value with the v2 value shown in the platform example. 4. Repeat for all receipt types (including special receipts such as Start-Receipt, Stop-Receipt, daily/shift closings, and Zero-Receipts). From 5c88f964f5ecccbdfa10f3c5d352065dd4832b3b Mon Sep 17 00:00:00 2001 From: deboragracio Date: Thu, 7 May 2026 15:15:22 +0200 Subject: [PATCH 08/10] fixed links --- .../middleware-doc/general/migration/v0-to-possystemapi.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/poscreators/middleware-doc/general/migration/v0-to-possystemapi.md b/poscreators/middleware-doc/general/migration/v0-to-possystemapi.md index 138f035..7701a11 100644 --- a/poscreators/middleware-doc/general/migration/v0-to-possystemapi.md +++ b/poscreators/middleware-doc/general/migration/v0-to-possystemapi.md @@ -104,14 +104,14 @@ The integer values used for `ftReceiptCase`, `ftChargeItemCase`, and `ftPayItemC :::info Development Plataform -The authoritative source for v2 case values and their mapping to v0 cases is the **fiskaltrust** [Development Platform](https://developers.fiskaltrust.eu/pos-system). It provides market-specific business case examples (AT, FR, DE) with the correct v2 `ftReceiptCase`, `ftChargeItemCase`, and `ftPayItemCase` values for each scenario. Use these examples as your reference when updating your integration. +The authoritative source for v2 case values and their mapping to v0 cases is the **fiskaltrust** [Development Platform](https://developer.fiskaltrust.eu/). It provides market-specific business case examples (AT, FR, DE) with the correct v2 `ftReceiptCase`, `ftChargeItemCase`, and `ftPayItemCase` values for each scenario. Use these examples as your reference when updating your integration. ::: A systematic approach to updating case values: 1. List every `ftReceiptCase`, `ftChargeItemCase`, and `ftPayItemCase` value currently used in your integration. -2. For each value, find the corresponding business case in the [Development Platform](https://developers.fiskaltrust.eu/pos-system#/pos-system) for your market. +2. For each value, find the corresponding business case in the [Development Platform](https://developer.fiskaltrust.eu/) for your market. 3. Replace the v0 value with the v2 value shown in the platform example. 4. Repeat for all receipt types (including special receipts such as Start-Receipt, Stop-Receipt, daily/shift closings, and Zero-Receipts). From 858d2818b5afc129091cbf658ff9b53d9fe48224 Mon Sep 17 00:00:00 2001 From: deboragracio Date: Thu, 7 May 2026 15:47:19 +0200 Subject: [PATCH 09/10] minor changes https://github.com/fiskaltrust/engineering/issues/1116 --- .../general/migration/v0-to-possystemapi.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/poscreators/middleware-doc/general/migration/v0-to-possystemapi.md b/poscreators/middleware-doc/general/migration/v0-to-possystemapi.md index 7701a11..4ccacdb 100644 --- a/poscreators/middleware-doc/general/migration/v0-to-possystemapi.md +++ b/poscreators/middleware-doc/general/migration/v0-to-possystemapi.md @@ -7,15 +7,15 @@ title: Migrating from API v0 to PosSystem API (v2) ## Introduction -The legacy **v0 SignatureCloud API** (also referred to by its subdomain pattern `signaturcloud-sandbox.*`) and the original synchronous `ifPOS.v0` fiskaltrust.Middleware API - primarily used in Austria (AT) and France (FR) - remain functional but no longer receive new features. All current and future development, including e-invoicing support and upcoming compliance capabilities, is available exclusively through the **POSSystem API (v2)**, making migration strongly recommended. +The legacy **v0 SignatureCloud API** (also referred to by its subdomain pattern `signaturcloud-sandbox.*`) and the original synchronous `ifPOS.v0` fiskaltrust.Middleware API — primarily used in Austria (AT) and France (FR) — remain functional but no longer receive new features. All current and future development, including e-invoicing support and upcoming compliance capabilities, is available exclusively through the **POSSystem API (v2)**, making migration strongly recommended. Migrating to v2 gives you: -- **E-invoicing support** - Access to e-invoicing features and all future compliance capabilities. +- **E-invoicing support** — Access to e-invoicing features and all future compliance capabilities. - **Alignment with fiskaltrust Middleware v2** — the POSSystemAPI interface is designed to remain largely stable when the middleware transitions from v1.2 to v2, making this migration valuable preparation. - **Long-term supportability** — v0 is considered deprecated; customers are encouraged to migrate as soon as possible. -- **Simpler authentication** - PIN-based pairing for simpler, more secure authentication setup. -- **Modern and flexible API design** - A modern, standard HTTP/REST API that works with any programming language or framework. +- **Simpler authentication** — PIN-based pairing for simpler, more secure authentication setup. +- **Modern and flexible API design** — A modern, standard HTTP/REST API that works with any programming language or framework. :::info @@ -84,7 +84,7 @@ If your integration targets a **Cloud CashBox** (for example, your POS system ca :::info -The v2 cloud endpoint uses a single, market-agnostic base URL for all markets (AT, FR, DE), with the actual market determined by values such as the `ftCashBoxID` / `ftReceiptCase` and your **CashBox and queue configuration**, not by the URL or host. +The v2 cloud endpoint uses a single, market-agnostic base URL for all markets (AT, FR, DE), with the actual market determined by values such as the `ftCashBoxID`, `ftReceiptCase` and your **CashBox and queue configuration**, not by the URL or host. ::: @@ -407,7 +407,7 @@ cashboxid: accesstoken: ``` -Both values are available on the CashBox page in the fiskaltrust.Portal. On first use, you also need to **pair** the client via the PIN displayed in the Portal (see the [Helper setup guide](../../../../posdealers/technical-operations/middleware/helper-possystemapi.md#test-the-possystem-api-helper)). +Both values are available on the CashBox page in the fiskaltrust.Portal. On first use, you also need to **pair** the client via the PIN displayed in the Portal. For more information, see how to [Test the PosSystem API Helper](../../../../posdealers/technical-operations/middleware/helper-possystemapi.md#test-the-possystem-api-helper). ##### Echo example From 2e655e70f835c6648ce520f18fd9c323ee003bb7 Mon Sep 17 00:00:00 2001 From: Arnaud Chentil Date: Thu, 21 May 2026 11:58:57 +0200 Subject: [PATCH 10/10] Add business cases changes for ftReceiptCase (fr market) --- .../general/migration/v0-to-possystemapi.md | 44 ++++++++++++++----- 1 file changed, 34 insertions(+), 10 deletions(-) diff --git a/poscreators/middleware-doc/general/migration/v0-to-possystemapi.md b/poscreators/middleware-doc/general/migration/v0-to-possystemapi.md index 4ccacdb..bf341d8 100644 --- a/poscreators/middleware-doc/general/migration/v0-to-possystemapi.md +++ b/poscreators/middleware-doc/general/migration/v0-to-possystemapi.md @@ -114,6 +114,8 @@ A systematic approach to updating case values: 2. For each value, find the corresponding business case in the [Development Platform](https://developer.fiskaltrust.eu/) for your market. 3. Replace the v0 value with the v2 value shown in the platform example. 4. Repeat for all receipt types (including special receipts such as Start-Receipt, Stop-Receipt, daily/shift closings, and Zero-Receipts). +5. If you don't find some values used in your integration in the table below, it seams that you just have to change the v0 with the v2 value. +6. **Important:** You'll see, in certain cases, for the same value in v0, you now need to specify a more precise value. For example, with invoices, there was only one code in v0, but now there are several possible values. Your POS system must therefore integrate whether the invoice is issued for B2C, B2B, B2G, etc. #### ftReceiptCase @@ -134,16 +136,38 @@ A systematic approach to updating case values:
France (FR) -| Business Case | v0 Value | POSSystemAPI v2 Value | -|---------------|----------|-----------------------| -| Cash sales / POS receipt | `0x4652000000000001` | TODO | -| Zero receipt | `0x465200000000000F` | TODO | -| Initial operation / start receipt | `0x4652000000000010` | TODO | -| Out of operation / stop receipt | `0x4652000000000011` | TODO | -| Daily closing | `0x4652000000000005` | TODO | -| Monthly closing | `0x4652000000000006` | TODO | -| Yearly closing | `0x4652000000000007` | TODO | -| Archives / fiscal period archive | `0x4652000000000015` | TODO | +| Business Case | v0 Value | POSSystemAPI v2 Value | Comment | +|---------------|----------|-----------------------|---------| +| Foreign sales | `0x465200000000000E` | `0x4652200008000000` | Unknown receipt type. Use this as a fallback; it is handled the same way as a point-of-sale receipt. | +| Foreign sales | `0x465200000000000E` | `0x4652200008000001` | Point-of-sale receipt type. | +| Foreign sales | `0x465200000000000E` | `0x4652200008000002` | Payment transfer receipt type. | +| Foreign sales | `0x465200000000000E` | `0x4652200008000003` | Point-of-sale receipt without fiscalization obligation or with exceptions to fiscalization regulations. | +| Payment transfer | `0x465200000000000A` or `0x465200000000000B` or `0x465200000000000C` | `0x4652200000000002` | All payment transfer receipt types ; conditional. pay-in to drawer/till, pay-out from drawer/till | +| Point-of-sale receipt type without fiskalisation obligation or with exemption | `0x465200000000000E` | `0x4652200000000003` | | +| E-commerce receipt type | `0x465200000000000E` | `0x4652200000000004` | | +| Delivery note receipt type | `0x4652000000000009` | `0x4652200000000005` | | +| Bill receipt type | `0x4652000000000008` | `0x4652200000000006` | | +| Proforma invoice receipt type | `0x4652000000000008` | `0x4652200000000007` | | +| Unknown invoice type | `0x4652000000000003` | `0x4652200000001000` | Your POS system must therefore integrate whether the invoice is issued for B2C, B2B, B2G, etc. | +| B2C invoice type | `0x4652000000000003` | `0x4652200000001001` | Your POS system must therefore integrate whether the invoice is issued for B2C, B2B, B2G, etc. | +| B2B invoice type | `0x4652000000000003` | `0x4652200000001002` | Your POS system must therefore integrate whether the invoice is issued for B2C, B2B, B2G, etc. | +| B2G invoice type | `0x4652000000000003` | `0x4652200000001003` | Your POS system must therefore integrate whether the invoice is issued for B2C, B2B, B2G, etc. | +| Zero receipt dailyoperation type | `0x465200000000000F` | `0x4652200000002000` | | +| Shift closing dailyoperation type | `0x4652000000000004` | `0x4652200000002010` | | +| Daily closing dailyoperation type | `0x4652000000000005` | `0x4652200000002011` | | +| Monthly closing dailyoperation type | `0x4652000000000006` | `0x4652200000002012` | | +| Yearly closing dailyoperation type | `0x4652000000000007` | `0x4652200000002013` | | +| Unknown/unspecified protocol type | `0x4652000000000014` | `0x4652200000003000` | | +| Technical event protocol type | `0x4652000000000012` | `0x4652200000003001` | | +| Audit event / accounting event protocol type | `0x4652000000000013` | `0x4652200000003002` | | +| Internal usage / material consumption protocol type | `0x465200000000000D` | `0x4652200000003003` | | +| Order protocol type | `0x4652000000000008` | `0x4652200000003004` | | +| Pay protocol type | `0x4652000000000002` | `0x4652200000003005` | Payment prove | +| Copy receipt / re-print existing receipt protocol type | `0x4652000000000016` | `0x4652200000003010` | | +| Archive receipt / archive all previous data protocol type | `0x4652000000000015` | `0x4652200000003011` | | +| Start-receipt lifecycle type | `0x4652000000000010` | `0x4652200000004001` | | +| Stop-receipt lifecycle type | `0x4652000000000011` | `0x4652200000004002` | | +| IsReturn/IsRefund | `0x4652000000040000` | `0x4652200001000000` | Full return/refund receipt. If one or more charge items are returned/refunded, please use the appropriate receipt type and the corresponding ChargeItemCase tag. |