Baselinker API otwiera całe konto na zewnątrz: zamówienia, stany, ceny, przesyłki i faktury da się czytać i zapisywać własnym kodem. To jeden adres, do którego wysyłasz zapytanie z nazwą metody, a w odpowiedzi dostajesz dane w formacie JSON - bez klikania w panelu, bez eksportów do Excela, bez ręcznego przepisywania. W praktyce oznacza to, że wszystko, co widzisz w Baselinkerze, można podłączyć do własnego sklepu, systemu księgowego, magazynu albo raportu.
Poniżej: co API naprawdę potrafi, czego nie trzeba pisać kodem, gdzie gotowe integracje się kończą i jakie pułapki wysadzają takie wdrożenia w powietrze.
Czym jest Baselinker API
Baselinker API to interfejs, przez który zewnętrzny program rozmawia z Twoim kontem Baselinkera. Nie ma tu wielu adresów ani skomplikowanej autoryzacji - jest jeden punkt wejścia i token z ustawień konta.
| Element | Jak to działa |
|---|---|
| Adres | jeden endpoint connector.php na api.baselinker.com |
| Logowanie | token z panelu, przesyłany w nagłówku X-BLToken |
| Zapytanie | POST z dwoma polami: method (nazwa funkcji) i parameters (dane w JSON) |
| Odpowiedź | JSON ze statusem SUCCESS albo ERROR i kodem błędu |
| Limit | rzędu stu zapytań na minutę na token - limity bywają zmieniane, sprawdź dokumentację przed projektowaniem |
| Zakres tokenu | dostęp praktycznie do całego konta, nie da się go zawęzić do jednej funkcji |
Ostatni wiersz jest ważniejszy, niż wygląda: token to klucz do wszystkich zamówień i danych klientów. Trzymaj go w zmiennych środowiskowych po stronie serwera - nigdy w kodzie strony ani w publicznym repozytorium.
Zanim napiszesz kod: co Baselinker robi sam
Sporo automatyzacji Baselinkera nie wymaga API w ogóle. W panelu są wbudowane automatyczne akcje - reguły typu „gdy pojawi się opłacone zamówienie z tego źródła, zmień status, wystaw dokument i przygotuj list przewozowy”. Ustawia się je klikając.
Zasada, którą stosuję przy każdej wycenie: najpierw sprawdzam, czy tego nie da się zrobić regułą w panelu. Kod pisze się dopiero tam, gdzie reguły nie sięgają - bo kod trzeba potem utrzymywać, a klikana reguła utrzymuje się sama. Jeśli Twoja lista potrzeb to w większości „przesuwaj statusy i drukuj etykiety”, możliwe, że nie potrzebujesz programisty, tylko porządków w konfiguracji. Powiem Ci to wprost na diagnozie.
Zamówienia w Baselinkerze - co się da
Zamówienia to najczęściej wykorzystywana część API. Da się je czytać, tworzyć, edytować i przestawiać między statusami.
getOrders- pobiera zamówienia (maksymalnie sto w jednym zapytaniu), z filtrami po dacie, statusie i źródlegetJournalList- dziennik zdarzeń: nowe zamówienie, zmiana statusu, edycja, opłacenie. To jest właściwy sposób na pobieranie przyrostoweaddOrder- wrzucenie zamówienia z zewnątrz, na przykład z własnego panelu B2B albo z formularza na stroniesetOrderFields,setOrderStatus,setOrderPayment- dopisanie danych, przesunięcie zamówienia dalej i odnotowanie wpłaty
Poprawne pobieranie nowych zamówień wygląda tak:
- Zapamiętujesz identyfikator ostatniego przetworzonego wpisu z dziennika zdarzeń
- Co kilka minut pytasz o zdarzenia nowsze od zapamiętanego i dociągasz pełne dane tych zamówień, które Cię interesują
- Zapisujesz u siebie identyfikator Baselinkera razem z własnym numerem - to Twoja jedyna obrona przed duplikatami
- Dopiero po udanym zapisie przesuwasz zapamiętany identyfikator do przodu
Ostatni punkt to nie drobiazg. Jeśli przesuniesz wskaźnik przed zapisem, jeden nieudany przebieg oznacza zamówienie, którego nikt nigdy nie zobaczy - a takie rzeczy wychodzą na jaw dopiero przy reklamacji.
Baselinker udostępnia też webhooki, czyli powiadomienia wysyłane w momencie zdarzenia. Są wygodne, ale nie zwalniają z odpytywania dziennika: powiadomienie może nie dojść, gdy Twój serwer akurat się restartuje. Dobre wdrożenie ma webhook dla szybkości i cykliczne sprawdzanie dziennika jako siatkę bezpieczeństwa.
Magazyn Baselinkera i stany magazynowe
Tu najczęściej rodzi się bałagan, bo Baselinker rozróżnia dwa różne magazyny i łatwo je pomylić.
Katalog wewnętrzny to produkty trzymane w samym Baselinkerze: czytasz je metodami getInventories i getInventoryProductsData, a zmieniasz przez updateInventoryProductsStock i updateInventoryProductsPrices (paczkami, rzędu tysiąca produktów na zapytanie).
Magazyn zewnętrzny to Twój sklep podpięty do Baselinkera - WooCommerce, PrestaShop, Shoper. Tu działają getExternalStorages, getExternalStorageProductsData i updateExternalStorageProductsQuantity.
Zanim napiszesz linijkę kodu, odpowiedz na jedno pytanie: gdzie jest prawda o stanie magazynowym? Jedno miejsce, nie dwa. Jeśli stan liczy Baselinker, sklep tylko go odbiera. Jeśli liczy Twój magazyn albo ERP, Baselinker dostaje gotową liczbę i nie ma prawa jej zmieniać. Dwukierunkowa synchronizacja „na wszelki wypadek” to najprostszy sposób na sprzedanie towaru, którego nie ma - dwa systemy odejmują tę samą sztukę, każdy raz.
Praktyczne zasady: wysyłasz tylko produkty, których stan faktycznie się zmienił, a nie cały katalog co dziesięć minut; pełne przeliczenie robisz raz na dobę w nocy; każda paczka zmian ma zapis w logu razem z odpowiedzią API.
Wysyłka, dokumenty i faktury
API obsługuje też to, co dzieje się po skompletowaniu zamówienia: createPackage zamawia przesyłkę u kuriera, getLabel zwraca etykietę do wydruku, getOrderPackages sprawdza numery listów. Po stronie dokumentów są addInvoice, getInvoices i getSeries - wystawianie faktur i pilnowanie numeracji.
Warto rozdzielić dwie rzeczy. Wystawienie dokumentu można spokojnie automatyzować. Wysyłka faktury do KSeF, który obowiązuje już wszystkich przedsiębiorców, to inna liga - błędnie wysłany dokument kosztuje realny czas na korekty. W układach, które buduję, automat przygotowuje komplet, a wysyłkę zatwierdza człowiek jednym kliknięciem. Jak to poukładać, rozpisałem przy własnej integracji z KSeF i w tekście o połączeniu WooCommerce z ERP i KSeF.
Gdzie kończą się gotowe integracje
Wtyczki i wbudowane połączenia Baselinkera obsługują scenariusz typowy: sklep w popularnym silniku, standardowy produkt, standardowa wysyłka. Kod pisze się wtedy, gdy Twój przypadek wychodzi poza ten schemat.
| Sytuacja | Czego brakuje w gotowcu |
|---|---|
| Zestawy i komplety | stan zestawu zależy od kilku produktów naraz - trzeba go przeliczać własną regułą |
| Ceny per kanał | inna marża na Allegro, inna w sklepie, inna dla stałego klienta B2B |
| Własny panel klienta | zamówienia z panelu B2B na WordPressie muszą trafić do Baselinkera przez addOrder |
| Nietypowy silnik sklepu | sklep na własnym kodzie albo mocno przerobiony - brak gotowego łącznika |
| Raporty i marża | zysk po kosztach zakupu i prowizjach kanałów liczysz u siebie |
| Reguły biznesowe | „wstrzymaj zamówienie, jeśli klient ma nieuregulowaną poprzednią fakturę” |
Jeśli rozważasz jeszcze, czy Baselinker jest właściwym miejscem na spinanie kanałów, zebrałem porównanie w tekście o alternatywach dla Baselinkera, a samo podłączanie Allegro do różnych silników opisałem w artykule o integracji marketplace’ów.
Pułapki, które kosztują najwięcej
Kolejność od najczęstszej - wszystkie widziałem na żywo.
- Brak zabezpieczenia przed duplikatem - powtórzone zapytanie tworzy drugie zamówienie albo drugą fakturę. Każda operacja zapisu musi mieć własny klucz i sprawdzenie, czy już się wykonała
- Ignorowanie limitu zapytań - integracja działa na testach z pięcioma produktami i pada przy pięciu tysiącach
- Brak obsługi błędu - API odpowiedziało błędem, kod poleciał dalej, dane rozjechały się w ciszy
- Stan liczony w dwóch miejscach - opisany wyżej klasyk, kończy się sprzedażą towaru, którego nie ma
- Brak logów - gdy po miesiącu stany się rozjeżdżają, bez logów nie ustalisz nawet, kiedy się zaczęło
- Zero testów na kopii - pierwsze uruchomienie od razu na koncie produkcyjnym, na żywych zamówieniach
Integracja jest jak instalacja elektryczna: przez pierwszy tydzień wszystko działa, a różnica między dobrą a złą robotą wychodzi w trzecim miesiącu. Dlatego to, co oddaję, ma zawsze log operacji i alert, gdy synchronizacja przestaje chodzić - standardowy element rozwoju i optymalizacji sklepu, nie dodatek za dopłatą.
Od czego zacząć i ile to kosztuje
Zaczynam od bezpłatnej diagnozy: patrzę na Twoje konto Baselinkera, sklep i listę rzeczy robionych ręcznie, a potem mówię wprost, co załatwi reguła w panelu, a co wymaga kodu. Często pierwsza część jest większa - i dobrze, bo to najtańsza automatyzacja, jaka istnieje.
Jeśli zostaje realna robota programistyczna, dostajesz wycenę na piśmie przed startem, z zakresem rozpisanym na punkty. Typowe wdrożenia w tej skali - spięcie sklepu z Baselinkerem po własnych regułach, panel B2B wysyłający zamówienia do systemu, przeliczanie stanów zestawów - mieszczą się w widełkach projektów fixed-bid: 5000-10000 zł netto. Mniejsze rzeczy schodzą poniżej tego progu, a integracje wpięte w większy projekt sklepu na WooCommerce wyceniam łącznie. Sam abonament Baselinkera zależy od liczby zamówień, a cenniki bywają aktualizowane - to sprawdź u źródła.
Najczęstsze pytania
Czy Baselinker API jest darmowe? Dostęp do API jest elementem konta, nie osobno płatnym dodatkiem - token generujesz w ustawieniach. Płacisz za abonament Baselinkera według jego cennika, a osobnym kosztem jest napisanie i utrzymanie integracji po Twojej stronie.
Czy da się połączyć Baselinker z WooCommerce bez programisty? Tak, podstawowe połączenie ustawia się w panelu i przy typowym sklepie to wystarcza: zamówienia spływają, stany wracają. Kod jest potrzebny dopiero przy zestawach, cenach zależnych od kanału, panelu B2B albo regułach, których panel nie obsługuje.
Ile trwa zbudowanie takiej automatyzacji? Prosta synchronizacja w jedną stronę to zwykle kilka dni roboczych razem z testami na kopii. Wdrożenia z fakturami, zestawami i własnymi regułami to kilka tygodni - termin podaję w wycenie, po obejrzeniu konta i sklepu.
Co się stanie, gdy Baselinker zmieni swoje API? Zmiany się zdarzają i integracja może przestać działać poprawnie, nawet gdy Ty niczego nie ruszasz. Dlatego każde wdrożenie ma logi i powiadomienie o błędach, a klienci na stałej opiece mają reakcję wliczoną w abonament - Basic 1000, Pro 2000, Premium 3500 zł netto miesięcznie.
Powiązane: Baselinker - alternatywy i porównanie · Własna integracja z KSeF · Sklepy e-commerce