Dwukierunkowa integracja Comarch Optima, Subiekt nexo i KSeF z prywatną bramką AI: architektura mostka Go + SQL bez ręcznego przepisywania faktur

✦ Materiał przygotowany przez zespół inżynieryjny Miscat.tech (Case Study Wdrożeniowe): W polskich firmach produkcyjnych, spedycyjnych (TSL) i hurtowniach ponad 70% systemów ERP (Comarch ERP Optima, Comarch XL, InsERT Subiekt GT oraz Subiekt nexo PRO) działa na lokalnych serwerach MS SQL Server w siedzibie firmy. W tym artykule pokazujemy krok po kroku naszą produkcyjną architekturę mostka w języku Go (Golang), dzięki której u naszych klientów (m.in. w projektach Humi i firmach logistyczno-produkcyjnych) skróciliśmy czas rozliczania dokumentów z 40 godzin miesięcznie do 15 minut przy 0% błędów w KSeF.

1. Dlaczego standardowe integracje plikowe (CSV / XML) i chmurowe konektory zawodzą na produkcji?

Właściciele firm i główni księgowi często słyszą od dostawców oprogramowania, że „integracja polega na eksporcie pliku CSV lub XML raz dziennie”. W realnym biznesie B2B (gdzie spedycja wystawia 150 zleceń dziennie, a magazyn wydaje towar z 4 ramp jednocześnie) podejście plikowe generuje trzy krytyczne awarie:

• Rozjazd stanów magazynowych i rezerwacji (Overselling): Handlowiec lub portal B2B sprzedaje towar, który 20 minut wcześniej został wydany na dokument WZ w Subiekcie, ale plik synchronizacyjny jeszcze się nie przetworzył.
• Duplikaty dokumentów przy ponowieniu (Lack of Idempotency): Gdy połączenie sieciowe zerwie się w połowie importu paczki faktur, ponowne uruchomienie skryptu tworzy zdublowane faktury zakupu (FZ) lub zamówienia (ZK) w rejestrze VAT.
• Odrzucenie całej paczki przez KSeF (Schema FA(2)/FA(3) Reject): Brak jednego kodu kraju w NIP kontrahenta unijnego lub rozbieżność o 1 grosz w zaokrągleniu podatku VAT między systemem zewnętrznym a silnikiem ERP blokuje wysyłkę całej partii faktur.

2. Architektura Miscat.tech: Lekki demon Go („On-Premise Edge Bridge”) przy serwerze MS SQL

Zamiast wystawiać port bazy danych MS SQL (1433) na publiczny internet (co jest ogromnym błędem bezpieczeństwa), w Miscat.tech instalujemy bezpośrednio na maszynie z serwerem ERP pojedynczy, skompilowany plik binarny napisany w języku Go (zużywający poniżej 25 MB pamięci RAM).

Demon działa jako usługa systemowa Windows (Windows Service) i łączy się z bazą ERP lokalnie przez oficjalne API obiektowe (Sfera dla Subiekta GT, SDK dla Subiekta nexo, dedykowane procedury i widoki dla Comarch ERP Optima), a ze światem zewnętrznym utrzymuje szyfrowany tunel mTLS / WireGuard z kolejką transakcyjną PostgreSQL:

// Fragment architektury transakcyjnej mostka Miscat.tech (Go + Idempotency Key)
func (s *ERPBridge) UpsertPurchaseInvoice(ctx context.Context, req InvoicePayload) (*SyncResult, error) {
    // 1. Sprawdzenie klucza idempotentności (SHA-256 z NIP + Numer Faktury + Data)
    exists, existingID, err := s.store.CheckIdempotencyKey(ctx, req.IdempotencyHash)
    if err != nil {
        return nil, fmt.Errorf("idempotency check failed: %w", err)
    }
    if exists {
        return &SyncResult{Status: "ALREADY_SYNCED", DocumentID: existingID}, nil
    }

    // 2. Twarda walidacja arytmetyczna (Netto + VAT == Brutto co do grosza)
    if err := ValidatePolishVATArithmetic(req.Lines, req.TotalNet, req.TotalVAT, req.TotalGross); err != nil {
        return nil, fmt.Errorf("arithmetic validation failed before ERP write: %w", err)
    }

    // 3. Zapis przez natywne API ERP w transakcji z automatycznym rollbackiem
    docID, err := s.erpAdapter.CreateFZDocument(ctx, req)
    if err != nil {
        return nil, err
    }

    _ = s.store.RecordIdempotencyKey(ctx, req.IdempotencyHash, docID)
    return &SyncResult{Status: "CREATED", DocumentID: docID}, nil
}

3. Jak działa automatyczny potok OCR + Vision AI dla faktur kosztowych i dokumentów CMR?

W firmach transportowych, budowlanych i produkcyjnych największym pożeraczem czasu jest ręczne przepisywanie wielostronicowych faktur zakupowych (paliwo, części, surowce, podwykonawcy) oraz parowanie ich z listami przewozowymi CMR i dokumentami WZ. Klasyczny OCR szablonowy gubi się, gdy dostawca zmieni układ tabeli na fakturze.

Nasz potok przetwarzania łączy model wizyjny z deterministyczną walidacją w bazie ERP:

1. Pobranie załącznika 24/7: Gdy na skrzynkę faktury@twojafirma.pl (lub przez komunikator / KSeF) wpływa dokument PDF lub zdjęcie CMR z trasy, webhook przekazuje plik do kolejki w ciągu 300 ms.
2. Ekstrakcja strukturalna z dopasowaniem indeksów: Prywatny agent AI (działający w reżimie Zero-Data-Retention) wyciąga pozycje faktury i za pomocą narzędzia MCP match_erp_contractor_and_sku dopasowuje nazwę towaru z faktury dostawcy (np. „Płyta wiórowa laminowana Dąb Sonoma 18mm”) do właściwego indeksu magazynowego w Subiekcie lub Optimie.
3. Weryfikacja z Białą Listą Podatników VAT (Wykaz MF) i VIES: Zanim dokument trafi do bufora księgowego, nasz serwis Go automatycznie sprawdza status czynnego podatnika VAT i numer rachunku bankowego na Białej Liście Ministerstwa Finansów, zapisując kryptograficzny identyfikator sprawdzenia (requestId) w notatce dokumentu.

4. Porównanie 3 podejść do integracji ERP w polskiej firmie B2B

5. Chcesz połączyć swój system Comarch Optima lub Subiekt z automatyzacją AI?

W Miscat.tech budujemy dedykowane integracje ERP, portale zamówień hurtowych B2B oraz prywatnych asystentów AI podłączonych bezpośrednio do Twojej bazy danych (pod umową NDA). Pierwszy działający proces wdrażamy na produkcję zazwyczaj w 2 do 4 tygodni — zarówno zdalnie w całej Polsce i UE, jak i bezpośrednio na miejscu u klientów w regionie (Zambrów, Łomża, Białystok, Ostrów Mazowiecka, Warszawa). Umów bezpłatną 15-minutową rozmowę techniczną →