Integrimi i Sistemeve ERP Vendore (Pantheon, Bilanci, Navision) me E-Commerce dhe Next.js 16: Sinkronizimi i Stokut në Kohë Reale, Faturimi Fiskal dhe Arkitektura e Sigurt me Webhooks

Në ekosistemin e tregtisë elektronike dhe distribucionit në Kosovë, Shqipëri dhe Ballkanin Perëndimor, shumica dërrmuese e ndërmarrjeve të mesme dhe të mëdha mbështeten në sisteme tradicionale ERP (Enterprise Resource Planning) si Datalab Pantheon, Bilanci Cloud / Desktop, Microsoft Dynamics NAV / Business Central, apo Alpha Accounting. Këto sisteme përbëjnë zemrën operative të kompanisë: menaxhimin e magazinave të shumëfishta, kontabilitetin, faturimin fiskal dhe marrëdhëniet me furnitorët.

Megjithatë, kur bizneset vendosin të zgjerohen online me një platformë moderne e-commerce apo portal B2B, përballen me një mur inxhinierik: si të sinkronizohet stoku në kohë reale, si të shmangen shitjet e dyfishta (overselling), dhe si të automatizohet faturimi pa ndërhyrje manuale të stafit?

Praktika e vjetëruar e eksport-importit manual me skedarë Excel/CSV ose skripteve të ngadalta periodike (cron jobs çdo 4 orë) shkakton gabime të vazhdueshme inventari, vonesa në dërgesa dhe pakënaqësi te blerësit.

Në këtë udhëzues teknik, Ekipi i Postieri XYZ L.L.C. shpalos arkitekturën e plotë të një ERP Sync Gateway modern, të ndërtuar me Next.js 16, PostgreSQL, Redis Queues dhe Webhooks me nënshkrim kriptografik HMAC, duke mundësuar sinkronizim sub-sekondar midis magazinave fizike dhe dyqanit dixhital.

---

1. Topologjia e Arkitekturës: Event-Driven ERP Integration Gateway

Integrimi i drejtpërdrejtë i uebsajtit me bazën e të dhënave të ERP-së lokale (p.sh. SQL Server i Pantheon brenda zyrës) paraqet rreziqe madhore sigurie dhe performancë të dobët. Zgjidhja profesionale është ndërtimi i një Gateway të ndërmjetëm të izoluar:

┌──────────────────────────────────────────────────────────────────────────┐
│                      ARKITEKTURA E INTEGRIMIT ERP                        │
│                     (Postieri XYZ Enterprise Stack)                      │
└──────────────────────────────────────────────────────────────────────────┘
                                      │
     ┌────────────────────────────────┴────────────────────────────────┐
     ▼                                                                 ▼
┌─────────────────────────┐                               ┌─────────────────────────┐
│   Dyqani Online B2C/B2B │                               │  POS & Magazina Fizike  │
│   (Next.js 16 App)      │                               │  (Pantheon / Bilanci)   │
└────────────┬────────────┘                               └────────────┬────────────┘
             │                                                         │
             │ [Porosi e Re / Checkout]                                │ [Ndryshim Stoku / Faturë]
             ▼                                                         ▼
┌─────────────────────────┐                               ┌─────────────────────────┐
│ Next.js Server Action   │                               │ Local ERP Agent / Tunnel│
│ + PostgreSQL Mutex Lock │                               │ (Cloudflare Zero Trust) │
└────────────┬────────────┘                               └────────────┬────────────┘
             │                                                         │
             │ [Webhook Event: order.created]                          │ [Webhook: stock.delta]
             ▼                                                         ▼
┌───────────────────────────────────────────────────────────────────────────────────┐
│                    ENTERPRISE EVENT BUS & QUEUE (Redis / BullMQ)                  │
│                                                                                   │
│   ┌──────────────────────────────┐       ┌────────────────────────────────────┐   │
│   │   Stock Reconciliation Job   │       │   Fiscal Invoice Generation Job    │   │
│   └──────────────┬───────────────┘       └─────────────────┬──────────────────┘   │
└──────────────────┼─────────────────────────────────────────┼──────────────────────┘
                   │                                         │
                   ▼                                         ▼
┌──────────────────────────────────────┐  ┌─────────────────────────────────────────┐
│   Sinkronizim i Stokut (PostgreSQL)  │  │  Administrata Tatimore / ATK API        │
│   Latenca: < 80ms                    │  │  Gjenerimi i QR Kodit Fiskal & PDF      │
└──────────────────────────────────────┘  └─────────────────────────────────────────┘

Parimet Kryesore të Kësaj Topologjie:

1. Zero Trust & Izolimi i Rrjetit: ERP-ja lokale në zyrë/depo nuk hap asnjë portë publike (no open port 1433/3306). Lidhja bëhet përmes një Cloudflare Tunnel të enkriptuar TLS 1.3 me autentikim mTLS ose token të rrotullueshëm.
2. Përpunim Asinkron me Radhë (Queue-Driven): Asnjë dështim i rrjetit të depos nuk bllokon blerësin në ueb. Nëse serveri lokal i ERP-së bie për disa minuta, radha e mesazheve (Message Queue) ruan transaksionet dhe i ri-ekzekuton automatikisht sapo lidhja të rikthehet.
3. Idempotencë Absolute: Çdo ngjarje (event) shoqërohet me një idempotency_key unik (UUIDv7) për të garantuar që asnjë zbritje stoku apo faturë të mos regjistrohet dy herë.

---

2. Parandalimi i Shitjeve të Dyfishta: Atomic Stock Locks në PostgreSQL

Problemi më i madh në tregtinë me shumë kanale (omnichannel) ndodh kur kanë mbetur vetëm 2 njësi të një artikulli në stok dhe shiten njëkohësisht në arkën fizike dhe në uebsajt.

Në Next.js 16 dhe PostgreSQL, përdorim Bllokim Atomik në nivel rreshti (SELECT FOR UPDATE) me kontroll të menjëhershëm të disponueshmërisë:

sql
-- Funksion i Sigurt për Rezervimin e Stokut me Garanci Konkurruese
CREATE OR REPLACE FUNCTION public.reserve_product_stock(
    p_product_id UUID,
    p_quantity_requested INT,
    p_order_id UUID,
    p_idempotency_key VARCHAR(64)
)
RETURNS TABLE (
    success BOOLEAN,
    remaining_stock INT,
    message TEXT
) 
LANGUAGE plpgsql
AS $$
DECLARE
    v_current_stock INT;
    v_already_processed BOOLEAN;
BEGIN
    -- 1. Kontrollojmë nëse ky transaksion është ekzekutuar më parë (Idempotency Check)
    SELECT EXISTS (
        SELECT 1 FROM public.stock_transactions 
        WHERE idempotency_key = p_idempotency_key
    ) INTO v_already_processed;

    IF v_already_processed THEN
        RETURN QUERY SELECT true, 0, 'Transaction already processed (Idempotent).';
        RETURN;
    END IF;

    -- 2. Bllokojmë rreshtin e produktit ekskluzivisht për këtë transaksion
    SELECT stock_quantity INTO v_current_stock
    FROM public.products
    WHERE id = p_product_id
    FOR UPDATE;

    -- Kontrollojmë ekzistencën e produktit
    IF NOT FOUND THEN
        RETURN QUERY SELECT false, 0, 'Product not found.';
        RETURN;
    END IF;

    -- 3. Verifikojmë disponueshmërinë e sasisë
    IF v_current_stock < p_quantity_requested THEN
        RETURN QUERY SELECT false, v_current_stock, 'Insufficient stock quantity.';
        RETURN;
    END IF;

    -- 4. Zbresim stokun dhe regjistrojmë audimin e plotë
    UPDATE public.products
    SET stock_quantity = stock_quantity - p_quantity_requested,
        updated_at = NOW()
    WHERE id = p_product_id;

    INSERT INTO public.stock_transactions (
        product_id, order_id, quantity_change, 
        idempotency_key, created_at
    ) VALUES (
        p_product_id, p_order_id, -p_quantity_requested, 
        p_idempotency_key, NOW()
    );

    RETURN QUERY SELECT true, (v_current_stock - p_quantity_requested), 'Stock reserved successfully.';
END;
$$;

---

3. Implementimi i Webhook Endpoint-it me Validim HMAC-SHA256 në Next.js 16

Kur sistemi ERP vendor përditëson stokun e një artikulli (p.sh. pas pranimit të një furnizimi të ri në magazinë), dërgon një sinjal webhook te platforma Next.js 16. Siguria garantohet me verifikimin e nënshkrimit kriptografik:

typescript
// app/api/erp/webhooks/stock-update/route.ts
import { NextRequest, NextResponse } from "next/server";
import crypto from "crypto";
import { getDbPool } from "@/lib/db";
import { z } from "zod";

const ERP_WEBHOOK_SECRET = process.env.ERP_WEBHOOK_SECRET || "postieri-erp-sync-secret-key-2026";

// Skema e verifikimit të payload-it nga ERP
const StockUpdateSchema = z.object({
  eventId: z.string().uuid(),
  timestamp: z.number(),
  warehouseCode: z.string().min(1),
  items: z.array(
    z.object({
      sku: z.string().min(1),
      barcode: z.string().optional(),
      newPhysicalQuantity: z.number().int().min(0),
      sellingPrice: z.number().positive().optional(),
      vatRate: z.number().min(0).max(100).default(18),
    })
  ),
});

export async function POST(req: NextRequest) {
  try {
    const rawBody = await req.text();
    const signature = req.headers.get("x-erp-signature");
    const timestamp = req.headers.get("x-erp-timestamp");

    // 1. Verifikimi i Nënshkrimit Kriptografik (HMAC-SHA256)
    if (!signature || !timestamp) {
      return NextResponse.json({ error: "Missing cryptographic headers" }, { status: 401 });
    }

    // Parandalimi i sulmeve replay (max 5 minuta diferencë kohore)
    const currentTime = Math.floor(Date.now() / 1000);
    if (Math.abs(currentTime - parseInt(timestamp, 10)) > 300) {
      return NextResponse.json({ error: "Timestamp tolerance exceeded" }, { status: 400 });
    }

    const expectedSignature = crypto
      .createHmac("sha256", ERP_WEBHOOK_SECRET)
      .update(`${timestamp}.${rawBody}`)
      .digest("hex");

    if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSignature))) {
      return NextResponse.json({ error: "Invalid signature" }, { status: 403 });
    }

    // 2. Validimi i të Dhënave
    const parsedData = StockUpdateSchema.parse(JSON.parse(rawBody));
    const pool = getDbPool();

    // 3. Përditësimi Transaksional në PostgreSQL
    const client = await pool.connect();
    try {
      await client.query("BEGIN");

      for (const item of parsedData.items) {
        await client.query(
          `
          UPDATE public.products 
          SET stock_quantity = $1,
              price = COALESCE($2, price),
              updated_at = NOW()
          WHERE sku = $3;
          `,
          [item.newPhysicalQuantity, item.sellingPrice || null, item.sku]
        );
      }

      await client.query("COMMIT");
    } catch (dbError) {
      await client.query("ROLLBACK");
      throw dbError;
    } finally {
      client.release();
    }

    return NextResponse.json({
      success: true,
      processedItems: parsedData.items.length,
      eventId: parsedData.eventId,
    });
  } catch (error: any) {
    console.error("[ERP Webhook Ingestion Error]:", error);
    return NextResponse.json(
      { success: false, error: error?.message || "Internal ingestion error" },
      { status: 500 }
    );
  }
}

---

4. Automatizimi i Faturimit Fiskal dhe Integrimi me Administratën Tatimore të Kosovës (ATK)

Në tregun e Kosovës dhe Shqipërisë, çdo transaksion online me pagesë me kartë bankare apo Cash on Delivery duhet të fiskalizohet sipas ligjit në fuqi.

Në vend që stafi i kontabilitetit të shtypë kuponë fiskalë manualisht në arkë në fund të ditës, arkitektura jonë realizon Fiskalizim të Menjëhershëm Asinkron:

1. Gjenerimi i XML/JSON Fiskal: Sapo porosia konfirmohet në Next.js, krijohet struktura fiskale me NUI, numrin e faturës, normën e TVSH-së (8% ose 18%) dhe artikujt e zbërthyer.
2. Nënshkrimi me Çertifikatë Dixhitale: Fatura nënshkruhet me çelësin privat të biznesit dhe dërgohet te serverët e ATK-së / ERP fiskalizimit.
3. Gjenerimi i QR Kodit & Dërgimi me Email/WhatsApp: Sistemi merr përgjigjen me kodin unik të sigurisë (NSLF/NIVF), krijon PDF-në e faturës zyrtare dhe ia dërgon blerësit automatikisht brenda 3 sekondave.

typescript
// Shërbimi i Gjenerimit të Faturës Fiskale
export async function dispatchFiscalInvoice(orderData: {
  orderId: string;
  customerNui?: string;
  totalEur: number;
  vatEur: number;
  items: Array<{ name: string; qty: number; unitPrice: number; vatPercent: number }>;
}) {
  const payload = {
    header: {
      docType: "INVOICE",
      currency: "EUR",
      issueDateTime: new Date().toISOString(),
      operatorCode: "OP_POSTIERI_ONLINE",
    },
    buyer: {
      nui: orderData.customerNui || "999999999", // NUI konsumatori ose biznesi
    },
    items: orderData.items.map((i) => ({
      description: i.name,
      quantity: i.qty,
      unitPriceNet: (i.unitPrice / (1 + i.vatPercent / 100)).toFixed(4),
      vatRate: i.vatPercent,
      totalGross: (i.qty * i.unitPrice).toFixed(2),
    })),
  };

  // Dërgimi te mikrosherbimi i fiskalizimit ERP
  const res = await fetch(process.env.ERP_FISCAL_SERVICE_URL!, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${process.env.ERP_FISCAL_API_KEY}`,
    },
    body: JSON.stringify(payload),
  });

  return await res.json();
}

---

5. Krahasimi i Qasjeve të Integrimit: Polling vs. Direct DB vs. Event-Driven Gateway

---

6. Hapat Praktikë për Zbatimin në Biznesin Tuaj

Për të ndërtuar një lidhje të suksesshme midis ERP-së tuaj dhe dyqanit dixhital:

1. Pastroni dhe Unifikoni Barkodet & SKU: Sigurohuni që çdo variant produkti (madhësia, ngjyra) të ketë një kod unik në ERP që përputhet saktësisht me platformën e-commerce.
2. Përcaktoni Magazinat Burimore: Nëse keni disa depo (p.sh. Magazina Qendrore në Prishtinë dhe Dyqani në Prizren), konfiguroni logjikën se cili stok konsiderohet i disponueshëm për shitje online.
3. Vendosni Pragun e Sigurisë së Stokut (Safety Buffer): Për produktet me xhiro të shpejtë, lini një rezervë prej 1–2 copë përpara se të shënohen si "Jashtë Stokut" në ueb.
4. Testoni Ndërprerjet e Rrjetit: Sigurohuni që kur linja e internetit në magazinë të shkëputet, radha e mesazheve të ruajë të gjitha porositë dhe t'i procesojë pa humbje sapo rrjeti të rikthehet.

---

Përfundim

Integrimi modern i ERP-ve nuk është thjesht një lehtësim teknik — është themeli që i lejon ndërmarrjet në Kosovë dhe rajon të shkallëzojnë shitjet online nga dhjetëra në mijëra porosi ditore pa shtuar kosto administrative.

Duke kombinuar shpejtësinë e Next.js 16, arkitekturën e sigurt të Cloudflare Zero Trust dhe transaksionet e pathyeshme të PostgreSQL, ekipi ynë ndërton ura të qëndrueshme midis operacioneve tuaja tradicionale dhe tregut global.

Dëshironi të sinkronizoni sistemin tuaj Pantheon, Bilanci ose Navision me platformën tuaj të re e-commerce? Kontaktoni inxhinierët e Postieri XYZ L.L.C. për një vlerësim teknik të infrastrukturës suaj.