Pytanie „czy integrować sklep z systemami, które już mamy” praktycznie nie pada. Odpowiedź jest oczywista, bo ręczne przepisywanie zamówień do programu magazynowego kończy się dokładnie tam, gdzie zaczyna się sensowna sprzedaż. Pada za to inne pytanie, dużo trudniejsze i zwykle zadawane za późno: którą metodą połączyć oba systemy i co dokładnie ma między nimi krążyć.
Ten tekst jest o tej decyzji. Opisuje cztery metody integracji, kryteria wyboru między nimi, listę rzeczy do ustalenia przed startem oraz miejsca, w których projekty integracyjne najczęściej się zatrzymują. Mechanikę trzech konkretnych obszarów zewnętrznych, czyli wysyłki, feedów produktowych i hurtowni, opisujemy osobno w tekście o integracjach zewnętrznych w PrestaShop.
Nie „czy integrować”, tylko „co dokładnie wymieniać”
Rozmowa o integracji zwykle zaczyna się od nazwy systemu. Firma ma program magazynowy albo ERP i chce, żeby „to się gadało ze sklepem”. To jest punkt wyjścia, a nie specyfikacja, bo nie mówi nic o tym, jakie dane mają płynąć, w którą stronę, jak często i który system ma rację, gdy oba znają tę samą wartość.
Dobrze postawione pytanie brzmi więc inaczej. Nie „z czym się integrujemy”, tylko „które dane wymieniamy, w jakim kierunku, z jaką częstotliwością i kto jest dla nich źródłem prawdy”. Dopiero mając te odpowiedzi, da się rozsądnie wybrać metodę. Odwrotna kolejność, czyli najpierw wybór narzędzia, a potem sprawdzanie, czy uniesie wymagania, to najkrótsza droga do przepisywania integracji w połowie projektu.
Cztery metody połączenia
W praktyce projekty integracyjne układają się w cztery ścieżki. Różnią się nie tylko kosztem, ale przede wszystkim tym, gdzie leży kontrola nad logiką wymiany i kto odpowiada za awarię.
Gotowy moduł integracyjny
Najtańsze wejście i najkrótszy czas wdrożenia. Instalujesz moduł, konfigurujesz dane dostępowe i wymiana rusza. Sprawdza się tam, gdzie po drugiej stronie stoi popularny system w standardowej konfiguracji, a zakres danych mieści się w tym, co autor modułu przewidział.
Granica jest dokładnie w tym ostatnim zdaniu. Gotowy moduł realizuje cudze założenia, więc pierwsze nietypowe wymaganie, na przykład osobny cennik dla grupy klientów albo własna reguła przeliczania jednostek, wymaga albo rozszerzenia modułu, albo rezygnacji z niego. Dochodzi zależność od cyklu wydawniczego dostawcy: aktualizacja modułu potrafi zepsuć działającą wymianę przy niezmienionym sklepie, a Ty nie decydujesz, kiedy ta aktualizacja się pojawi.
Wymiana po plikach
Metoda, którą łatwo uznać za przestarzałą, a która w wielu projektach jest najrozsądniejszym wyborem. Jeden system odkłada plik w uzgodnionym miejscu, drugi go odczytuje i przetwarza. Format zwykle prosty, harmonogram cykliczny.
Wymiana plikowa wygrywa wtedy, gdy system po drugiej stronie nie ma użytecznego interfejsu programistycznego albo gdy dostęp do niego jest kosztowny czy obwarowany licencją. Wygrywa też odpornością: plik można obejrzeć, powtórzyć przetwarzanie, zarchiwizować i pokazać przy reklamacji.
Płaci się za to opóźnieniem i obowiązkiem sprzątania. Dane są tak świeże, jak ostatni przebieg, a katalog z plikami rośnie i po kilku miesiącach samo jego przetworzenie staje się kosztem. Dlatego przy tej metodzie trzeba od razu ustalić dwie rzeczy: kto i kiedy czyści stare wpisy oraz po czym poznać, że dany plik został już przetworzony.
Dedykowana integracja przez API
Sklep i system firmowy rozmawiają bezpośrednio, kodem pisanym pod konkretny przypadek. To najdroższa i najbardziej elastyczna ścieżka, a jednocześnie jedyna, która pozwala odwzorować nietypowy proces bez kompromisów.
Wybiera się ją wtedy, gdy wymiana ma być dwukierunkowa i warunkowa, gdy w grę wchodzą reguły biznesowe, których gotowy moduł nie zna, albo gdy integracja dotyka rzeczy wrażliwych, jak kredyt kupiecki, indywidualne cenniki czy rozliczenia częściowe. Kosztem jest utrzymanie: kod dedykowany jest Wasz i to Wy odpowiadacie za jego zgodność z kolejnymi wersjami obu systemów.
Warto przy tym wiedzieć, że dedykowana nie musi znaczyć pisana od zera. Sensownie prowadzona pracownia buduje jeden szkielet integracyjny i dokłada do niego sterowniki pod kolejne systemy. Dzięki temu logika wspólna, czyli harmonogram, obsługa błędów, logowanie i konfiguracja, powstaje raz, a pod nowy system pisze się wyłącznie warstwę tłumaczącą jego dane.
Integrator zewnętrzny
Czwarta ścieżka to platforma pośrednicząca, która wpina się między sklep a resztę systemów i bierze na siebie komunikację z wieloma kanałami naraz. W polskich realiach najczęściej rozważanym rozwiązaniem tej klasy jest Baselinker.
Ma to sens przede wszystkim wtedy, gdy kanałów jest dużo, a każdy z nich osobno nie uzasadnia własnej integracji: kilka marketplace’ów, kilku przewoźników, program magazynowy, wszystko obsługiwane z jednego miejsca. Cena to kolejny element w łańcuchu, nad którym nie macie kontroli, oraz ograniczenie zakresu danych do tego, co integrator obsługuje. Przy nietypowej konfiguracji sklepu, zwłaszcza wielosklepowej, warto sprawdzić zachowanie takiego pośrednika osobno dla każdego sklepu, zanim stanie się centralnym elementem procesu.
Które kryteria naprawdę rozstrzygają
| Kryterium | Gotowy moduł | Pliki | Dedykowana | Integrator |
|---|---|---|---|---|
| Czas uruchomienia | dni | dni | tygodnie | dni |
| Nietypowe reguły biznesowe | nie | ograniczone | tak | nie |
| Aktualność danych | zależna od modułu | cykliczna | dowolna | zależna od platformy |
| Kto odpowiada za awarię | dostawca modułu | obie strony | Wy | dostawca platformy |
| Koszt zmiany wymagań | wysoki | niski | średni | wysoki |
| Ryzyko przy aktualizacji | realne | niskie | kontrolowane | realne |
Te cztery ścieżki wolno łączyć i w większych wdrożeniach zwykle się je łączy. Zamówienia potrafią iść dedykowanym kanałem, stany magazynowe plikiem, a sprzedaż na marketplace’ach przez integratora. Ważne, żeby dla każdego strumienia danych decyzja była świadoma, a nie odziedziczona po tym, co akurat było pod ręką.
Webservice PrestaShopa, czyli co dostajesz w standardzie
Zanim zamówisz cokolwiek dedykowanego, warto wiedzieć, co PrestaShop ma wbudowane. Webservice to wewnętrzny interfejs programistyczny sklepu, włączany w ustawieniach zaawansowanych. Tworzysz klucz dostępu i nadajesz mu uprawnienia osobno dla każdego zasobu i osobno dla każdej operacji, więc integracja pobierająca zamówienia nie musi mieć prawa kasowania produktów.
Interfejs udostępnia najważniejsze zasoby sklepu, między innymi produkty, kombinacje, kategorie, klientów, adresy, zamówienia i stany magazynowe. Odpowiedzi domyślnie przychodzą w formacie XML, można je przełączyć na JSON. Dostępne są filtrowanie, sortowanie i stronicowanie, a pustą strukturę rekordu da się pobrać, żeby zobaczyć, jakich pól system oczekuje przy zapisie.
Trzy ograniczenia trzeba znać, zanim oprze się na tym projekt. Po pierwsze, to interfejs operujący na danych, a nie na procesach: zapisze zamówienie, ale nie wykona za Was logiki biznesowej, która ma się przy tym zadziać. Po drugie, standardowy webservice nie wysyła powiadomień o zdarzeniach, więc nie ma tu webhooków w takim sensie, w jakim znasz je z systemów płatniczych. System zewnętrzny musi dopytywać cyklicznie albo trzeba dołożyć moduł, który wywoła adres zewnętrzny w momencie, gdy coś się w sklepie wydarzy. Po trzecie, pobieranie dużych zbiorów jednym przebiegiem zwykle nie przechodzi i trzeba przetwarzać porcjami.
Wniosek praktyczny: webservice świetnie nadaje się na czytanie danych ze sklepu i na proste zapisy. Do procesu, w którym coś ma się wydarzyć w konkretnym momencie i w konkretnej kolejności, i tak potrzebna jest warstwa po stronie sklepu.
Co trzeba ustalić, zanim wybierzesz metodę
To jest lista, która najczęściej decyduje o tym, czy projekt skończy się w terminie. Warto ją przejść na kartce, zanim padnie pierwsza wycena, bo każda nieodpowiedziana pozycja wraca później jako zmiana zakresu.
Produkty
Zakres bazowy jest prosty: nazwa, kod, numer EAN. Aktualizacje to zwykle stany i ceny. Reszta wymaga decyzji i to w niej siedzi cały koszt. Czy z systemu firmowego idą też cechy, opisy, zdjęcia, czas realizacji? Czy warianty istnieją po obu stronach jako to samo, czy w jednym systemie są osobnymi kartotekami? Jaka jest jednostka zamówienia, sztuka, karton czy paleta? Czy w grę wchodzą rabaty ilościowe, progi cenowe, ceny indywidualne dla kontrahentów, cenniki w różnych walutach i zestawy produktów?
Klienci i zamówienia
Tu ustala się przebieg, a nie tylko zakres danych. Jak wygląda aktywacja konta, czy sklep sprawdza kontrahenta w systemie firmowym przed jej udzieleniem, kto o tym decyduje. W którą stronę płyną zamówienia i czy potrzebny jest import w drugą stronę, a jeśli tak, to czy tylko historyczny, czy również bieżący. Czy do konta przypisuje się opiekuna handlowego i skąd ta informacja pochodzi.
Faktury i rozliczenia
Obszar najczęściej pomijany w pierwszej rozmowie i najbardziej wrażliwy. Kwoty netto i brutto, data wystawienia, termin płatności, rozliczenia częściowe i całościowe, informacja o zaległościach, kredyt kupiecki i płatności odroczone. Każda z tych pozycji zmienia to, co klient widzi po zalogowaniu, więc żadnej nie da się dołożyć „przy okazji” później.
Warstwa techniczna
Dopiero na końcu wybór metody z czterech opisanych wyżej, wraz z ustaleniem, kto dostarcza dokumentację, kto daje dostęp do środowiska testowego i kto po stronie systemu firmowego odpowiada za zmiany w jego interfejsie.
Kto jest źródłem prawdy i jak trzymać powiązanie
Architektura integracji sprowadza się do dwóch rozstrzygnięć i oba są bardziej biznesowe niż techniczne.
Pierwsze to źródło prawdy, ustalane osobno dla każdej danej, a nie raz dla całości. Cena zwykle pochodzi z systemu firmowego, stan magazynowy z magazynu, kartoteka klienta bywa dzielona, a status przesyłki przychodzi od przewoźnika. Brak tej decyzji nie objawia się od razu. Wychodzi przy pierwszym konflikcie, gdy dwa systemy znają tę samą wartość i każdy uważa swoją za aktualną.
Drugie to sposób trzymania powiązania. Zasada jest prosta i warto ją traktować jak warunek wejścia: każda encja musi mieć identyfikator po obu stronach. Sklep zapisuje u siebie identyfikator kontrahenta i zamówienia nadany przez system firmowy, a system firmowy trzyma numer zamówienia ze sklepu jako numer zewnętrzny. Bez tego dopasowywanie odbywa się po danych opisowych, czyli po nazwisku, adresie albo kwocie, i psuje się przy pierwszej literówce.
Do tego dochodzi decyzja o rytmie. Dane, które muszą być natychmiastowe, czyli zwykle zamówienia, idą zdarzeniowo. Dane, które mogą się spóźnić o godzinę, czyli stany, ceny czy limity kupieckie, idą cyklicznie. Przy większych katalogach przebieg cykliczny trzeba dzielić na porcje, bo bez tego po prostu nie przechodzi. Wydajnościową stronę tego zagadnienia rozwijamy w tekście o kosztownych awariach w szczycie sprzedażowym.
I rzecz ostatnia, banalna, a pomijana w połowie specyfikacji: wszystkie odpowiedzi z błędami muszą trafiać do logu. Integracja bez logu jest nieserwisowalna, bo przy zgłoszeniu nie da się odtworzyć, co właściwie poszło w świat.
Mapowanie danych, czyli gdzie projekt rozstrzyga się naprawdę
Jeśli z całego tekstu warto zapamiętać jedną rzecz, to tę: integracje rzadko wywracają się na kodzie. Wywracają się na danych.
Pusty klucz mapowania. Powiązanie produktu trzyma się na kodzie, referencji albo numerze EAN. Zdarza się, że eksport zamówień przestaje działać, bo w katalogu brakuje wypełnionego klucza, i bywa, że dotyczy to znacznej większości asortymentu, mimo że integracja przeszła testy na próbce. Testy przechodzą, bo do testów wybiera się produkty kompletne. Zanim wycenisz projekt, policz, ile pozycji ma ten klucz faktycznie wypełniony. To zapytanie do bazy na kilka minut, a wynik potrafi przestawić cały harmonogram.
Warianty. Trzeba ustalić przed startem, czy limity i stany są globalne dla produktu, czy osobne dla każdego wariantu, oraz czy w systemie firmowym warianty w ogóle istnieją jako osobne kartoteki. Najprostsze zabezpieczenie to wymuszenie unikalności numeru EAN albo referencji na poziomie pojedynczego wariantu. Ta jedna decyzja usuwa całą klasę późniejszych problemów.
Format zamiast wartości. Bywa, że stan magazynowy przychodzi jako tekst z jednostką, a nie jako liczba. Przy prostym parsowaniu kończy się to wyzerowaniem dostępności całego asortymentu albo cichym zapisem błędnej wartości. Dlatego każde pole liczbowe z zewnątrz trzeba walidować, a nie zakładać, że przyjdzie w oczekiwanej postaci.
Ceny i podatki. Gdy dwa systemy liczą cenę samodzielnie, podsumowania zamówień przestają się zgadzać, bo różnią się zaokrągleniami i momentem doliczenia podatku. Rozstrzygnięcie, które zwykle działa: jedna strona przekazuje cenę netto i osobno wartość podatku, druga niczego nie przelicza.
Wszystkie cztery punkty prowadzą do tego samego wniosku. Projekt integracyjny zaczyna się od porządkowania katalogu, nie od pisania kodu, a stan danych warto sprawdzić w ramach audytu technicznego, zanim ustali się termin wdrożenia.
Warunki brzegowe, których nie widać w wycenie
Osobna kategoria opóźnień, wspólna dla wszystkich czterech metod. Żaden z tych punktów nie jest problemem programistycznym, a potrafią zabrać więcej czasu niż sama implementacja.
- Ruch wychodzący z serwera. Timeout, który wygląda na błąd aplikacji, potrafi okazać się zablokowanym ruchem wychodzącym na niestandardowych portach. Warto to sprawdzić na początku, a nie po dwóch dniach diagnostyki, zwłaszcza gdy ta sama integracja działa na środowisku testowym.
- Czas życia tokena. Jeśli uwierzytelnianie opiera się na tokenie, trzeba wiedzieć, na jak długo jest wydawany i jak go odświeżyć. Zdarza się, że dokumentacja tego nie podaje, a integracja przestaje działać po kilku dniach od uruchomienia.
- Interfejs po drugiej stronie się zmienia. Bywa, że zapytanie działające trzy tygodnie wcześniej zaczyna zwracać błąd, bo dostawca zmienił coś u siebie bez zapowiedzi. Integracja jest zależnością zewnętrzną o cudzym cyklu wydawniczym i trzeba to wpisać w plan utrzymania.
- Dokumentacja bywa niepełna. Zdarza się, że wskazany adres w ogóle nie występuje w oficjalnej dokumentacji, a przykładowe zapytanie nie zawiera danych, które system przyjmuje jako obowiązkowe. Praca zaczyna się wtedy od odtworzenia kontraktu na podstawie odpowiedzi, a nie od jego lektury.
- Środowisko testowe jako warunek startu. To najczęstsza przyczyna przestojów. Bez dostępu do środowiska, na którym można wykonać próbne wywołanie, projekt nie rusza, a oczekiwanie na ten dostęp bywa dłuższe niż cała implementacja.
Praktyczny wniosek dla harmonogramu: dostęp do środowiska testowego i potwierdzenie ruchu wychodzącego powinny być pierwszymi zadaniami w projekcie, a nie czynnościami przy wdrożeniu na produkcję.
Obsługa błędów jest decyzją biznesową
W specyfikacjach na pytanie „co zrobić, gdy wywołanie się nie uda” pada zwykle odpowiedź „ponowić i zapisać w logu”. To nie jest odpowiedź, bo nie rozstrzyga niczego, co trzeba rozstrzygnąć.
Przy każdej integracji trzeba podjąć trzy decyzje, a nie jedną.
- Moment wywołania. Kiedy dokładnie sklep ma odezwać się do drugiego systemu. Najczęściej sensowną granicą jest zmiana statusu na opłacone, bo przekazywanie zamówień nieopłaconych zaśmieca system firmowy.
- Zachowanie przy powodzeniu. Co się zapisuje i co się zmienia. Zwykle identyfikator z drugiego systemu oraz status mówiący, że realizacja ruszyła.
- Zachowanie przy niepowodzeniu. Ile razy ponawiać, co zrobić z zamówieniem, którego po tych próbach nadal nie udało się przekazać, i kto się o tym dowiaduje. Ponawianie w nieskończoność nie ma sensu, bo przy danych po prostu błędnych żadna kolejna próba nie przejdzie. Sprawdza się osobny status wyjątku, który wyciąga takie zamówienie na wierzch listy, zamiast chować je w logu.
Ostatni punkt jest najważniejszy, bo dotyczy pieniędzy. Zamówienie, które nie dotarło do systemu firmowego i o którym nikt nie wie, jest zamówieniem niezrealizowanym.
Kiedy integracja wymusza zmiany w samym sklepie
Bywa, że wymaganie systemu nadrzędnego zderza się z tym, jak PrestaShop liczy dane, i wtedy integracja przestaje być integracją, a staje się przebudową.
Dobrym przykładem jest rabat. PrestaShop obsługuje rabat na poziomie całego koszyka albo przez reguły cenowe dla produktów, ale nie rozbija rabatu ogólnego na poszczególne pozycje zamówienia. Jeśli system po drugiej stronie wymaga właśnie takiego rozbicia, żeby poprawnie zaksięgować dokument, logikę trzeba napisać od podstaw i zmienić w czterech miejscach naraz: w koszyku na froncie, w edycji zamówienia w panelu, w historii zamówień na koncie klienta oraz w danych wychodzących do drugiego systemu. Pominięcie któregokolwiek z nich daje niespójność, którą zauważy dopiero księgowość.
Wniosek na etapie analizy jest taki, że wymagania dotyczące formatu dokumentu po stronie systemu firmowego trzeba poznać przed wyceną, bo potrafią przenieść projekt z kategorii „integracja” do kategorii „zmiana w silniku sklepu”. Pocieszające jest to, że taka praca zwykle daje się zamknąć w osobnym, wielokrotnie używalnym komponencie, więc kolejny klient z tym samym wymaganiem dostaje je już jako gotowy element.
Ile to trwa
Uczciwa odpowiedź brzmi: sama implementacja pojedynczego, dobrze zdefiniowanego kierunku wymiany danych to rząd wielkości dni roboczych, nie tygodni. Tygodnie i miesiące robią się z trzech innych rzeczy: z analizy, w której ustala się zakres z powyższej listy, z jakości danych w katalogu oraz z oczekiwania na dostępy i odpowiedzi drugiej strony. Dlatego wycena podana przed analizą jest wyceną kodu, a nie projektu, i prawie zawsze rozmija się z rzeczywistością.
Odbiór integracji
Integracja ma własne kryteria odbioru i warto wpisać je do harmonogramu jako osobny punkt, a nie podpunkt odbioru sklepu.
Na środowisku przedprodukcyjnym, na sucho i przed puszczeniem ruchu, sprawdza się: synchronizację z systemami zewnętrznymi w obie strony, wykonanie zadań cyklicznych o zaplanowanych porach, zgodność stanów magazynowych po przebiegu oraz zachowanie przy celowo wprowadzonym błędzie. Na koniec przegląda się logi, bo ich pustka jest tak samo podejrzana jak nadmiar wpisów.
Osobno warto sprawdzić zachowanie integracji w konfiguracji wielosklepowej, jeśli taka u Was działa. Moduł nieświadomy wielu sklepów w jednej instancji będzie działał w sklepie podstawowym i cicho gubił dane w pozostałych, nie zwracając przy tym żadnego błędu. Piszemy o tym szerzej w tekście o architekturze multistore.
Z czym już to robiliśmy
Doświadczenie w integracjach mierzy się liczbą systemów, z którymi zespół faktycznie się zderzył, bo każdy z nich ma własne dziwactwa. Po naszej stronie są przepracowane połączenia z systemami klasy ERP i magazynowymi, między innymi Comarch XL i Optima, Sage Symfonia, WAPRO WFMag, Streamsoft Prestiż, Insert Subiekt GT i Subiekt NEXO, Enova oraz Navireo, a także mapowanie statusów z SAP i wymiana z inną platformą sprzedażową jako systemem nadrzędnym.
Do tego dochodzą integracje innego typu: marketplace’y, hurtownie, wyszukiwarki produktowe, systemy opinii, marketing automation, rejestry publiczne używane do weryfikacji kontrahenta oraz analityka. W katalogu mamy kilkadziesiąt modułów integracyjnych, a nowe połączenia budujemy na wspólnym szkielecie ze sterownikami, więc pod kolejny system pisze się warstwę tłumaczącą jego dane, a nie całą mechanikę od nowa.
Pełny zakres prac i lista systemów są na stronie integracji PrestaShop.
