Własny system do obsługi zamówień: zacznij od fundamentu, nie od zera

Ten tekst jest dla firm, które już zdecydowały, że chcą mieć własny system do obsługi zamówień. Jeśli jeszcze się zastanawiacie, czy w ogóle odchodzić od SaaS-u, najpierw przeczytaj własny system integracji czy SaaS. Tutaj zakładamy, że ta decyzja zapadła, i zajmujemy się kolejną. Piszecie wszystko sami czy zaczynacie od czegoś, co już istnieje?

Piszemy o tym z perspektywy ludzi, którzy przez ostatnie dwa lata budowali dokładnie taki fundament. Adaptery do PrestaShopa, Allegro czy InPostu to w tej pracy najmniejsza część. Najwięcej czasu zjadły rzeczy, których nie widać na żadnym demo.

Własny system do obsługi zamówień: trzy drogi

Pierwsza droga to kupić inne gotowe narzędzie. To najszybsze, ale zostajecie z tym samym problemem, przez który odchodzicie: system jest wynajęty, płacicie od zamówień albo od obrotu, a nietypowe potrzeby trafiają do kolejki dostawcy.

Druga to dedykowany system e-commerce pisany od zera, przez własny zespół albo software house. Macie pełną kontrolę, ale odpowiadacie też za każdą linijkę kodu, także za tę, która nie ma nic wspólnego z waszym biznesem.

Trzecia to budowa na otwartym fundamencie. Kod i dane są wasze, tak samo jak przy systemie pisanym od zera, ale warstwa techniczna już istnieje i obsługuje prawdziwe zamówienia. Wasz zespół pisze to, co jest specyficzne dla firmy.

Różnica między drugą a trzecią drogą sprowadza się do pytania, ile kosztuje warstwa techniczna. Najłatwiej to pokazać na przykładach z naszego kodu.

Co naprawdę zajmuje czas przy budowie integracji e-commerce

Integracja sklepu z marketplace’em od zera na początku wygląda na kilka wywołań API: pobierz zamówienia, utwórz je w sklepie, odeślij numer przesyłki. Problemy zaczynają się na produkcji.

Żadne zamówienie nie może zginąć

Worker się restartuje, marketplace odpowiada błędem, sieć znika na minutę. Dlatego każda integracja w OpenLinkerze pamięta, gdzie skończyła: dla Allegro to pozycja w dzienniku zdarzeń, dla PrestaShopa data ostatniej zmiany i numer zamówienia. Brzmi prosto, dopóki nie trafi się sklep, który odmawia sortowania zamówień po dacie zmiany. Takie sklepy się zdarzają, więc OpenLinker sam to wykrywa i przełącza się na odczyt po samym numerze zamówienia.

Zamówienie, które wraca

Zamówienie z Allegro trafia do PrestaShopa jako nowe zamówienie w sklepie. Przy kolejnym odczycie zamówień ze sklepu system widzi je jeszcze raz. Bez osobnego zabezpieczenia nadpisuje wtedy jego pochodzenie: w panelu kanałem sprzedaży staje się PrestaShop, choć e-mail kupującego jest z Allegro, a zamówienie wypada z synchronizacji statusów wysyłki. Złapaliśmy to na prawdziwych danych i od tego czasu OpenLinker rozpoznaje zamówienia, które sam wysłał.

„Zakończone” to nie to samo co „dotarło”

Jedno zamówienie może iść do kilku miejsc naraz, na przykład do dwóch sklepów. Jeśli jedno z nich odmówi, zadanie w tle i tak się kończy, a problem trzeba widzieć na poziomie konkretnego zamówienia i konkretnego celu. Dlatego OpenLinker osobno zapisuje stan zadania i stan synchronizacji, a panel operatora grupuje błędy i pozwala je ponowić pojedynczo albo zbiorczo.

Każdy system ma inne numery

Ten sam produkt ma inny numer w sklepie, w ofercie na Allegro i w ERP. OpenLinker trzyma jedną mapę tych powiązań. Zamówienie z produktem, którego jeszcze nie zmapowano, dostaje status „oczekuje na mapowanie”, zamiast po cichu wpaść w błąd.

Dostęp do API to osobny projekt

Dane dostępowe każdej integracji są zaszyfrowane. Tokeny OAuth Allegro trzeba odświeżać tak, żeby dwa procesy nie robiły tego jednocześnie, więc odświeżanie działa z blokadą. Do tego dochodzą limity zapytań, osobne dla każdej integracji i wspólne dla wszystkich procesów, z pierwszeństwem dla operacji, na które czeka człowiek. Webhooki przychodzą w dowolnej kolejności i czasem po kilka razy, więc każdy jest sprawdzany pod kątem podpisu i duplikatu.

Faktura czy paragon

Czy zamówienie dostaje fakturę, czy paragon, zależy od kraju dostawy i od tego, czy kupujący podał NIP. Gdy reguły nie rozstrzygają, OpenLinker wstrzymuje zamówienie i pokazuje powód, zamiast zgadywać. Status faktury w KSeF OpenLinker odczytuje sam.

Testy na prawdziwych systemach

Część błędów wychodzi dopiero na żywej instancji. Przykład z naszego stanowiska testowego: jeśli klucz API nie jest przypisany do sklepu, PrestaShop 9 zwraca błąd 503 „webservice is disabled”, choć API jest włączone. Dlatego testy integracyjne OpenLinkera uruchamiają w kontenerach prawdziwego PrestaShopa 9, Postgresa i Redisa.

Budowaliśmy to przez dwa lata, w ponad 1700 commitach. Stoi za tym ponad 70 spisanych decyzji architektonicznych, a każdy build przechodzi ponad 60 automatycznych kontroli. Tak wygląda podział pracy, gdy budujecie na OpenLinkerze:

Co piszecie sami

Zostają dwie rzeczy. Pierwsza to adaptery do systemów, których OpenLinker jeszcze nie obsługuje: waszego ERP, systemu magazynowego, marketplace’u bez oficjalnej integracji. Adapter implementuje jeden albo kilka portów, na przykład zamówienia, stany czy fakturowanie. Szkielet generuje jedno polecenie:

pnpm create-adapter acme-erp

Resztę opisuje przewodnik dla autorów wtyczek: dane dostępowe, OAuth, migracje bazy danych należące do wtyczki i testy. Jeśli system potrzebuje własnego ekranu, panel też przyjmuje wtyczki.

Druga rzecz to reguły biznesowe: kierowanie zamówień, wstrzymania, zasady wystawiania dokumentów. Adapter może też zadeklarować zupełnie nową możliwość, na przykład własny mechanizm wyceny. Jej obsługę w rdzeniu uzgadnia się wtedy z opiekunami projektu.

To wciąż system integracji open source na licencji Apache 2.0. Kod możecie czytać, zmieniać, a gdyby trzeba było, rozwijać dalej bez nas. Dane zostają na infrastrukturze, którą wybierzecie. Dlaczego rodzaj licencji ma przy tej decyzji znaczenie, pisaliśmy w tekście open source czy source-available.

Kto to zbuduje

Nie musicie budować sami. Chętnie wdrożymy, rozwiniemy i dostosujemy OpenLinkera do waszej firmy, od jednego adaptera po całe wdrożenie. Możecie też pracować z agencją, z którą już współpracujecie, albo z partnerem OpenLinkera (tak wygląda to od strony agencji), albo oprzeć się na własnych programistach. Gdy system staje się krytyczny, dochodzą SLA, Integration Assurance, czyli utrzymanie i gwarancja działania integracji przy zmianach API, oraz hosting zarządzany.

Jak to może wyglądać w dużej firmie, pokazaliśmy na fikcyjnej sieci sklepów z elektroniką, z salonami, hurtowniami i kilkunastoma marketplace’ami: omnichannel w handlu elektroniką.

Kiedy to się nie opłaca

Jeśli macie jeden sklep, jeden marketplace i standardowy proces, gotowe narzędzie będzie prostsze i tańsze w utrzymaniu. Jeśli wasz zespół nie pracuje w TypeScripcie, a nie chcecie partnera, fundament w TypeScripcie, NestJS, Reakcie, PostgreSQL i Redisie będzie dla was obcym kodem. A jeśli integracje są waszym produktem na sprzedaż, prawdopodobnie i tak będziecie chcieli mieć własny rdzeń.

OpenLinker jest jeszcze przed wersją 1.0, ale jest gotowy do produkcji i obsługuje już prawdziwe zamówienia. Działają m.in. PrestaShop, WooCommerce, Allegro, ERLI, InPost, DPD, Subiekt, KSeF, inFakt i eparagony.pl. Stany w wielu lokalizacjach i reguły cenowe dla kanałów mają już pierwszą wersję, a sprzedaż w salonach jest w planach. Aktualna lista jest na stronie integracji.

Kod jest na GitHubie, a panel można obejrzeć w demo na żywo. Jeśli chcecie porozmawiać o konkretnym wdrożeniu, napiszcie do nas przez stronę dla firm.