Przejdź do głównej zawartości

Różnice względem BaseLinkera

Beel API dąży do pełnej zgodności, ale model danych Sellrocket różni się od BaseLinkera. Poniżej różnice, które mogą wpłynąć na Twoją integrację. Które identyfikatory (statusy, źródła zamówień, konta kurierskie, pola dodatkowe) mogą być takie same jak w BaseLinkerze, opisuje Identyfikatory z BaseLinkera.

  • Źródło zamówienia to połączenie Beel, do którego należy token. Parametr custom_source_id jest dopasowywany do połączeń typu „Pozostałe kanały sprzedaży” (po zewnętrznym ID), a jeśli żadne nie pasuje — do połączenia o takim ID. Gdy nic nie pasuje, zamówienie trafia do połączenia tokenu. Jeśli pasuje kilka połączeń, zamówienie nie zostanie dodane (błąd).
  • external_order_id — parametr spoza API BaseLinkera. Pozwala podać identyfikator zamówienia w systemie źródłowym; jest widoczny w Sellrocket jako numer zamówienia w źródle.
  • date_add jest wymagane. Zamówienia z date_add starszym niż 2 miesiące są odrzucane z błędem ERROR_SAVING_ORDER.
  • order_status_id musi być istniejącym statusem w instancji (pobierz listę przez getOrderStatusList), inaczej ERROR_BAD_ORDER_STATUS_ID.
  • date_confirmed jest ustawiane na moment dodania zamówienia.
  • Imię i nazwisko są rozdzielane z pola pełnej nazwy. Adres jest zapisywany w całości w polu ulicy (numer domu i lokalu nie są wydzielane).
  • paid: true tworzy jedną płatność na pełną kwotę zamówienia (produkty + dostawa).
  • Maksymalnie 100 zamówień na wywołanie. Bez date_confirmed_from wyniki są sortowane rosnąco po ID — stronicuj przez id_from. Z date_confirmed_from — rosnąco po dacie potwierdzenia; stronicuj, przesuwając date_confirmed_from na datę ostatniego pobranego zamówienia.
  • filter_order_source_id działa tylko razem z filter_order_source — samo filter_order_source_id zwraca ERROR_BAD_ORDER_SOURCE. Jeśli filtr źródła pasuje do kilku połączeń, zwracany jest ERROR_CONNECTIONS_COUNT.
  • Pola bez odpowiednika w Sellrocket mają wartości stałe: order_source_info = "-", order_page = "", pick_state = 0, pack_state = 0.
  • shop_order_id jest wypełniane tylko dla zamówień ze sklepów internetowych.
  • Pola produktu storage, storage_id, variant_id, warehouse_id, location, auction_id, attributes, weight pochodzą z pól elastycznych pozycji zamówienia (zapisywanych m.in. przez addOrder i addOrderProduct).
  • payment_done ustawia łączną kwotę wpłaty (jak w BaseLinkerze), ale po wywołaniu zamówienie ma jedną płatność na tę kwotę — jeśli miało ich kilka, pozostałe są usuwane.
  • payment_done = 0 nie zmienia płatności.

Pola dodatkowe zamówień i zwrotów to pola elastyczne Sellrocket. extra_field_id 1 i 2 są zawsze stałe — to „Pole dodatkowe 1/2” zamówienia (extra_field_1, extra_field_2). ID pozostałych pól Beel API wylicza w jeden z dwóch sposobów — zależnie od opcji „ID pól elastycznych w Beel API”:

Tryb extra_field_id ID jak w BaseLinkerze
ID pola elastycznego (opcja włączona) identyfikator definicji pola elastycznego tak — możesz je nadać przy zakładaniu pola
ID wyliczone z nazwy pola (domyślnie) duża liczba zależna od nazwy technicznej pola nie — nie da się go ustawić

Jak rozpoznać tryb: wywołaj getOrderExtraFields. ID od 1 000 000 000 wzwyż (albo nadane ręcznie, np. z BL) oznaczają tryb „ID pola elastycznego”. Nieregularne duże liczby (np. 53157978) — tryb „ID wyliczone z nazwy pola”.

custom_extra_fields w getOrders i getOrderReturns są zwracane tylko z include_custom_extra_fields: true — domyślnie false, tak samo jak w BaseLinkerze.

Nowa instancja — pola jeszcze nie istnieją:

  1. Upewnij się, że instancja działa w trybie „ID pola elastycznego”. Jeśli nie — klient zgłasza do wsparcia Sellrocket włączenie opcji „ID pól elastycznych w Beel API”.
  2. Pobierz listę pól z BaseLinkera klienta: getOrderExtraFields (i getOrderReturnExtraFields, jeśli używasz zwrotów) — extra_field_id, name, editor_type, options.
  3. Załóż w Sellrocket definicje pól z id równym extra_field_id z BL — zobacz Pola elastyczne → Własne ID. Nazwę techniczną (fieldName) wybierz na stałe — później nie da się jej zmienić.
  4. Sprawdź w Beel API:
    • getOrderExtraFields zwraca ID jak w BaseLinkerze,
    • setOrderFields z custom_extra_fields: { "135": "B2B" } zapisuje wartość,
    • getOrders z include_custom_extra_fields: true zwraca custom_extra_fields z tymi kluczami.

Pola już istnieją i mają wartości: nie usuwaj pól — usunięcie definicji usuwa wszystkie jej wartości. Klient zgłasza do wsparcia Sellrocket nadanie istniejącym polom ID z BaseLinkera — zmiana jest przeprowadzana bez utraty wartości. Przekaż listę: nazwa techniczna pola (fieldName) → ID z BaseLinkera. Jeśli instancja działa w trybie „ID wyliczone z nazwy pola”, w tym samym zgłoszeniu klient prosi o włączenie opcji „ID pól elastycznych w Beel API”.

  • W trybie „ID wyliczone z nazwy pola” lista z getOrderReturnExtraFields może nie zgadzać się z kluczami custom_extra_fields w getOrderReturns. W trybie „ID pola elastycznego” są spójne.
  • Pola dodatkowe produktów (getInventoryExtraFields, text_fields) to pola złożone w PIM, nie pola elastyczne. extra_field_id na liście pól jest zawsze wyliczany z nazwy pola (nie da się go ustawić). Odczyt produktu (getInventoryProductsData) zwraca klucz z nazwy pola — pole nazwane extra_field|extra_field_<ID z BL> daje klucz extra_field_<ID z BL> jak w BaseLinkerze. Zapis kluczem z BaseLinkera w addInventoryProduct jest pomijany bez błędu, a przy tworzeniu nowego produktu pola dodatkowe nie są zapisywane — wartości zapisuj przez PIM API. Zobacz Pola dodatkowe produktów.
  • addOrderReturn działa w dwóch trybach:
    • z order_id — zwrot do istniejącego zamówienia; podane order_product_id musi wskazywać pozycję tego zamówienia (inaczej ERROR_BAD_ORDER_ITEM_ID), a pozycja bez order_product_id jest dodawana do zwrotu jako nowa,
    • bez order_id — zwrot samodzielny; pozycje nie mogą mieć order_product_id (inaczej ERROR_BAD_ORDER_ID).
  • status_id zwrotu i status_id każdej pozycji są wymagane i muszą istnieć w instancji (inaczej ERROR_BAD_STATUS_ID). Beel API nie udostępnia listy statusów zwrotów — pobierz ją przez REST API → Zwroty.
  • Kwota zwrotu jest liczona z pozycji (price_brutto × quantity) i delivery_price. refunded: true oznacza zwrot całej tej kwoty — nie można podać innej kwoty refundacji.
  • getOrderReturns zwraca maksymalnie 100 zwrotów na wywołanie — zawężaj wyniki filtrami (id_from, date_from). Pola reference_number i admin_comments są puste, date_in_status = 0; shop_order_id, order_return_source i order_return_source_id nie są zwracane.
  • getInventoryWarehouses zwraca warehouse_type = "bl" i liczbowe warehouse_id. W stanach, lokalizacjach i liście magazynów katalogu (getInventories) magazyn ma klucz bl_{id}.
  • reservations jest zawsze false, a rezerwacje w getInventoryProductsStock zawsze 0.
  • Stare API magazynowe (getProductsList itd.) działa na domyślnym katalogu, widocznym jako bl_1.
  • Stan zestawu jest wyliczany ze składników — updateInventoryProductsStock odrzuca zmianę stanu zestawu (zwraca ostrzeżenie dla tego produktu, pozostałe są aktualizowane).
  • To samo dotyczy produktu głównego z wariantami — jego stan wynika ze stanów wariantów; aktualizuj stany wariantów.
  • addInventoryProduct z is_bundle nie może ustawiać stanów, a składniki muszą należeć do tego samego katalogu.

Nie są zwracane zdarzenia typu: połączenie zamówień (5), rozdzielenie (6), faktura (7), paragon (8), czarna lista (15), kopia zamówienia (17) oraz typy 19 i 20. Do śledzenia zmian możesz użyć też historii zamówień w REST API.

Parametr courier_code — obsługiwane wartości (kolumna getLabel pokazuje, czy dla przesyłek tego kuriera można pobrać etykietę przez Beel API):

Kurier courier_code getLabel
InPost Paczkomaty paczkomaty tak
InPost Kurier inpost, inpost_courier, inpostkurier tak
DPD dpd, dpd_locker tak
UPS ups tak
GLS gls tak
DHL dhl tak
FedEx fedexpl tak
Poczta Polska pocztapolska, poczta_polska tak
Świat Przesyłek swiatprzesyl tak
Allegro (Wysyłam z Allegro) all, all_courier, allegrokurier tak
Erli erli, erlipro tak
Euro Hermes eurohermes tak
Olza Logistic olzalogistic tak
Packeta packeta tak
Global24 goglobal24 tak
Apaczka apaczka tak
Paxy czechlog tak
Orlen Paczka ruch tak
Geis geis, geiscz, geissk nie
Zadbano zadbano, dts nie

getLabel pobiera też etykiety przesyłek Geodis (pekaes) i Ambro Express (ambro) utworzonych poza Beel API — tych kurierów nie obsługuje createPackage.

account_id wskazuje połączenie kurierskie w Sellrocket (pobierz przez getCourierAccounts) — dopasowywane po zewnętrznym ID, a potem po ID połączenia. Bez account_id używane jest pierwsze połączenie danego kuriera.

Błędy: nieobsługiwany courier_code — ERROR_COURIER_CODE; brak połączenia tego kuriera w instancji lub niepasujące account_id — ERROR_UNSUPPORTED; niepoprawne dane paczki dla kuriera — ERROR_COURIER.

Beel API nie ma osobnego licznika zapytań — działa w ramach limitów platformy Sellrocket. Gdy limit zostanie przekroczony, metoda zwraca ERROR_BLOCKED_TOKEN, a error_message podaje godzinę (czas polski), po której można ponowić zapytanie — około minuty. Odczekaj ten czas i ponów wywołanie, podobnie jak w BaseLinkerze.