Jak działa integracja z Magento 2?

Najczęściej połączenie Magento 2 z programem fakturowym, magazynowym, ERP albo systemem obsługi zamówień odbywa się przez API. Jeden system udostępnia dane, drugi je pobiera lub aktualizuje, a integracja pilnuje, żeby zamówienie złożone w sklepie nie musiało być ponownie wpisywane ręcznie.

Przy dobrze skonfigurowanym połączeniu klient składa zamówienie w Magento, a dalej większość operacji może odbyć się automatycznie.

Co można pobierać z Magento 2?

Magento posiada REST API pozwalające zewnętrznym systemom pracować między innymi z zamówieniami, klientami, produktami, fakturami, wysyłkami czy magazynem.

Najprostsza integracja z programem do fakturowania interesuje się głównie zamówieniami.

System może pobrać:

numer zamówienia,
dane kupującego,
NIP, jeśli został podany,
adres rozliczeniowy,
adres dostawy,
produkty i ich SKU,
liczbę sztuk,
ceny,
rabaty,
koszty dostawy,
walutę,
metodę płatności,
status zamówienia.

Na tej podstawie zewnętrzny program może utworzyć dokument sprzedaży bez ponownego przepisywania danych przez pracownika.

To ważne zwłaszcza przy większych sklepach. Przy pięciu zamówieniach dziennie ręczne wystawianie faktur jest jeszcze do wykonania. Przy pięciuset staje się osobnym stanowiskiem pracy.

Jak wygląda typowy proces?

Najprostszy wariant można przedstawić na jednym zamówieniu.

Klient kupuje w sklepie Magento trzy produkty. Wprowadza dane firmy i NIP, płaci BLIK-iem albo kartą.

Magento zapisuje zamówienie.

Integracja sprawdza nowe zamówienia i pobiera jego dane. Może też czekać, aż zamówienie otrzyma określony status, na przykład potwierdzający otrzymanie płatności.

Dane trafiają do programu fakturowego.

Program tworzy kontrahenta, jeżeli jeszcze go nie posiada, dodaje odpowiednie produkty i wystawia fakturę.

Jeżeli dokument podlega KSeF, może zostać wysłany do Krajowego Systemu e-Faktur. Informacja o wystawieniu dokumentu może później wrócić do procesu obsługi zamówienia.

W dobrze przygotowanej integracji pracownik nie robi tego:

Magento → kopiuj imię → kopiuj firmę → kopiuj NIP → kopiuj adres → kopiuj produkty → sprawdź cenę → wystaw fakturę.

Dane powinny przejść pomiędzy systemami automatycznie.

Nie każde zamówienie powinno od razu tworzyć fakturę

To jedna z najważniejszych decyzji podczas konfiguracji.

Można ustawić:

„wystawiaj fakturę po każdym nowym zamówieniu”.

Technicznie jest to możliwe, ale zwykle nie jest najlepszym rozwiązaniem.

Klient może przecież wybrać przelew tradycyjny i nigdy go nie wykonać. Płatność kartą może zostać odrzucona. Zamówienie może zostać anulowane kilka minut po złożeniu.

Dlatego często bezpieczniejszym wyzwalaczem jest odpowiedni status zamówienia albo potwierdzenie płatności.

Przykładowo:

pending – jeszcze bez faktury,

processing – zamówienie opłacone, można utworzyć dokument,

canceled – nie wystawiaj faktury,

complete – zamówienie zrealizowane.

Nie należy jednak kopiować tych zasad mechanicznie do każdego sklepu. Magento pozwala dostosowywać statusy i sposób obsługi zamówień, dlatego integracja musi być dopasowana do rzeczywistego procesu.

Sklep, który wystawia fakturę już przy przyjęciu zamówienia B2B z odroczonym terminem płatności, potrzebuje innych reguł niż detaliczny e-commerce, w którym dokument powstaje dopiero po płatności online.

Faktura w Magento i faktura podatkowa to nie zawsze to samo

To ważne rozróżnienie.

Magento ma własny obiekt „invoice”. W panelu można utworzyć invoice do zamówienia, oznaczyć zafakturowane pozycje i wykorzystać ten dokument w procesie realizacji sprzedaży.

Nie oznacza to automatycznie, że taki dokument spełnia wszystkie wymagania polskiej faktury podatkowej, a tym bardziej że został przesłany do KSeF.

Magento jest międzynarodową platformą e-commerce. Nie należy więc zakładać, że utworzenie invoice w Magento załatwia polskie obowiązki związane z fakturowaniem.

W polskim sklepie rozsądny podział może wyglądać tak:

Magento odpowiada za zamówienie i sprzedaż internetową, a wyspecjalizowany polski program odpowiada za prawidłową fakturę, VAT i KSeF.

Integracja łączy te dwa procesy.

API nie powinno mieć dostępu do wszystkiego

Podłączenie zewnętrznego systemu wymaga uwierzytelnienia.

W Magento Open Source i klasycznych wdrożeniach Adobe Commerce można tworzyć integracje i określać, do jakich zasobów API mają dostęp. Nie należy przekazywać zewnętrznemu programowi pełnych uprawnień administratora tylko dlatego, że potrzebuje odczytać zamówienia.

Jeżeli integracja ma wyłącznie pobierać zamówienia i klientów, powinna dostać uprawnienia potrzebne do tych operacji.

Jeżeli ma dodatkowo aktualizować produkty i stany, zakres będzie szerszy.

To ważne także z praktycznego punktu widzenia. Błąd w integracji mającej wyłącznie odczyt zamówień może uniemożliwić wystawienie faktury. Błąd w aplikacji posiadającej możliwość edycji całego katalogu może zmienić tysiące produktów.

Dane dostępowe do API również nie powinny być umieszczane w publicznym kodzie strony czy przesyłane e-mailem między pracownikami.

Synchronizacja może działać w jedną albo w dwie strony

Integracja Magento 2 z innym systemem nie musi oznaczać pełnej synchronizacji wszystkiego.

Najprostszy wariant:

Magento → program fakturowy

Ze sklepu pobierane są zamówienia, a program na ich podstawie wystawia dokumenty.

Bardziej rozbudowany:

Magento ↔ system ERP lub magazyn

Magento przekazuje zamówienia, a zewnętrzny system odsyła aktualne stany i ceny.

Można też stworzyć układ, w którym Magento jest wyłącznie kanałem sprzedaży, natomiast kartoteka produktów, ceny i magazyn są zarządzane w ERP.

To dużo bezpieczniejsze niż sytuacja, w której ten sam stan produktu jest niezależnie edytowany przez pracownika w Magento i w programie magazynowym.

Firma powinna zdecydować, który system jest nadrzędny dla konkretnej informacji.

Przykładowo:

zamówienia – Magento,
faktury – program fakturowy,
stany – ERP,
opisy i zdjęcia – Magento.

Bez takiej decyzji szybko pojawiają się konflikty.

A co ze stanami magazynowymi?

Magento 2 ma własny system zarządzania zapasami. Pozwala pracować z produktami, źródłami towaru i stanami.

Jeżeli jednak firma równocześnie prowadzi magazyn w zewnętrznym programie, trzeba określić źródło prawdy.

Załóżmy, że Magento pokazuje 20 sztuk.

Zamówienie klienta obejmuje 5.

Jednocześnie handlowiec sprzedał telefonicznie 10 sztuk i wystawił dokument w zewnętrznym systemie.

Jeżeli oba systemy nie wymieniają informacji o stanach, Magento nadal może pozwalać klientowi kupić 15 sztuk, mimo że fizycznie zostało tylko 5.

Dlatego przy pełnej integracji można synchronizować również zapasy.

Nie zawsze jest to jednak potrzebne. Jeżeli zewnętrzny program służy tylko do fakturowania, a cały magazyn nadal prowadzony jest w Magento, dokładanie drugiego magazynu może stworzyć więcej problemów niż korzyści.

Pobieranie co kilka minut czy reakcja natychmiast po zdarzeniu?

Integracje mogą pracować na dwa sposoby.

Pierwszy to cykliczne pytanie Magento:

„Czy od ostatniego sprawdzenia pojawiły się nowe zamówienia?”

Program wykonuje je np. co kilka minut i pobiera zamówienia spełniające określone kryteria.

Takie rozwiązanie jest stosunkowo proste i w wielu sklepach w zupełności wystarcza.

Drugi model opiera się na zdarzeniach. Gdy coś wydarzy się w systemie, informacja jest wysyłana do integracji.

Adobe Commerce rozwija obecnie mechanizmy Events i Webhooks, ale dostępne możliwości zależą od wersji i modelu wdrożenia. Nie należy więc zakładać, że każdy sklep Magento Open Source ma dokładnie taki sam zestaw webhooków jak najnowszy Adobe Commerce as a Cloud Service.

W przypadku Magento Open Source często spotyka się również własny moduł integracyjny, który reaguje na konkretne zdarzenia sklepu i informuje system zewnętrzny.

Z punktu widzenia właściciela sklepu liczy się efekt: zamówienie powinno znaleźć się w programie docelowym wystarczająco szybko i tylko raz.

Najgroźniejszy błąd integracji: podwójne faktury

Wyobraźmy sobie sytuację:

integracja pobiera zamówienie nr 100045 i wystawia fakturę.

Po chwili traci połączenie, zanim zapisze informację, że operacja się udała.

Przy następnej próbie ponownie widzi zamówienie nr 100045 jako nieobsłużone i wystawia drugą fakturę.

Dlatego dobra integracja powinna być odporna na ponowne przetwarzanie tych samych danych.

Najprostszym zabezpieczeniem jest przechowywanie powiązania:

Magento order_id → ID dokumentu w programie fakturowym

Przed wystawieniem faktury system sprawdza wtedy, czy dane zamówienie zostało już obsłużone.

Podobnie trzeba traktować zwroty, korekty i częściową realizację zamówienia. Integracja sklepu internetowego nie może zakładać, że każde zamówienie zawsze przechodzi idealną ścieżkę od „nowe” do „zrealizowane”.

Magento 2, KSeF i sprzedaż B2B

W polskim e-commerce dochodzi obecnie jeszcze KSeF.

Jeżeli klient kupuje jako przedsiębiorca i faktura podlega obowiązkowemu KSeF, samo wygenerowanie PDF nie kończy procesu.

Dlatego wygodny model wygląda tak:

Magento pobiera zamówienie → dane trafiają do polskiego programu fakturowego → powstaje faktura → dokument trafia do KSeF → program zapisuje numer i status KSeF.

Sprzedawca nie powinien ręcznie przepisywać zamówienia do kolejnego programu tylko dlatego, że platforma sklepu nie obsługuje polskiego systemu podatkowego w potrzebnym zakresie.

Inaczej wygląda sprzedaż konsumentowi. Faktury B2C nie są objęte obowiązkowym KSeF, dlatego reguły automatyzacji powinny rozpoznawać, z jakim typem nabywcy mamy do czynienia.

Jak połączyć Magento 2 z FakturBox?

Obecnie FakturBox nie ma na liście gotowych integracji bezpośredniego modułu Magento 2.

Są natomiast dwie praktyczne drogi.

Pierwsza prowadzi przez Base.com.

Base.com obsługuje Magento 2 / Adobe Commerce i może połączyć się ze sklepem przez API, pobierać zamówienia oraz synchronizować wybrane dane. FakturBox posiada z kolei gotową integrację z Base.com.

W takim układzie przepływ może wyglądać następująco:

Magento 2 → Base.com → FakturBox

To rozwiązanie jest szczególnie sensowne w sklepach, które już wykorzystują Base.com do obsługi zamówień z kilku kanałów.

Druga możliwość to własna integracja API.

FakturBox udostępnia API do integracji z systemami zewnętrznymi, a Magento posiada rozbudowane REST API. Można więc zbudować połączenie dopasowane dokładnie do procesu sklepu – na przykład pobierać tylko opłacone zamówienia B2B, tworzyć faktury i następnie obsługiwać je w KSeF.

Przy własnym wdrożeniu trzeba jednak dokładnie określić mapowanie danych i zachowanie w sytuacjach wyjątkowych.

Co trzeba ustalić przed rozpoczęciem integracji?

Nie zaczynałbym od pytania „jaki endpoint wywołać?”.

Najpierw trzeba opisać proces biznesowy.

Kiedy powstaje faktura?
Po utworzeniu zamówienia czy po płatności?

Co robimy z pobraniem za pobraniem?

Jak rozpoznajemy klienta B2B?

Co dzieje się po anulowaniu zamówienia?

Jak obsługujemy częściowy zwrot?

Który system kontroluje stan magazynowy?

Czy ceny zmieniają się w Magento, czy w ERP?

Co robimy, jeśli program fakturowy albo KSeF jest chwilowo niedostępny?

Dopiero później warto programować.

Wiele problemów przypisywanych później „błędom API” w rzeczywistości wynika z tego, że nikt wcześniej nie zdecydował, co integracja powinna zrobić w nietypowej sytuacji.

Dobra integracja z Magento 2 jest właściwie niewidoczna. Klient kupuje produkt, zamówienie trafia do realizacji, faktura powstaje w odpowiednim momencie, a pracownik nie zastanawia się, które dane trzeba jeszcze przepisać do kolejnego systemu.

Jeżeli po wdrożeniu integracji nadal codziennie eksportuje się CSV, kopiuje NIP-y i ręcznie sprawdza, czy wszystkie faktury zostały wystawione, połączono systemy technicznie, ale nie zautomatyzowano procesu.