Jak połączyć magazyn z BaseLinkerem przez API: kto jest źródłem prawdy dla stanów towaru i jak działają ponowienia po błędzie wymiany danych ze sklepem.
BaseLinker zbiera zamówienia z wielu kanałów sprzedaży w jednym panelu, a magazyn potrzebuje z niego tylko tego, co da się spakować. Studio WMS.net nie zastępuje tego panelu. Rezerwuje towar na lokalizacji, prowadzi kompletację i wydanie, a wynik odsyła do BaseLinkera. Od 2024 roku historia marki wymienia integracje z platformami e-commerce, wśród nich z Baselinkerem i Shoperem.
Ogólny przepływ danych między platformą a magazynem opisuje strona o integracji WMS z platformami e-commerce, a układ całego magazynu sklepu strona o WMS dla e-commerce. Tutaj schodzimy niżej: do metod API i do decyzji, które trzeba podjąć przed pierwszą linią kodu. Dane o API pochodzą z dokumentacji BaseLinkera (stan na 6.10.2026). Serwis działa dziś także pod marką Base.com, ale dokumentacja nadal stoi pod adresem api.baselinker.com.
Co BaseLinker przekazuje do magazynu
Jedno API, wiele źródeł zamówień i osobna metoda na każdy rodzaj danych.
Zapytania do API wysyła się metodą POST na adres api.baselinker.com/connector.php, z nazwą metody i parametrami w formacie JSON. Token użytkownika podaje się w nagłówku X-BLToken. Limit wynosi 100 zapytań na minutę, więc o tempie integracji decyduje kolejka, a nie pojedyncze wywołanie.
Każde zamówienie niesie informację o źródle. Metoda getOrderSources wylicza typy źródeł, wśród nich Allegro i połączone sklepy, a pole order_source w odpowiedzi getOrders mówi, skąd zamówienie przyszło. Dla magazynu źródło ma znaczenie drugorzędne: każde potwierdzone zamówienie trafia do tej samej kolejki. Wpływa dopiero na to, co wraca do kupującego, na przykład na numer przesyłki, który opisuje strona o integracji WMS z Allegro.
Metoda getOrders zwraca najwyżej 100 zamówień naraz, więc większy zbiór pobiera się partiami od ostatniej daty potwierdzenia. Zamówienia niepotwierdzone mogą mieć niepełne dane. Dlatego zlecenie wydania powstaje dopiero po potwierdzeniu.
| Dane | Kierunek | Metoda API | Ograniczenie z dokumentacji |
|---|---|---|---|
| Nowe zamówienia | BaseLinker → WMS | getOrders, getJournalList | do 100 zamówień na zapytanie; dziennik obejmuje 3 dni |
| Stan dostępny | WMS → BaseLinker | updateInventoryProductsStock | do 1000 produktów na zapytanie |
| Status zamówienia | WMS → BaseLinker | setOrderStatus | statusy definiuje użytkownik, lista z getOrderStatusList |
| Etykieta i numer przesyłki | BaseLinker ↔ WMS | createPackage, getLabel | etykieta w wybranym formacie, na przykład pdf lub zpl |
| Zwrot | BaseLinker → WMS | getOrderReturns | do 100 zwrotów na zapytanie |
Przepływ zamówienia od BaseLinkera do kuriera
Siedem etapów w trzech systemach, z jasnym rozdziałem odpowiedzialności.
Zamówienie zmienia właściciela kilka razy. Zaczyna w BaseLinkerze, na czas kompletacji i pakowania przechodzi do magazynu, potem wraca po etykietę, a kończy u przewoźnika. Schemat pokazuje, który etap należy do którego systemu.
W Studio WMS.net zamówienie przyjmuje postać zlecenia wydania ZWZ, w którego nagłówku stoją odbiorca i przewoźnik. Kompletację prowadzi aplikacja magazynowa na Androida, a przy pakowaniu na podstawie ZWZ powstaje dokument WZ. Zasady pracy na hali opisuje strona o kompletacji zamówień.
Stany i źródło prawdy
Gdy dwa systemy liczą sztuki, jeden z nich musi mieć ostatnie słowo.
WMS widzi skany i lokalizacje, więc tylko on wie, ile sztuk leży na półce, a ile jest już zarezerwowane. BaseLinker odpowiada za treść zamówienia i za ofertę. Do oferty powinien trafiać stan dostępny, czyli towar na półce pomniejszony o rezerwacje, a jego opis znajdziesz na stronie o stanach magazynowych.
Metoda updateInventoryProductsStock przyjmuje stany w podziale na magazyny BaseLinkera, do 1000 produktów w jednym zapytaniu. Odpowiedź zawiera licznik zaktualizowanych pozycji oraz ostrzeżenia z identyfikatorami produktów, których nie udało się zmienić. Zmiany wysyła się więc paczkami i czyta ostrzeżenia, zamiast zużywać limit na jedną pozycję w zapytaniu.
| Dane | Źródło prawdy | Powód |
|---|---|---|
| Treść zamówienia, płatność, adres | BaseLinker | Zmienia się po stronie kupującego, nie magazynu |
| Stan fizyczny i lokalizacja | WMS | Tylko magazyn widzi skany i dokumenty |
| Rezerwacja pod zamówienie | WMS | Powstaje przy zleceniu wydania |
| Stan dostępny w ofercie | WMS liczy, BaseLinker publikuje | Oferta ma pokazywać półkę pomniejszoną o rezerwacje |
| Status realizacji | WMS zmienia, BaseLinker pokazuje | Etap pracy wynika z dokumentu magazynowego |
Stan dostępny w ofercie liczy jeden system, ten, który zna rezerwacje. Dwie reguły przeliczania działające naraz kończą się rozjazdem, którego nikt nie wyjaśni po fakcie.
Dla towarów o małym stanie ustawia się zapas bezpieczeństwa, którego oferta nie pokazuje. Po inwentaryzacji do BaseLinkera wysyła się pełną nową wartość, a nie różnicę, bo powtórzenie takiego zapytania niczego nie psuje. Wielkość zapasu bezpieczeństwa ustala analiza.
Statusy zamówień i ich mapowanie
Lista statusów należy do sprzedawcy, więc jej odpowiedniki w WMS trzeba uzgodnić.
Statusy zamówień definiuje użytkownik BaseLinkera, a ich listę zwraca metoda getOrderStatusList. Zmianę wykonuje setOrderStatus z numerem zamówienia i identyfikatorem statusu. Magazyn nie wyśle więc słowa „spakowane”, tylko identyfikator statusu, który sprzedawca wcześniej założył. Tabela podaje punkt wyjścia, a nazwy w ostatniej kolumnie są przykładami.
| Zdarzenie w WMS | Dokument | Przykładowy status |
|---|---|---|
| Towar zarezerwowany, zlecenie zapisane | ZWZ | W realizacji |
| Kompletacja i pakowanie zakończone | WZ w toku | Spakowane |
| Paczka przekazana kurierowi | WZ zamknięty | Wysłane |
| Brak towaru na lokalizacji | ZWZ z uwagą | Wstrzymane do wyjaśnienia |
Jedna reguła chroni przed błędem: przed każdą zmianą statusu integracja odczytuje bieżący status zamówienia. Jeżeli sprzedawca anulował zamówienie w trakcie kompletacji, WMS tego nie nadpisuje. Zwalnia rezerwację i zgłasza towar do odłożenia na lokalizację.
Etykiety kurierskie i numer przesyłki
Dane paczki są znane dopiero przy pakowaniu, więc etykieta powstaje na końcu.
Etykietę można zlecić przez BaseLinker. Metoda createPackage zakłada przesyłkę w systemie kuriera dla wskazanego zamówienia i wymaga co najmniej wagi jednej paczki, a wymiary podaje się w centymetrach. W odpowiedzi wraca identyfikator przesyłki i jej numer. Metoda getLabel zwraca etykietę zakodowaną w base64 w jednym z formatów, wśród których są pdf i zpl. Format drukarki termicznej pozwala wysłać etykietę prosto na stanowisko pakowania.
Druga droga omija BaseLinker. Integracja programu magazynowego ze Studio Spedycja.net rejestruje numery listów przewozowych i kojarzy je z dokumentami WZ, a etykiety z kodem kreskowym drukuje drukarka kodów kreskowych, jak opisuje strona o wysyłce przez firmy kurierskie. Wtedy numer przesyłki trzeba osobno przekazać do BaseLinkera razem ze statusem. Wybór drogi zależy od tego, gdzie skonfigurowano umowę z przewoźnikiem.
Zwroty od kupujących
Zwrot ma w BaseLinkerze własny status i zawsze wskazuje zamówienie.
Metoda getOrderReturns zwraca zwroty od wskazanej daty, po 100 na zapytanie. Zwrot wskazuje zamówienie, z którego powstał, i ma własny status z osobnej listy. Integracja wiąże go z zamówieniem po numerze, więc magazynier skanujący paczkę widzi, co kupujący zamawiał.
Magazyn przyjmuje paczkę dokumentem przyjęcia i odkłada towar na wydzieloną lokalizację poza stanem dostępnym. Dopiero ocena decyduje, czy wraca on na półkę sprzedażową. Decyzję o zwrocie pieniędzy podejmuje sprzedawca poza magazynem, na przykład w systemie ERP połączonym z WMS.
Błędy i ponowienia
Po awarii integracja ma dojść do poprawnego stanu bez ręcznej interwencji.
Każda wymiana ma jawny klucz, którym jest numer zamówienia z BaseLinkera. Dzięki temu ponowione pobranie nie tworzy drugiego zlecenia, a powtórzona zmiana statusu nie zmienia wyniku. Dziennik zdarzeń getJournalList obejmuje tylko ostatnie 3 dni i zwykle do 100 zdarzeń w odpowiedzi. Metoda działa też dopiero po włączeniu w ustawieniach API konta, a bez tego zwraca pustą odpowiedź.
| Sytuacja | Skutek | Reakcja integracji |
|---|---|---|
| Przekroczony limit 100 zapytań na minutę | Zapytania nie przechodzą | Kolejka z odstępem i grupowanie stanów po 1000 pozycji |
| Ostrzeżenie przy produkcie w odpowiedzi o stanach | Oferta zostaje ze starą liczbą | Ponowienie samej pozycji, alarm po kolejnej porażce |
| Przerwa w pracy dłuższa niż 3 dni | Dziennik nie obejmuje zaległych zdarzeń | Pełne pobranie getOrders od ostatniej potwierdzonej daty |
| Zamówienie niepotwierdzone | Dane mogą być niepełne | Zlecenie nie powstaje do czasu potwierdzenia |
| Ten sam numer zamówienia pobrany dwa razy | Zdwojone zlecenie wydania | Odrzucenie drugiej próby po kluczu zamówienia |
Błąd, który zniknął po ponowieniu, nadal trzeba zapisać w dzienniku integracji. Bez zapisu nikt nie sprawdzi, czy wraca.
Kto wykonuje integracje po stronie Studio WMS.net
Usługa Windows na serwerze, a zakres dla sklepu potwierdza analiza.
Integracje w Studio WMS.net, w tym z platformami sprzedażowymi, wykonuje usługa Windows SSService.exe. Instaluje się ją na serwerze. Usługa realizuje zadania, a wymiana danych z innym systemem jest jednym z nich.
W przypadku BaseLinkera wymiana idzie przez API serwisu, czyli przez metody opisane na tej stronie, na przykład getOrders i createPackage. Strona opisuje drogę wymiany, a nie listę gotowych ustawień. Które metody wchodzą w zakres dla danego sklepu, potwierdza analiza przedwdrożeniowa. Zachowanie przy awarii opisuje sekcja o błędach i ponowieniach.
Co ustala analiza wdrożeniowa
Cztery decyzje, od których zależy zakres prac.
Zakres integracji dla konkretnego sklepu wynika z analizy przedwdrożeniowej. Na liście decyzji są cztery pozycje:
- Lista statusów - które statusy BaseLinkera odpowiadają etapom ZWZ i WZ oraz kto może je zmieniać ręcznie.
- Identyfikacja towaru - po czym łączy się indeks WMS z produktem w BaseLinkerze. Odpowiedź getOrders zawiera pola sku i ean, więc wybór musi być jeden i spójny.
- Tempo wymiany - jak często pobiera się zamówienia i wysyła stany przy limicie 100 zapytań na minutę.
- Przewoźnicy - kto zakłada przesyłkę i skąd pochodzi etykieta dla każdego kuriera.
Zakres prac programistycznych zależy od liczby i złożoności systemów, z którymi magazyn ma się komunikować, a zasady wyceny opisuje cennik.