SISL Optima Connector — known issues

v0.3.5 status — what works, what doesn't, why

We update this list at every release. Updated May 12, 2026 (v0.3.5). Polish version: wersja polska.

Working in production (verified on a real Optima 2024 instance)

• Product sync Optima → Magento — code, name, EAN, unit, price from selected pricelist.
• Multi-warehouse stock → Magento MSI — Optima warehouses mapped to MSI sources.
• Per-website pricing — different prices for `retail.shop` vs `b2b.shop` from a single Optima.
• Auto-invoices (Optima → Magento Invoice) — operator issues FA with description `MG-100000123`, Magento creates the matching Invoice with correct qty. Partial documents supported (1 of 5 units → 1 in Magento, not 5).
• Customer sync (KntKarty → customer_entity) — Optima contractors upsert by email + websiteId.
• HMAC-SHA256 + Ed25519 + anti-tamper manifest — secure Magento ↔ .NET, signed licence verification.
• Cron locks — concurrent crons don't race on cursor.

⛔ NOT working in v0.3.5 (TBD v0.4.0 — June 2026)

• Order forward Magento → Optima — Magento sends the payload correctly, but OptimaSqlClient.ForwardOrderAsync is a stub on the .NET side. Magento orders do not auto-create invoices in Optima. v0.4.0 plan: XML drop folder + operator clicks "Import documents from XML" in Optima. Admin toggle sync/orders_enabled defaults off to avoid misleading users.
• VAT mismatch — Magento recalculates tax with its own rules, ignores Optima totals. Can produce sub-grosz differences between Magento Invoice and Optima FA. v0.4.0 plan: override total fields post-prepareInvoice() with net/vat/gross returned by .NET.
• No credit memos / FK/WZK — Optima correcting invoices aren't mirrored as Magento Credit Memos. v0.5.0 plan: doc-type recognition + Credit Memo creation.
• Full shipping cost on first partial invoice — Magento adds the full shipping cost to the first invoice regardless of its size. v0.4.0 plan (with VAT parity).

⚠️ Known limitations (workaround available)

• Edit-idempotency for Optima documents — if an operator edits a confirmed Optima document (changes description), its TrN_TS_Mod changes and F2 sees it again → tries to create a second Magento Invoice for the same Optima doc.
  Workaround: don't edit confirmed Optima documents.
  Roadmap v0.4.0/v0.5.0: mapping table optima_doc_id ↔ magento_invoice_id.
• Timezone CET vs UTC drift at DST — Optima stores datetime without offset, .NET uses UTC; documents may be lost or duplicated by ±1h on DST nights (March + October).
  Workaround: don't issue invoices 02:00-03:00 on DST nights (twice a year).
  Roadmap v0.3.6: AT TIME ZONE in SQL + TZ config in appsettings.
• Unstable licence hostname on k8s/Docker Swarm — Dns.GetHostName() returns the random container hostname; every restart invalidates the licence.
  Workaround: deploy .NET service on a single VPS with a fixed hostname (most common setup).
  Roadmap v0.3.6: Sisl:License:CanonicalHost in appsettings.
• Configurable / bundle / grouped Magento products — Optima only knows simple SKUs; ProductSync skips non-simple types with a warning, doesn't reshape parent-child structure.
  Workaround: in Optima use simple SKUs that match simple Magento products; build configurable parents manually in Magento.

Fixed in 3 rounds of code review before release (24 bugs)

Full changelog of every release with type tags (NEW / FIX / SECURITY / BREAKING) → /en/sisl-optima/changelog. Plans for v0.4.0 and beyond → /en/sisl-optima/roadmap. Best-of fixes before v0.3.5:

• v0.3.1 #1: F1 multi-store silent no-op when catalog/price/scope=Global — now hard-fails with a clear error pointing to the admin setting.
• v0.3.1 #5: F3 schema referenced Knt_TS_Mod which doesn't exist on a real Optima 2024 — rewritten to full-sync (KntKarty has no datetime column).
• v0.3.1 #6: F2 schema referenced TrN_DataOst which doesn't exist — rewritten to TrN_TS_Mod.
• v0.3.2 #7: InvoiceManagementInterface::prepareInvoice in Magento 2.4.7 wants an Order object, not entity_id — fixed by switching to InvoiceService.
• v0.3.3 #1+2: partial WZ/FA created full shipment/invoice → fixed via TraElem join + buildItemQtysMap.
• v0.3.4 #5: duplicate SKU within one order (custom options) — fixed via FIFO queue per SKU.
• v0.3.4 #7: HMAC + Polish characters (Brzęczyszczykiewicz in order forward) — fixed with explicit UTF-8 in StreamReader.

Every bug found and fixed before it could hit a customer. Stability is the priority.

How to report a bug

Email [email protected] with:

• module version (see app/code/Sisl/Optima/etc/module.xml);
• .NET service version (see /healthz endpoint);
• repro steps;
• Magento logs (var/log/system.log) + .NET service logs (logs/).

Critical bugs fixed within 24 business hours — guaranteed at the PLN 300/month subscription.