General Description of the Software Solution

This software solution (referred to below as SEF — the fiscalization software integrated into a business' POS/ERP system) is a PHP-based client library and companion test console that implements the integration between a business' point of sale / ERP system and the ATK (Tatimore e Kosovës) central Fiscalization System.

Its purpose is to allow any POS/ERP vendor to:

• Build fiscal coupons (receipts) in the exact binary format required by ATK (Protocol Buffers), using either a full POS Coupon (the detailed receipt) or a summarized Citizen Coupon (the data embedded in the printed QR code).
• Digitally sign those coupons with the business/POS' own ECDSA private key, so that ATK can verify their authenticity and integrity.
• Submit the signed POS Coupon to ATK automatically at the moment of sale, and make the signed Citizen Coupon available as a QR code that customers can scan with the ATK Citizen Mobile App.

Deployment model. Rather than distributing this library separately to every client, it will be operated as a single centralized fiscalization service, hosted at https://fiscalization.starsoft.app. Multiple client ERP/POS applications (from different vendors/technologies) will integrate with this one central service over its HTTP API, submitting their sale data in the API/JSON format described below (see section 3.3). The centralized service takes care of building, signing, and submitting the coupons to ATK on behalf of each onboarded business, and returns the resulting QR code data back to the calling ERP.

The repository is organized into the following main parts:

1. Coupon construction — building PosCoupon and CitizenCoupon protobuf messages from structured sale data: business/POS/branch identifiers, operator, line items (CouponItem: name, unit, price, quantity, tax rate, total), payments (Payment: cash, credit card, voucher, cheque, cryptocurrency, other), and tax groups (TaxGroup: rate code, taxable base, tax amount).
2. VAT/tax-rate handling — support for the four ATK tax rate codes: A (0%, exempt), C (0%, zero-rated), D (8%, reduced), E (18%, standard), with automatic aggregation into TaxGroup totals that must reconcile between the POS Coupon and the Citizen Coupon.
3. Digital signing (PKI/ECDSA) — serializing a coupon to Protobuf binary, Base64-encoding it, hashing it with SHA-256, and signing the hash with the business/POS' ECDSA private key via PHP's OpenSSL extension.
4. QR code generation — combining the Base64-encoded Citizen Coupon and its Base64-encoded signature (<data>|<signature>) into the string that is encoded as the QR code printed on the physical fiscal receipt.
5. Submission to the ATK Fiscalization Service — sending the signed POS Coupon to ATK's /pos/coupon endpoint at the time of sale, and (for testing) sending the signed Citizen Coupon to /citizen/coupon, mimicking what the Citizen Mobile App does when a customer scans the receipt's QR code.
6. Local Test Console (public/index.html) — paste or edit raw Citizen/POS coupon JSON, then Build & Sign (locally only) or Build, Sign & Send (a real call to ATK), and inspect the resulting Base64 payload, signature, QR string and HTTP response.
7. POS Manual Sale simulator (public/pos-sale.html) — a guided cash-register-style form: add items with a per-line tax rate, take one or more split payments, and automatically compute subtotals, tax groups and totals; then build/sign (and optionally send) both the POS Coupon and its matching Citizen Coupon in one action, rendering a scannable QR code image.
8. User documentation (public/manual.html) — bilingual (English/Albanian) step-by-step instructions and troubleshooting guidance for using the tools above.
9. PKI onboarding tool (onboarder) — a separate cross-platform executable that generates the POS' unique ECDSA key pair, produces a Certificate Signing Request (CSR), submits it to the ATK Certificate Authority, and retrieves/exports the signed certificate and private key (PEM format) used by this software's Signer class.

Integration between the business' software (SEF) and the ATK central Fiscalization System happens in two phases: a one-time onboarding phase and the recurring, per-sale fiscalization phase.

3.1 Onboarding (one time, per POS/till)

1. The business runs the onboarder utility on the specific POS machine, using -env=TEST or -env=PROD, providing the business NUI, Fiscalization Number (obtained from EDI) and a unique POS ID / Branch ID.
2. The utility generates an ECDSA key pair locally and sends a Certificate Signing Request (CSR) to the ATK Certificate Authority.
3. ATK validates and digitally signs the certificate; the utility retrieves it and lets the operator export private-key.pem and signed-certificate.pem.
4. The private key never leaves the POS machine and is configured for this software via the PRIVATE_KEY environment variable (or a local dummy-private-key.pem for local testing only).

3.2 Fiscalization flow (every sale)

sequenceDiagram
    participant POS as SEF (POS/ERP system)
    participant Lib as This software (fiskalizimi/*)
    participant ATK as ATK Fiscalization Service
    participant App as ATK Citizen Mobile App

    POS->>Lib: Sale data (items, payments, tax groups, totals)
    Lib->>Lib: Build PosCoupon + CitizenCoupon (Protobuf)
    Lib->>Lib: Serialize -> Base64 -> SHA-256 hash -> ECDSA sign (private key)
    Lib->>ATK: POST /pos/coupon (Base64 details + signature)
    ATK-->>Lib: HTTP 200 / acknowledgement
    Lib-->>POS: QR string = Base64(CitizenCoupon) + "|" + Base64(signature)
    POS->>POS: Print receipt with embedded QR code
    App->>App: Customer scans printed QR code
    App->>ATK: POST /citizen/coupon (same QR payload)
    ATK->>ATK: Verify signature & reconcile totals against stored POS Coupon
    ATK-->>App: Verified / Failed verification
        

Key points of the integration:

• Transport: HTTPS REST calls (via guzzlehttp/guzzle) to ATK's fiscalization endpoints — https://fiskalizimi.atk-ks.org/pos/coupon and https://fiskalizimi.atk-ks.org/citizen/coupon.
• Data format on the wire: Protocol Buffers binary payload, Base64-encoded, accompanied by an ECDSA/SHA-256 Base64 signature.
• Trust model: PKI — each POS has its own private key (never transmitted) and an ATK-issued certificate; ATK verifies the signature using the public key associated with that POS/business.
• Consistency requirement: the totals and tax groups on the POS Coupon (sent automatically at checkout) must exactly match those on the Citizen Coupon (encoded in the printed QR code); otherwise ATK marks the receipt as FAILED VERIFICATION.
• Local integration point for an ERP/POS: an ERP only needs to supply sale data as a JSON/array payload to CouponFactory/FiscalizationService (or to the bundled public/api.php HTTP endpoint used by the test console), without needing to understand Protobuf or cryptography directly.

3.3 Centralized Multi-Tenant Deployment (fiscalization.starsoft.app)

In production, this software will not be installed and operated separately by each client. Instead, a single instance will be deployed and centrally operated at https://fiscalization.starsoft.app, exposed as an API that all client ERP/POS applications can call, regardless of the ERP vendor or technology stack:

flowchart LR
    ERP1[Client ERP / App 1] -->|API data - JSON| Central
    ERP2[Client ERP / App 2] -->|API data - JSON| Central
    ERP3[Client ERP / App N] -->|API data - JSON| Central
    Central[["Centralized fiskalizimi service<br/>fiscalization.starsoft.app"]] -->|Signed POS Coupon| ATK[ATK Fiscalization Service]
    Central -->|QR code string + result| ERP1
    Central -->|QR code string + result| ERP2
    Central -->|QR code string + result| ERP3
        

How responsibilities are split:

• Client ERP/POS applications only need to capture the sale (items, tax rates, payments, and their business/POS identifiers) and call the centralized API with that data, in the same API/JSON format accepted by this project's public/api.php (Citizen Coupon / POS Coupon payloads). They do not need to implement Protobuf serialization, ECDSA signing, or PKI key storage themselves.
• The centralized service (fiscalization.starsoft.app) receives each API request, identifies the calling business/POS, loads that business' own onboarded private key/certificate, builds and signs the corresponding POS/Citizen coupons, submits the POS Coupon to ATK, and returns the QR code string (and the ATK response) back to the calling ERP so it can be printed on the receipt.
• Per-client key isolation: even though the service is centralized and multi-tenant, each onboarded business/POS keeps its own distinct ECDSA key/certificate pair; the centralized service selects the correct key per request — it does not share one key across clients.

This model lets any number of ERP/POS applications integrate with ATK's fiscalization system through one simple, uniform API, without each of them having to separately implement or maintain the Protobuf/PKI/signing logic described above.

• Language / runtime: PHP 7.4+/8.x (ext-openssl for cryptography).
• Dependency management: Composer (composer.json, PSR-4 autoloading).
• Data serialization: Protocol Buffers (google/protobuf Composer package) — schema defined in models.proto, generated PHP classes in Atk/ and GPBMetadata/.
• Cryptography / digital signatures: PHP's built-in OpenSSL extension, ECDSA key pairs, SHA-256 hashing (openssl_sign / openssl_pkey_get_private).
• HTTP client: GuzzleHTTP (guzzlehttp/guzzle), built on PSR-7 (psr/http-message), PSR-18 (psr/http-client) and PSR-17 (psr/http-factory).
• PKI onboarding tool: standalone cross-platform executable (onboarder-windows.zip, onboarder-macos.zip, onboarder-linux.zip) for key-pair generation and ATK certificate enrollment.
• Front-end test console: plain HTML5, CSS3, and vanilla JavaScript (ES6+) using the Fetch API — no build step or framework required (public/index.html, public/pos-sale.html, public/manual.html, app.js, pos-sale.js, i18n.js, style.css).
• QR code rendering: client-side qrcode JavaScript library (loaded via CDN) for rendering a scannable QR image from the signed Citizen Coupon string.
• Localization: custom lightweight i18n implementation (i18n.js) supporting English (en) and Albanian (sq).
• Back-end API: a minimal PHP endpoint (public/api.php) exposing the build/sign/send flow over JSON for the browser-based test console.
• Hosting / deployment model: centralized, multi-tenant fiscalization API service hosted at https://fiscalization.starsoft.app, accepting sale data (API/JSON format) from multiple client ERP/POS applications and performing the build/sign/submit-to-ATK flow on their behalf.
• Version control / distribution: Git / GitHub.