BaseLinker API wdrożenie bez ruszania produkcji
Warstwa techniczna integracji z BaseLinkerem: token z panelu w nagłówku żądania, jeden punkt wejścia z nazwą metody w treści, pobieranie zamówień przyrostowo po dacie i identyfikatorze, kolejka na limity zapytań, webhook jako sygnał i dopytanie stanu metodą. Pilot chodzi na koncie testowym, z wyłączoną komunikacją do klientów.
- 1 punkt wejściacały interfejs stoi pod jednym adresem, a operację wskazujesz nazwą metody w treści żądania, nie ścieżką zasobu
- 100 zamówieńtyle najwyżej zwraca jedna odpowiedź według dokumentacji, dlatego pobieramy przyrostowo z kursorem, a nie od początku przy każdym uruchomieniu
- 14 dnityle zwykle mija od warsztatu do pierwszego strumienia na produkcji, sprawdzonego wcześniej na koncie testowym
Problem
Dlaczego integracja z BaseLinkerem nie zachowuje się jak zwykłe REST API?
Kto siada do tego interfejsu z przyzwyczajeniami z klasycznego REST, ten szuka adresów zasobów i czasowników HTTP. Nie znajdzie ich. Żądania idą metodą POST na jeden punkt wejścia (connector.php), a to, co ma się stać, wskazujesz nazwą metody w treści żądania. Kontraktem są więc nazwy metod i ich parametry, nie ścieżki. Klient napisany pod ścieżki zasobów trzeba przepisać od zera, zwykle po dwóch dniach zdziwienia.
Token generujesz w panelu BaseLinkera i przekazujesz w nagłówku każdego żądania. Stąd dwie decyzje, które lepiej podjąć przed pierwszą linią kodu: co dokładnie tym tokenem wolno zrobić, czyli czy integracja tylko czyta, czy także zapisuje, oraz gdzie ten token fizycznie leży. Token wklejony na sztywno w scenariusz, bez rotacji i bez wiedzy, kto go ma, jest problemem organizacyjnym, nie technicznym.
Trzecia rzecz to skala odpytywania. Interfejs zwraca zamówienia paczkami, a liczbę zapytań ogranicza po swojej stronie. Dokładne wartości podaje oficjalna dokumentacja BaseLinker API i sprawdzamy je przed wdrożeniem, bo bywają zmieniane. Wniosek jest niezależny od liczby: scenariusz, który przy każdym uruchomieniu przeciąga wszystko od początku, działa na koncie z dwustu zamówieniami i przestaje działać na koncie z dwudziestu tysiącami.
- Klient napisany pod ścieżki zasobów, których w tym interfejsie nie ma
- Pełne przeciąganie zamówień co godzinę, które wyczerpuje limit w szczycie sezonu
- Odrzucone żądanie ginie bez śladu, bo nikt nie zapisał ani treści, ani odpowiedzi
- Token wpisany na sztywno w scenariusz, bez rotacji i bez ewidencji, kto go ma
Dlaczego teraz
Webhook czy odpytywanie: co powinno uruchamiać przepływ?
Webhooki konfiguruje się w panelu BaseLinkera dla zdarzeń takich jak nowe zamówienie czy zmiana statusu, a panel wysyła wtedy żądanie POST na Wasz adres. To skraca reakcję z minut do sekund i dlatego z nich korzystamy. Traktujemy je jednak jako sygnał, nie jako źródło prawdy: to samo zdarzenie może przyjść dwa razy, przyjść w innej kolejności albo nie przyjść wcale, gdy Wasz adres akurat nie odpowiadał. Po sygnale dopytujemy aktualny stan metodą i dopiero to zapisujemy.
Odpytywanie zostaje jako siatka bezpieczeństwa i jako sposób nadrabiania zaległości. Robimy je przyrostowo: pytamy o zamówienia od ostatniej przetworzonej daty potwierdzenia i od ostatniego przetworzonego identyfikatora, a kursor trzymamy po naszej stronie. Uruchomienie po awarii podejmuje pracę tam, gdzie ją zostawiło, zamiast zaczynać od pierwszego zamówienia w historii konta.
Sam kształt interfejsu upraszcza wdrożenie. Jeden adres, jeden format żądania i token w nagłówku znaczą, że w n8n albo Make wystarczy węzeł HTTP z tokenem w nagłówku, a dołożenie kolejnej operacji to nowa nazwa metody, nie nowa integracja. Własny kod piszemy tam, gdzie potrzebna jest logika przekształcania danych albo spięcie z systemem, którego żadne z tych narzędzi nie obsługuje.
Co się zmienia
Co dostaje osoba, która to potem utrzymuje?
Jeden klient obsługuje wszystkie operacje
Token w nagłówku, nazwa metody w treści, ten sam format odpowiedzi. Zamówienia, produkty, stany i przesyłki idą przez ten sam kod, więc dołożenie kolejnej operacji nie jest nowym projektem.
Jeden adres i jeden format żądania dla zamówień, produktów, stanów i przesyłek
Pobieranie przyrostowe zamiast pełnego przeciągania
Kursor z ostatnią przetworzoną datą potwierdzenia i identyfikatorem zamówienia trzymamy po naszej stronie. Każde uruchomienie bierze wyłącznie to, co przyszło później, a restart po awarii nie zaczyna od początku historii.
Kursor z datą i identyfikatorem zamiast pełnego pobrania przy każdym uruchomieniu
Limit zapytań pod kontrolą kolejki
Żądania wychodzą z kolejki z odstępem, odczyty grupujemy, a po odrzuceniu ponawiamy z rosnącym opóźnieniem. Limit czytamy z dokumentacji przed startem i mierzymy realne zużycie w pilocie.
Kolejka z odstępem i ponowieniami zamiast pętli, która wysyła żądania tak szybko, jak umie
Webhook jako sygnał, stan z metody
Zdarzenie z panelu uruchamia przepływ, ale zapisujemy to, co zwróciła metoda, a nie to, co przyszło w webhooku. Zapis idzie po identyfikatorze zamówienia, więc ten sam sygnał odebrany dwa razy daje ten sam wynik.
Powtórzony webhook nie tworzy drugiego dokumentu ani drugiej wiadomości do klienta
Jeden proces zapisujący stan magazynowy
Przy sprzedaży w kilku kanałach naraz nadsprzedaż bierze się z dwóch procesów piszących stan w tej samej minucie. Ustalamy jeden proces zapisujący i jedno źródło prawdy, a zmiany wysyłamy paczkami zamiast po sztuce.
Zmiany stanu wysyłane paczkami z jednego procesu, kolejność ustalona, nie przypadkowa
Błąd widać razem z żądaniem
Każde odrzucone wywołanie ląduje w kolejce błędów z nazwą metody, treścią żądania, odpowiedzią interfejsu i znacznikiem czasu. Osoba z zespołu ponawia je sama, bez zgłoszenia do nas.
Metoda, żądanie i odpowiedź w jednym wpisie, gotowe do ponowienia
A u Ciebie
Co, jeśli u nas nikt jeszcze nie ruszał tego interfejsu?
Cztery zdania, które słyszymy przy tej integracji najczęściej, i to, co na nie odpowiadamy.
Mamy programistę, poradzi sobie sam.
Bardzo możliwe i nie będziemy przekonywać, że jest inaczej. Wywołanie metody jest łatwe. Trudne jest to, co obok: kursor pobierania, kolejność zapisów między systemami, ponowienia po odrzuconym żądaniu i zachowanie przy powtórzonym webhooku. Wtedy warsztat kończy się dokumentem z listą metod, parametrów i przypadków brzegowych, który Wasz programista realizuje bez nas.
Nie damy tokenu do konta firmie z zewnątrz.
Nie musicie. Pracujemy na koncie testowym, a token produkcyjny zostaje w Waszej instancji n8n, Make albo na Waszym serwerze. Po naszej stronie potrzebna jest tylko wiedza, jakie dane wolno wysyłać dalej i jakie metody wchodzą w grę. Po wdrożeniu token rotujecie, a integracja pracuje dalej.
Boimy się, że test wyśle prawdziwe wiadomości do klientów.
Dlatego pierwsze przejście jest wyłącznie odczytem, bez ani jednego zapisu. Potem pilot chodzi z wyłączoną komunikacją do klientów i z zapisami skierowanymi na konto testowe. Na produkcję przełączamy dopiero wtedy, gdy porównanie wyników z panelem się zgadza.
Mamy scenariusz w Make, tylko regularnie się wysypuje.
Wtedy nie przepisujemy go od nowa. Czytamy log błędów i szukamy przyczyny w trzech miejscach: brak kursora, brak ponowień, przekroczony limit zapytań. Czasem winny jest jeden parametr o złym formacie. W takim wypadku sprawa kończy się na warsztacie i poprawce, nie na nowym wdrożeniu.
- Interfejs BaseLinkera
- token z panelu, jeden punkt wejścia, metody zamówień, produktów, stanów i przesyłek, webhooki z panelu
- Warstwa automatyzacji
- n8n, Make, Zapier, własne integracje przez API
- Sprzedaż
- Allegro, Shopify, WooCommerce, PrestaShop
- Księgowość
- Fakturownia, iFirma, Subiekt, Comarch Optima
- Dane i logi
- BigQuery, Google Sheets, bazy SQL, GA4
- Alerty i praca zespołu
- Slack, Microsoft 365, Google Workspace
Operacje w BaseLinker API i o czym pamiętać przy każdej
Siedem operacji, od których zwykle zaczyna się integracja, razem ze sposobem realizacji i pułapką, która przy każdej z nich wraca najczęściej. Wartości liczbowe limitów czytamy z dokumentacji producenta i potwierdzamy w pilocie.
| Operacja | Jak to realizujemy | O czym pamiętać |
|---|---|---|
| Uwierzytelnienie | token z panelu w nagłówku każdego żądania | zakres tokenu ustalamy przed startem, token zostaje w Waszej instancji narzędzia |
| Pobranie nowych zamówień | metoda zamówień z filtrem po dacie potwierdzenia i identyfikatorze | jedna odpowiedź to paczka, według dokumentacji do 100 zamówień, więc idziemy z kursorem |
| Reakcja na zdarzenie | webhook z panelu jako sygnał, stan dopytany metodą | sygnał może przyjść dwa razy albo nie przyjść, zapis po identyfikatorze zamówienia |
| Zmiana statusu zamówienia | wywołanie metody statusu po potwierdzonym zapisie w drugim systemie | kolejność ma znaczenie: najpierw dokument, potem status, inaczej po błędzie gubi się krok |
| Aktualizacja stanów | paczkowa aktualizacja z jednego procesu zapisującego | dwa procesy piszące stan w tej samej minucie to nadsprzedaż, źródło prawdy musi być jedno |
| Przesyłka i etykieta | metoda przesyłek po skompletowaniu danych adresowych i gabarytu | brak wagi albo wymiarów odrzuca żądanie, więc walidujemy dane przed wywołaniem |
| Błąd i przekroczony limit | ponowienie z rosnącym odstępem, żądanie i odpowiedź w logu | limit według dokumentacji, sprawdzamy przed wdrożeniem; zapisów nie ponawiamy bez klucza |
Pierwsze wdrożenie obejmuje zwykle dwie albo trzy operacje z tej listy. Reszta wchodzi tym samym torem, po pomiarze pierwszych.
Jak to robimy
Pięć kroków od tokenu w panelu do integracji na produkcji
Każdy krok kończy się czymś, co możesz ocenić, zanim zdecydujesz o następnym. Pierwsze dwa nie zmieniają ani jednego rekordu.
Warsztat
Tydzień. Spisujemy cel, a z niego listę metod, które są do niego potrzebne. Sprawdzamy, co już robią akcje automatyczne i webhooki w panelu, jaki jest zakres tokenu, ile zamówień na dobę przechodzi przez konto i jakie systemy stoją po drugiej stronie. Wynikiem jest dokument, nie kod.
Konto testowe i pierwsze odczyty
Wyłącznie odczyt, ani jednego zapisu. Sprawdzamy realne kształty danych na Waszym koncie: zamówienie bez numeru NIP, zamówienie zagraniczne, produkt wariantowy z osobnym stanem na wariant, zwrot, zamówienie z brakującym gabarytem. To one decydują o walidacji, a nie przykłady z dokumentacji.
Pilot obok produkcji
Uruchamiamy kursor, kolejkę zapytań i ponowienia. Komunikacja do klientów wyłączona, zapisy kierowane na konto testowe. Porównujemy wynik przepływu z tym, co widać w panelu, i mierzymy realne zużycie limitu zapytań przy Waszym wolumenie.
Produkcja i przekazanie
Przełączamy z monitoringiem błędów. Zostaje wyłącznik po Waszej stronie, kolejka błędów z treścią żądania i odpowiedzią oraz spisane metody, parametry i miejsce kursora. Token rotujecie, a osoba z zespołu uczy się czytać i zamykać kolejkę błędów.
Pomiar po 30 i 90 dniach
Patrzymy na liczby z logu: ile żądań odrzucił interfejs, ile poszło ponowień, ile zdarzeń wpadło do wyjątków, czy kursor kiedykolwiek się cofnął. Dopiero po tym dokładamy kolejną operację, tym samym torem.
Przed i po
Jak zmienia się dzień osoby, która utrzymuje tę integrację
Przedtem
- Scenariusz przy każdym uruchomieniu przeciąga zamówienia od początku historii konta
- Po odrzuconym żądaniu nikt nie wie, czy zamówienie poszło dalej, czy stanęło w połowie
- Webhook przyszedł dwa razy, więc klient dostał dwie wiadomości i dwa dokumenty
- Zmianę parametru sprawdza się na produkcji, bo nie ma gdzie indziej
Po zmianie
- Uruchomienie bierze tylko to, co przyszło po ostatnim przetworzonym zamówieniu
- Odrzucone żądanie leży w kolejce błędów razem z treścią i odpowiedzią, gotowe do ponowienia
- Powtórzony sygnał daje ten sam wynik, bo zapis idzie po identyfikatorze zamówienia
- Zmiany sprawdzasz na koncie testowym, z wyłączoną komunikacją do klientów
Pierwszy strumień działa na produkcji zwykle 14 dni po warsztacie. Liczbę odrzuconych żądań, ponowień i wyjątków oceniamy po 30 i po 90 dniach, na wskaźnikach spisanych przed startem.
Dla osoby, która to zamawia
Co z tego ma osoba odpowiedzialna za systemy
Bierzesz na siebie integrację z narzędziem, w którym stoją zamówienia, więc pytanie nie brzmi „czy da się wywołać metodę”. Brzmi „co się stanie, gdy jedno wywołanie nie przejdzie w piątek wieczorem”. Po wdrożeniu odpowiedź jest w dokumentacji i w kolejce błędów, a nie w pamięci jednej osoby, która akurat to pisała.
Druga rzecz dotyczy rozliczenia z decyzji. Pierwsze przejście jest samym odczytem, pilot chodzi obok produkcji z wyłączoną komunikacją do klientów, a token produkcyjny nie wychodzi z Waszej infrastruktury. Jeśli po warsztacie okaże się, że integracja jest zbędna, kończy się na dokumencie i tygodniu pracy.
- Token zostaje po Waszej stronie, my pracujemy na koncie testowym
- Pierwsze przejście bez ani jednego zapisu, potem pilot obok produkcji
- Kolejka błędów, wyłącznik i log żądań zostają u Was po wdrożeniu
- Metody, parametry i miejsce kursora spisane, więc integracja nie wisi na jednej osobie
Ile to kosztuje
Warsztat ma cenę jawną, integracja wycenę po nim
Warsztat procesowy kosztuje 2500 zł netto za tydzień. Przy jednym interfejsie zwykle wystarcza jeden tydzień, bo zakres jest wąski: cel, lista metod, kursor, limity i obsługa błędów. Integrację wyceniamy po warsztacie, gdy wiadomo, ile operacji wchodzi w grę i w jakim stanie są systemy po drugiej stronie.
Abonament BaseLinkera oraz koszt scenariuszy w Make albo n8n płacisz dostawcom bezpośrednio, według ich cenników. Tak samo koszt użycia modeli, jeśli dochodzi agent AI. Nie doliczamy prowizji i nie pośredniczymy w płatnościach.
Warsztat procesowy
2500 zł netto
za tydzień, przy jednym interfejsie zwykle jeden
Zamknięta całość. Kończy się dokumentem technicznym, który Wasz programista może zrealizować bez nas.
- Lista metod potrzebnych do celu, z parametrami i formatem odpowiedzi
- Przegląd tego, co już robią akcje automatyczne i webhooki w panelu
- Zakres tokenu i decyzja, jakie dane wolno wysyłać dalej
- Plan pobierania przyrostowego, kolejki zapytań i obsługi błędów
- Wskaźniki do pomiaru po 30 i 90 dniach
- Najczęściej wybierany
Warsztat i integracja przez API
Wycena po warsztacie
zakres wynika z liczby metod i systemów po drugiej stronie
Najczęściej wybierany wariant. Działający strumień w 2 do 4 tygodni od warsztatu, uruchomiony najpierw na koncie testowym.
- Wszystko z warsztatu
- Klient z tokenem w nagłówku, kolejką zapytań i ponowieniami
- Pobieranie przyrostowe z kursorem po dacie i identyfikatorze
- Webhooki jako sygnał, stan dopytywany metodą, zapis po identyfikatorze
- Pilot na koncie testowym, monitoring i kolejka błędów
- Szkolenie osoby, która ma potem czytać log i ponawiać żądania
Integracja i agent AI
Wycena po warsztacie
dla zespołów, które pytają o dane z zamówień codziennie
Wszystko z integracji plus BOND, firmowy agent AI, który odpowiada z tych danych zwykłym zdaniem. Wdrożenie agenta zajmuje około 2 miesiące.
- Wszystko z integracji przez API
- Hurtownia z zamówieniami, statusami i logiem żądań
- Agent AI odpowiada z tych danych w 5 do 10 sekund
- Alerty o odrzuconych żądaniach i o zbliżaniu się do limitu zapytań
- Dostęp dla obsługi i dla osoby odpowiedzialnej za systemy
Warsztat kończy się dokumentem, który obroni się bez nas: listą metod z parametrami, planem pobierania przyrostowego i opisem obsługi błędów. Jeśli na warsztacie okaże się, że cel załatwiają akcje automatyczne i webhooki z samego panelu, mówimy to wprost i pokazujemy, jak je ustawić. Sprawa kończy się wtedy na warsztacie, a nie na integracji, której nie potrzebujecie.
Najczęstsze pytania
Czy BaseLinker API to zwykłe REST API?
Nie w tym sensie, w jakim REST rozumie się zwyczajowo. Żądania idą metodą POST na jeden punkt wejścia, a operację wskazujesz nazwą metody w treści żądania, nie ścieżką zasobu ani czasownikiem HTTP. Odpowiedź wraca w formacie JSON. Kontraktem są nazwy metod i ich parametry, więc klient napisany pod ścieżki zasobów nie zadziała i trzeba go napisać inaczej.
Jak wygląda uwierzytelnianie i gdzie trzymamy token?
Token generujesz w panelu BaseLinkera i przekazujesz go w nagłówku każdego żądania, w polu X-BLToken. Token produkcyjny zostaje w Waszej instancji n8n, Make albo na Waszym serwerze, a my pracujemy na koncie testowym. Zakres uprawnień ustalamy na warsztacie, bo od niego zależy, czy integracja tylko czyta, czy także zapisuje. Po wdrożeniu token rotujecie i integracja pracuje dalej.
Czy BaseLinker ma webhooki i czy wystarczą same webhooki?
Webhooki konfiguruje się w panelu dla zdarzeń takich jak nowe zamówienie albo zmiana statusu, a panel wysyła żądanie POST na Wasz adres. Same nie wystarczą. To samo zdarzenie może przyjść dwa razy, w innej kolejności albo nie przyjść, gdy Wasz adres nie odpowiadał. Dlatego traktujemy webhook jako sygnał, po nim dopytujemy stan metodą, a odpytywanie przyrostowe zostaje jako siatka bezpieczeństwa.
Ile zamówień pobiera jedno zapytanie i jak paginować?
Według dokumentacji jedna odpowiedź obejmuje do 100 zamówień, i sprawdzamy tę wartość przed wdrożeniem, bo bywa zmieniana. Dlatego nie paginujemy numerem strony, a idziemy przyrostowo: pytamy o zamówienia od ostatniej przetworzonej daty potwierdzenia i od ostatniego przetworzonego identyfikatora. Kursor trzymamy po naszej stronie, więc restart po awarii nie zaczyna od pierwszego zamówienia w historii.
Jak radzicie sobie z limitem zapytań?
Żądania wychodzą z kolejki z odstępem, odczyty grupujemy w jedno wywołanie tam, gdzie metoda to pozwala, a po odrzuceniu ponawiamy z rosnącym opóźnieniem. Wartość limitu czytamy z dokumentacji producenta przed wdrożeniem i mierzymy realne zużycie w pilocie, przy Waszym wolumenie zamówień. Zapisów nie ponawiamy w ciemno, tylko po sprawdzeniu stanu albo z kluczem, który zabezpiecza przed dublem.
Jak testujecie integrację bez ruszania produkcji?
W trzech etapach. Pierwsze przejście jest samym odczytem, bez ani jednego zapisu, na Waszych prawdziwych kształtach danych. Potem pilot chodzi obok obecnego procesu z wyłączoną komunikacją do klientów i z zapisami skierowanymi na konto testowe. Na produkcję przełączamy dopiero wtedy, gdy porównanie wyników przepływu z panelem się zgadza, i robimy to z monitoringiem błędów.
Jak interfejs traktuje produkty wariantowe i ich stany?
Produkt wariantowy ma produkt nadrzędny i warianty pod nim, a każdy wariant ma własny identyfikator, własny stan magazynowy i własny kod EAN. Aktualizacja stanu wymaga więc wskazania właściwego wariantu, nie samego produktu nadrzędnego. Na koncie testowym sprawdzamy to na Waszym realnym produkcie, bo od struktury katalogu zależy, czy stan da się zapisywać paczkami.
Co się dzieje, gdy jedno wywołanie nie przejdzie?
Wpada do kolejki błędów z nazwą metody, treścią żądania, odpowiedzią interfejsu i znacznikiem czasu. Ponowienia idą z rosnącym odstępem, a kolejność zapisów jest ustalona tak, żeby po błędzie nie zgubić kroku: najpierw dokument w drugim systemie, potem zmiana statusu w BaseLinkerze. Osoba z Waszego zespołu ponawia wpis sama, bez zgłoszenia do nas.
Przejdźmy przez jedno wywołanie na Waszym koncie testowym
Bezpłatna konsultacja trwa 30 minut. Mówisz, co ma się dziać po nowym zamówieniu i jakie systemy stoją po drugiej stronie, a my mówimy, które metody są do tego potrzebne i co przy nich zwykle wybucha. Nie musisz na tym etapie udostępniać konta ani generować tokenu.
Prowadzimy najwyżej dwa wdrożenia równocześnie, żeby przy każdym ktoś realnie siedział.
Umów bezpłatną konsultacjęPS. Jeśli Wasz scenariusz przy każdym uruchomieniu pobiera zamówienia od początku historii konta, to jest dokładnie ten problem: kwestia czasu, kiedy limit zapytań go zatrzyma. Kursor i kolejka załatwiają to raz. Piszesz do Pawła, założyciela, nie na skrzynkę zbiorczą.