KSeF a Magento i Optima: kto i kiedy wystawia fakturę?

Gdzie fizycznie powstaje faktura: w Magento 2.4.7 czy w Comarch Optima?

Krótka i jednoznaczna odpowiedź: fakturę ustrukturyzowaną wystawia i wysyła do Ministerstwa Finansów wyłącznie Comarch ERP Optima. Magento 2 zbiera koszyk, blokuje stany magazynowe, rejestruje płatność z Przelewy24 lub BLIK i przekazuje rekord transakcji jako zamówienie (Order) do ERP. Próba zmuszenia Magento do bezpośredniej komunikacji z API KSeF w architekturze zintegrowanej z Optimą to prosty przepis na rozjazd numeracji, podwójne księgowanie i chaos w JPK_V7. W architekturze, którą projektujemy w ramach KSeF w SISL Optima Connector, silnik e-commerce pozostaje warstwą sprzedażową, a ERP jest jedynym źródłem prawdy księgowej.

Dlaczego nie generować faktury w Magento? Standardowy mechanizm sales_order_invoice w Magento 2.4.7 (działającym na PHP 8.3 i OpenSearch 2.12) tworzy encję faktury wewnętrznej na potrzeby statusów e-commerce. Ta faktura nie jest jednak dokumentem fiskalnym w polskim porządku prawnym. Jeśli zainstalujesz moduł firm trzecich (np. Amasty, Mageworx czy Mirasvit) z zamiarem bezpośredniego wypychania XML-a FA(2) do środowiska produkcyjnego KSeF z poziomu Adobe Commerce, natrafisz na mur:

• Biała lista VAT i weryfikacja NIP: Optima weryfikuje status czynnego podatnika VAT i numer rachunku w Wykazie Podatników VAT przed nadaniem numeru dokumentu. Magento tego nie robi natywnie bez zewnętrznych, płatnych integracji.
• Korekty i anulacje: Jeśli klient zmieni zdanie przed wysyłką, w Magento zrobisz Credit Memo, ale w KSeF faktura pierwotna już istnieje i wymaga sformalizowanej faktury korygującej z odniesieniem do numeru KSeF dokumentu bazowego.
• Fiskalizacja zamówień mieszanych: Optima bez problemu rozdziela transakcje B2C (paragon fiskalny lub faktura bez KSeF) od transakcji B2B (obowiązkowy KSeF) na podstawie atrybutów kontrahenta i stawek podatkowych.

Kiedy dokładnie dokument trafia do KSeF i co wraca do sklepu?

Proces nie odbywa się synchronicznie w momencie kliknięcia „Kupuję i płacę”. Próba synchronicznego strzału do API KSeF podczas checkoutu na motywie Hyvä sparaliżowałaby sklep przy pierwszym spowolnieniu serwerów rządowych. Przepływ w poprawnie wdrożonym tandemie Magento–Optima wygląda następująco:

1. Klient składa zamówienie w Magento 2, wybiera opcję „Faktura VAT” i podaje NIP.
2. Webhook z Przelewy24 potwierdza wpłatę (status transakcji: Processing).
3. Harmonogram cron (lub kolejka RabbitMQ) przesyła obiekt zamówienia do Comarch Optima przez WebAPI / COM.
4. Magazyn kompletuje towar, a pracownik lub automat w Optimie generuje dokument handlowy (FA).
5. Optima wysyła dokument do KSeF w sesji interaktywnej lub wsadowej, podpisując go pieczęcią firmową lub certyfikatem.
6. Bramka KSeF zwraca 32-znakowy identyfikator (np. 1234567890-20260215-ABC123DEF456-78) oraz Urzędowe Poświadczenie Odbioru (UPO).
7. Konektor pobiera numer KSeF z Optimy i wstrzykuje go do Magento w tabeli sales_order_grid oraz do szczegółów konta klienta.

Wdrożeniowy fakt: Data wystawienia faktury to data jej przesłania do KSeF, a nie data wygenerowania zamówienia w Magento. Jeśli zamówienie wpłynie w piątek o 23:59, a automat w ERP przetworzy je w poniedziałek o 06:00, to poniedziałek jest prawną datą wystawienia faktury.

Jak obsłużyć zamówienia z Allegro, pobrania i odroczone płatności?

Wielokanałowość komplikuje sprawę. Jeśli sprzedajesz na Magento i równolegle na Allegro (przez Baselinkera lub natywny integrator), oba strumienie zamówień wpadają do Optimy. W SISL stoimy na stanowisku, że to Optima musi być centralnym dyspozytorem KSeF dla wszystkich kanałów. Gdyby Baselinker pchał do KSeF swoje faktury, a Magento swoje, w Comarch Optima powstałby koszmar uzgadniania rejestrów VAT.

W przypadku zamówień za pobraniem (np. InPost Pobranie) faktura nie może trafić do KSeF przed fizycznym wydaniem towaru z magazynu. Procedura wymaga wystawienia dokumentu Pro Forma (lub zamówienia zaliczkowego RO) w Optimie, a przekształcenie do FA i wysyłka do KSeF następuje w momencie wygenerowania etykiety w InPost ShipX. Dzięki temu unikasz korygowania faktur dla paczek nieodebranych przez klientów, które wracają na magazyn.

Typowe błędy API i co się dzieje, gdy KSeF nie działa?

Bramka KSeF potrafi zwrócić błąd 400 Bad Request (błąd schemy XML) albo 422 Unprocessable Entity (np. niepoprawny NIP, brak prefiksu kraju, nieprawidłowa stawka VAT). Co wtedy dzieje się ze sklepem?

Sklep internetowy musi działać bez zakłóceń. Magento nie może blokować checkoutu ani wysypywać fatal errorów. Prawidłowa integracja buforuje transakcje w tabelach pośrednich. Jeśli Optima dostanie odrzut z KSeF z powodu literówki w NIP-ie klienta:

• Zamówienie w Magento zachowuje status Processing, a magazyn może wstrzymać pakowanie na podstawie flagi błędu.
• ERP oznacza dokument statusem błędu i wysyła alert do działu obsługi klienta.
• Po poprawieniu danych w kartotece kontrahenta w Optimie następuje ponowna wysyłka (retry policy).
• W Magento nie zmieniamy bezpośrednio danych w bazie przez zapytania SQL — każda zmiana musi przejść przez CustomerRepositoryInterface lub OrderRepositoryInterface, aby nie naruszyć spójności indeksów OpenSearch.

Dlaczego natywne pluginy KSeF do Magento to ślepy zaułek?

Na rynku pojawiły się moduły obiecujące „KSeF bezpośrednio z panelu Magento za 499 PLN”. Dla małego sklepu bez ERP może to być prowizoryczne rozwiązanie. Jednak dla firmy operującej na Comarch Optima taki moduł to pułapka technologiczna. Uruchomienie wysyłki do KSeF z poziomu Magento przy jednoczesnej synchronizacji z ERP tworzy tzw. problem dwóch masterów (Two-Master Problem):

Kto decyduje o numerze faktury? Kto przechowuje XML z UPO? Jeśli Magento nada numer i wyśle XML, to Comarch Optima musi zaimportować gotowy dokument FA, zamiast go wygenerować. Tymczasem silnik Optimy ma własną logikę kalkulacji groszy, rabatów i zaokrągleń (zwłaszcza przy stawkach 8%, 5% i 23%), która często różni się o 1 grosz od kalkulatora Magento\Tax\Model\Calculation. Wtedy Optima odrzuci import dokumentu z błędem niezgodności sumy pozycji z nagłówkiem.

Jedynym stabilnym modelem jest model asymetryczny: Magento zbiera zamówienie brutto/netto, przesyła koszyk do Comarch Optima, Optima dokonuje kalkulacji zgodnej z polską ustawą o rachunkowości, rejestruje dokument w KSeF, a z powrotem do Magento odsyła wyłącznie numer KSeF, link do pobrania zweryfikowanego PDF z kodem QR oraz status fiskalny.

Wdrożenie: na co zwrócić uwagę przed kompilacją?

Zanim uruchomisz na produkcji bin/magento setup:di:compile i wyczyścisz cache komendą bin/magento cache:flush, sprawdź architekturę swoich atrybutów. Upewnij się, że:

• Pole NIP w checkoucie jest zmapowane do standardowego atrybutu vat_id lub dedykowanego pola z modułu (np. Amasty Order Attributes), które Optima odczytuje bez obcinania znaków specjalnych.
• Mapowanie kodów GTU i procedur (np. MPP) jest zdefiniowane po stronie atrybutów produktów w Magento i mapowane 1:1 na grupy towarowe w Optimie.
• Masz wdrożony mechanizm pobierania zwrotnego UPO, aby klient na swoim koncie w panelu Magento mógł pobrać dokument z wizualizacją numeru KSeF.

Integracja Magento 2 z Comarch ERP Optima w realiach KSeF wymaga precyzyjnego podziału odpowiedzialności systemów. Jeśli planujesz uporządkować przepływ dokumentów w swoim sklepie lub zmigrować niespójne integracje, napisz do nas — dobierzemy architekturę, która nie zatrzyma sprzedaży w szczycie sezonu.