Arkitektura e Faturimit Elektronik dhe Fiskalizimit me ATK: Integrimi i API-ve Fiskale në Next.js 16 dhe PostgreSQL

Transformimi digjital i ekonomisë në Kosovë po hyn në një fazë vendimtare. Për vite me radhë, tregtia elektronike (e-commerce), platformat SaaS dhe ndërmarrjet vendore kanë operuar nën barrën e një sistemi të fragmentuar fiskal: arka fizike fiskale të lidhura me kabllo serike ose RS-232, operatorë manualë që ri-shtypnin faturat e porosive të uebit, dhe mungesë e plotë e sinkronizimit në kohë reale me sistemet ERP.

Me avancimin e kërkesave nga Administrata Tatimore e Kosovës (ATK) dhe standardizimin e faturimit elektronik (e-Invoicing), kërkesa për sisteme automatike, të integruara direkt në kodin e aplikacionit, është kthyer në prioritet parësor infrastrukturor.

Në këtë analizë të thellë teknike, Ekipi i Postieri XYZ L.L.C. paraqet arkitekturën inxhinierike të provuar në prodhim për integrimin e drejtpërdrejtë të faturimit elektronik dhe fiskalizimit me Next.js 16, PostgreSQL dhe shërbimet e API-ve fiskale, duke garantuar transaksione idempotente, zero humbje faturash dhe përputhshmëri të plotë ligjore.

---

1. Pse Metodat Tradicionale Dështojnë në E-Commerce & SaaS?

Modeli i vjetër i fiskalizimit fizik nuk është projektuar për dinamikën e uebit modern:

• Bllokimi Gjatë Flukseve (Concurrency Bottlenecks): Një arkë fizike përpunon faturat në mënyrë sekuenciale me shpejtësi printimi 1-3 sekonda për faturë. Nëse dyqani juaj përballet me qindra porosi njëkohësisht (p.sh. gjatë fushatave Black Friday ose zbritjeve sezonale), radha bllokohet dhe pagesat dështojnë.
• Mungesa e Idempotencës: Në rast se lidhja me internetin ndërpritet gjatë transmetimit, rrezikohet printimi i dyfishtë i faturës tatimore ose, akoma më keq, lëshimi i pagesës në Stripe/NestPay pa u regjistruar në ATK.
• Struktura e Ndërlikuar Tatimore (TVSH): Në Kosovë zbatohen norma të diferencuara tatimore: 18% (norma standarde), 8% (norma e reduktuar për artikuj esencialë, hoteleri dhe ushqim), dhe 0% (për eksport shërbimesh digjitale apo donacione). Çdo gabim në ndarjen e bazës tatimore sjell mospërputhje në librat e blerjes/shitjes.

Zgjidhja moderne kërkon Fiskalizim Asinkron të Bazuar në Ngjarje (Event-Driven Fiscal Architecture).

---

2. Topologjia e Arkitekturës: Nga Shporta te ATK

Për të ndarë ciklin kritik të pagesës nga komunikimi me sistemet fiskale (të cilat mund të kenë vonesa rrjeti), ne përdorim modelin Transactional Outbox në PostgreSQL:

┌────────────────────────────────────────────────────────┐
│             Klienti (Browser / Mobile App)             │
└───────────────────────────┬────────────────────────────┘
                            │ 1. Checkout (Server Action)
                            ▼
┌────────────────────────────────────────────────────────┐
│           Next.js 16 (App Router / Node.js)           │
│                                                        │
│  ┌───────────────────────┐    ┌─────────────────────┐  │
│  │   Pagesa (Stripe /    │    │  Krijimi i Porosisë │  │
│  │   NestPay BKT/TEB)    │───►│  & Outbox Event     │  │
│  └───────────────────────┘    └──────────┬──────────┘  │
└──────────────────────────────────────────┼─────────────┘
                                           │ 2. ACID Transaction
                                           ▼
┌────────────────────────────────────────────────────────┐
│             PostgreSQL (Baza e të Dhënave)            │
│                                                        │
│  ┌───────────────────────┐    ┌─────────────────────┐  │
│  │     Tabela orders     │    │ Tabela fiscal_outbox│  │
│  └───────────────────────┘    └──────────┬──────────┘  │
└──────────────────────────────────────────┼─────────────┘
                                           │ 3. Poll / LISTEN
                                           ▼
┌────────────────────────────────────────────────────────┐
│           Fiscal Worker Daemon (Hermes / Node)         │
│                                                        │
│  - Gjeneron XML/JSON Payload me TVSH 18% / 8% / 0%     │
│  - Llogarit Nënshkrimin Kriptografik (SHA-256)         │
│  - Gjeneron QR Kodin e Verifikimit Tatimor             │
└───────────────────────────┬────────────────────────────┘
                            │ 4. Thirrje e Sigurt TLS 1.3
                            ▼
┌────────────────────────────────────────────────────────┐
│      Serveri Fiskal i Autorizuar / API Gateway ATK     │
└────────────────────────────────────────────────────────┘

Hapat Kryesorë të Fluksit:

1. Pagesa dhe Regjistrimi në Një Transaksion: Kur klienti konfirmon pagesën, porosia dhe regjistri fiskal i pritshëm ruhen në të njëjtin transaksion PostgreSQL (BEGIN ... COMMIT). Nëse diçka dështon, anulohet e gjithë porosia.
2. Përpunimi Asinkron i Pavarur: Një proces punues në sfond (worker) merr detyrën nga fiscal_outbox, përgatit faturën dhe komunikon me shërbimin fiskal.
3. Pavarësia e Shpejtësisë së Uebit: Blerësi merr konfirmimin e menjëhershëm në ekran nën 200ms, ndërsa fatura fiskale zyrtare me numër fiskal dhe QR kod gjenerohet dhe i dërgohet me email brenda pak sekondave.

---

3. Skema e PostgreSQL me Idempotencë dhe Audit Trail

Baza e të dhënave duhet të parandalojë me rigorozitet çdo regjistrim të dyfishtë përmes idempotency_key unik:

sql
-- Tabela e transaksioneve fiskale të ndërlidhura me ATK
CREATE TABLE public.fiscal_invoices (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    order_id UUID NOT NULL REFERENCES public.orders(id) ON DELETE RESTRICT,
    idempotency_key VARCHAR(128) NOT NULL UNIQUE,
    invoice_number VARCHAR(64) UNIQUE,
    fiscal_receipt_number VARCHAR(64),
    tax_base_standard NUMERIC(12, 2) NOT NULL DEFAULT 0.00, -- 18% TVSH
    tax_amount_standard NUMERIC(12, 2) NOT NULL DEFAULT 0.00,
    tax_base_reduced NUMERIC(12, 2) NOT NULL DEFAULT 0.00,  -- 8% TVSH
    tax_amount_reduced NUMERIC(12, 2) NOT NULL DEFAULT 0.00,
    tax_exempt_amount NUMERIC(12, 2) NOT NULL DEFAULT 0.00, -- 0% TVSH
    total_amount NUMERIC(12, 2) NOT NULL,
    fiscal_verification_url TEXT,
    qr_code_data TEXT,
    status VARCHAR(32) NOT NULL DEFAULT 'PENDING', -- PENDING, COMPLETED, FAILED, RETRYING
    error_message TEXT,
    attempts INT NOT NULL DEFAULT 0,
    last_attempt_at TIMESTAMPTZ,
    completed_at TIMESTAMPTZ,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

-- Indeksi për kërkim të shpejtë të faturave në pritje
CREATE INDEX idx_fiscal_invoices_status ON public.fiscal_invoices(status) WHERE status IN ('PENDING', 'RETRYING');
CREATE INDEX idx_fiscal_invoices_order ON public.fiscal_invoices(order_id);

---

4. Implementimi në Next.js 16: Përgatitja dhe Nënshkrimi i Faturës

Në Next.js 16, përdorim TypeScript për të modeluar llogaritjen precize të taksave pa gabime rrumbullakimi (duke përdorur numra të plotë centesh ose biblioteka precize si dinero.js / decimal.js).

Ja moduli i përgatitjes së faturës fiskale:

typescript
// lib/fiscal/fiscal-builder.ts
import crypto from "crypto";

export interface FiscalItem {
  name: string;
  quantity: number;
  unitPriceEur: number;
  vatRate: 0.18 | 0.08 | 0.00;
}

export interface FiscalInvoicePayload {
  orderId: string;
  customerNui?: string; // NUI / Numri Fiskal i blerësit B2B
  customerName: string;
  items: Array<{
    description: string;
    qty: number;
    price: number;
    vatRatePercent: number;
    total: number;
  }>;
  taxSummary: {
    base18: number;
    vat18: number;
    base8: number;
    vat8: number;
    exempt0: number;
    grandTotal: number;
  };
  signatureSha256: string;
}

export function buildFiscalPayload(
  orderId: string,
  customerName: string,
  items: FiscalItem[],
  privateSigningKey: string,
  customerNui?: string
): FiscalInvoicePayload {
  let base18 = 0, vat18 = 0;
  let base8 = 0, vat8 = 0;
  let exempt0 = 0;
  let grandTotal = 0;

  const formattedItems = items.map((item) => {
    const itemTotal = Math.round(item.quantity * item.unitPriceEur * 100) / 100;
    grandTotal += itemTotal;

    if (item.vatRate === 0.18) {
      const base = Math.round((itemTotal / 1.18) * 100) / 100;
      base18 += base;
      vat18 += itemTotal - base;
    } else if (item.vatRate === 0.08) {
      const base = Math.round((itemTotal / 1.08) * 100) / 100;
      base8 += base;
      vat8 += itemTotal - base;
    } else {
      exempt0 += itemTotal;
    }

    return {
      description: item.name.substring(0, 50),
      qty: item.quantity,
      price: item.unitPriceEur,
      vatRatePercent: item.vatRate * 100,
      total: itemTotal,
    };
  });

  // Gjenerimi i nënshkrimit dixhital me çelësin privat të certifikatës
  const signString = `${orderId}|${grandTotal.toFixed(2)}|${customerNui || "B2C"}|${Date.now()}`;
  const signer = crypto.createHmac("sha256", privateSigningKey);
  signer.update(signString);
  const signatureSha256 = signer.digest("hex");

  return {
    orderId,
    customerNui,
    customerName,
    items: formattedItems,
    taxSummary: {
      base18: Math.round(base18 * 100) / 100,
      vat18: Math.round(vat18 * 100) / 100,
      base8: Math.round(base8 * 100) / 100,
      vat8: Math.round(vat8 * 100) / 100,
      exempt0: Math.round(exempt0 * 100) / 100,
      grandTotal: Math.round(grandTotal * 100) / 100,
    },
    signatureSha256,
  };
}

---

5. Gjenerimi i QR Kodit dhe Verifikimi Zyrtar

Një nga shtyllat kryesore të faturimit të ri elektronik është prania e një QR Kodi unik në çdo faturë PDF ose letër. Ky kod lejon blerësin dhe inspektorin tatimor të skanojnë me telefon dhe të verifikojnë menjëherë autenticitetin e kuponit në serverët qendrorë të ATK.

Shembull i gjenerimit të të dhënave për QR kodin në Node.js:

typescript
// lib/fiscal/qr-generator.ts
import QRCode from "qrcode";

export async function generateFiscalQR(
  verificationUrl: string,
  receiptNumber: string,
  total: number,
  fiscalDate: Date
): Promise<string> {
  // Formati i unifikuar i verifikimit tatimor
  const qrPayload = JSON.stringify({
    url: verificationUrl,
    rec: receiptNumber,
    tot: total.toFixed(2),
    dt: fiscalDate.toISOString(),
  });

  // Gjeneron Data URL (Base64 PNG) gati për printim ose PDF
  return await QRCode.toDataURL(qrPayload, {
    errorCorrectionLevel: "M",
    margin: 2,
    width: 256,
    color: {
      dark: "#0a0a0a",
      light: "#ffffff",
    },
  });
}

---

6. Trajtimi i Gabimeve: Strategjia Exponential Backoff dhe Dead Letter Queue

Asnjë sistem i jashtëm tatimor nuk ka 100% disponueshmëri. Çfarë ndodh kur serveri fiskal vonohet ose përgjigjet me kod 503 Service Unavailable?

Në arkitekturën e Postieri XYZ, përdoret një strategji me 3 nivele mbrojtjeje:

1. Rithirrje Eksponenciale (Exponential Backoff): Në dështimin e parë, ri-provo pas 5 sekondash; nëse dështon sërish, pas 30 sekondash, 2 minutash dhe 10 minutash.
2. Circuit Breaker: Nëse 5 kërkesa radhazi dështojnë, sistemi kalon në gjendje OPEN (offline mode) dhe ruan ngjarjet në radhë lokale pa mbingarkuar rrjetin e jashtëm.
3. Dead Letter Queue (DLQ): Pas 5 tentativash të pasuksesshme, fatura merr statusin FAILED dhe dërgon një sinjalizim të menjëhershëm në kanalin administrativ të inxhinierëve (Discord / Telegram) me të dhënat e plota të porosisë për zgjidhje me një klikim.

---

7. Përmbledhje dhe Rekomandime Praktike për Bizneset në Kosovë

Zbatimi i duhur i faturimit elektronik dhe fiskalizimit automatik sjell përfitime të jashtëzakonshme:

• Efikasitet 100% Automatik: Eliminon shpenzimin e qindra orëve manuale nga stafi i arkës dhe kontabilitetit.
• Përputhshmëri e Sigurt me ATK: Çdo faturë llogaritet saktë sipas normave tatimore 18%, 8% dhe 0%, duke evituar gjobat dhe diskrepancat në deklarimet mujore.
• Përvojë Moderne për Blerësin: Klienti merr faturën digjitale menjëherë në email me QR kod të verifikueshëm dhe dizajn profesional.
• Skalueshmëri e Pafundme: Sistemi përballon mijëra porosi në sekondë pa rënë dhe pa bllokuar arkën e dyqanit fizik.

Për ndërmarrjet që kërkojnë të modernizojnë platformat e tyre ekzistuese të tregtisë elektronike ose të ndërtojnë një infrastrukturë të personalizuar SaaS me faturim të integruar, Postieri XYZ L.L.C. ofron konsulencë inxhinierike, auditim të thellë të arkitekturës dhe implementim të plotë sipas kërkesave ligjore të Republikës së Kosovës.