Integracja API krok po kroku: jak połączyć sprzedaż z operacjami

Integruj proces, w którym te same dane są obecnie ręcznie przenoszone między sprzedażą a operacjami. API, czyli interfejs programistyczny aplikacji, pozwala systemom wymieniać żądania i odpowiedzi według uzgodnionego kontraktu; samo API nie określa, jak firma ma prowadzić zamówienie.

Rozrysuj jedną ścieżkę od produktu do obsługi posprzedażowej: publikacja oferty, przyjęcie zamówienia, płatność, rezerwacja, kompletacja, wysyłka, faktura i zwrot. Zaznacz ręczne przepisania, opóźnienia oraz miejsca, w których pracownik podejmuje decyzję. Najpierw automatyzuj przepływ o jasnym właścicielu i jednoznacznym warunku zakończenia.

Jeżeli kanał sprzedaży, magazyn i system obsługi zamówień mają wymieniać dane przez warstwę BaseLinker, poznaj zakres integracji z BaseLinkerem i sprawdź, które etapy procesu ta warstwa ma przejąć.

Źródłem prawdy dla pola powinien być jeden wskazany system, który ma prawo je zmieniać. Systemy podrzędne mogą otrzymywać kopię wartości, ale nie powinny bez reguły zwrotnej aktualizować tej samej informacji.

Tabela poniżej wskazuje przykładowego właściciela danych dla każdego pola i regułę rozstrzygania konfliktu. Dopasuj przypisanie do procesu oraz konfiguracji konkretnych systemów.

Tabela wyznacza właściciela, a nie konkretną konfigurację każdego produktu. Zapisz wyjątki, takie jak blokada ręcznej zmiany ceny lub korekta stanu po inwentaryzacji, zanim powstanie logika synchronizacji.

Przed projektowaniem przepływu sprawdź dokumentację producenta dla uwierzytelniania, operacji, limitów, wersji i środowiska testowego. Dla każdego systemu zanotuj adresy endpointów, wymagane zakresy dostępu, formaty żądań i odpowiedzi oraz warunki otrzymania błędów.

Lista kontroli dokumentacji:

• Metoda i endpoint dla odczytu, utworzenia, aktualizacji oraz anulowania danych.
• Sposób autoryzacji, ważność tokenów i zakres uprawnień.
• Limity zapytań, paginacja i sposób pobierania zmian od ostatniego odczytu.
• Dostępność webhooków, czyli powiadomień wysyłanych przez system po zdarzeniu.
• Identyfikatory zdarzeń i możliwość wykrywania duplikatów.
• Środowisko testowe, przykładowe odpowiedzi i różnice względem produkcji.
• Właściciel API i procedura zgłaszania zmian lub awarii.

Nie zakładaj, że wszystkie API mają webhooki albo środowisko testowe. Gdy system udostępnia tylko odczyt cykliczny, uwzględnij częstotliwość pobierania, okno zmian i sposób wykrywania rekordów usuniętych.

Przepływ danych określa kierunek, moment, identyfikator i reguły przetwarzania każdej zmiany. Opisz go jako zdarzenie wejściowe, walidację, zapis w systemie docelowym, potwierdzenie wyniku i obsługę błędu.

Tabela poniżej porządkuje decyzje projektowe dla pojedynczego zamówienia. Każdy etap powinien mieć uzgodniony warunek powodzenia i dalsze działanie po błędzie.

Idempotencja oznacza, że ponowienie identycznej operacji nie powinno powielić jej skutku. RFC 9110 określa metody HTTP PUT i DELETE jako idempotentne, a klientowi odradza automatyczne ponawianie żądania nieidempotentnego bez sposobu sprawdzenia, czy operacja została wykonana. Dla tworzenia zamówienia przez POST ustal unikalny klucz lub najpierw sprawdź, czy rekord już istnieje.

Zamówienie powinno zmniejszać dostępność dopiero zgodnie z uzgodnioną regułą rezerwacji w systemie magazynowym lub OMS. Rezerwacja przed potwierdzeniem płatności, po autoryzacji albo dopiero po opłaceniu to decyzja biznesowa, którą trzeba zapisać jako warunek procesu.

Przykładowy przepływ wygląda następująco: sklep wysyła zamówienie z trwałym ID, integrator sprawdza duplikat i kompletność SKU, OMS tworzy zamówienie, a WMS rezerwuje dostępny zapas. Po potwierdzeniu płatności proces przechodzi do kompletacji; anulowanie zwalnia rezerwację zgodnie z regułą magazynową, a zwrot przechodzi osobną ścieżkę oceny i przyjęcia towaru.

Podwójna rezerwacja może wystąpić, gdy system ponowi niejednoznaczne żądanie po timeout albo dwa kanały niemal równocześnie zamówią ostatnią sztukę. Użyj identyfikatora zamówienia jako klucza deduplikacji, a rezerwację wykonuj w systemie, który kontroluje wspólny stan. Przy timeout nie twórz drugiego zamówienia bez sprawdzenia rezultatu pierwszej próby.

Testy powinny potwierdzić poprawny przebieg zamówienia i bezpieczne zachowanie po błędach komunikacji. Sprawdź logikę na danych testowych obu dostawców, a każdy scenariusz wiąż z identyfikatorem korelacyjnym, który pozwala znaleźć zdarzenie w logach wszystkich systemów.

Tabela poniżej obejmuje scenariusze poprawne i błędne, które warto sprawdzić przed uruchomieniem. Wynik każdego testu powinien potwierdzić stan zamówienia oraz rezerwacji w systemach źródłowym i docelowym.

Po teście end-to-end sprawdź także aktualizację stanu z powrotem do sklepu. Sam kod HTTP 200 nie dowodzi, że wartość została prawidłowo zapisana w docelowym procesie.

Monitoring powinien pokazywać, które zdarzenie nie przeszło, w jakim systemie wystąpił błąd i kto ma je wznowić. Rejestruj identyfikator zamówienia, identyfikator korelacyjny, czas, endpoint, wynik walidacji i skróconą treść błędu; nie zapisuj w logach haseł, tokenów ani zbędnych danych osobowych.

Ustal kolejkę błędów z kategoriami: błąd danych, brak uprawnień, przekroczony limit, timeout i niedostępność systemu. Dla każdego typu określ, czy integrator może ponowić zdarzenie automatycznie, czy potrzebna jest korekta danych albo decyzja operatora. Microsoft zaleca, by przy ponawianiu metod nieidempotentnych sprawdzić dokumentację API lub zastosować mechanizm, który chroni przed powtórnym skutkiem.

Alert powinien wskazywać nazwę procesu i instrukcję wznowienia, a nie tylko komunikat "błąd API". Osoba dyżurna musi móc sprawdzić, czy system docelowy wykonał operację przed wznowieniem. Po naprawie zapisz przyczynę i rezultat, aby odróżnić awarię chwilową od błędu mapowania.

Efekt integracji mierzy się zmianą czasu i jakości obsługi procesu, a nie samą liczbą poprawnych odpowiedzi API. Zbierz wartości bazowe przed uruchomieniem i porównuj je po wdrożeniu przy tej samej definicji zamówienia oraz okresie pomiaru.

Tabela poniżej grupuje mierniki operacyjne, ich zakres i sposób interpretacji. Porównuj je z wartościami bazowymi zebranymi przed wdrożeniem.

Jeśli nie chcesz samodzielnie projektować mapowania i procesu, zleć połączenie systemów obsługiwanych przez BaseLinker po wcześniejszym uzgodnieniu zakresu systemów i testów. Przy API niewspieranym przez gotowy konektor potrzebny może być odrębny projekt integracyjny.

• Jak zintegrować zamówienia ze sklepu internetowego z systemem księgowym?
• API Shoper: jak działają integracje, uwierzytelnianie i limity
• IdoSell Bridge: modele integracji IdoSell z systemami magazynowo-księgowymi
• Co to jest BaseLinker, dlaczego firmy go wdrażają i kiedy się opłaca