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.
addOrder
Dział zatytułowany „addOrder”- Źródło zamówienia to połączenie Beel, do którego należy token. Parametr
custom_source_idjest 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_addjest wymagane. Zamówienia zdate_addstarszym niż 2 miesiące są odrzucane z błędemERROR_SAVING_ORDER.order_status_idmusi być istniejącym statusem w instancji (pobierz listę przezgetOrderStatusList), inaczejERROR_BAD_ORDER_STATUS_ID.date_confirmedjest 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: truetworzy jedną płatność na pełną kwotę zamówienia (produkty + dostawa).
getOrders
Dział zatytułowany „getOrders”- Maksymalnie 100 zamówień na wywołanie. Bez
date_confirmed_fromwyniki są sortowane rosnąco po ID — stronicuj przezid_from. Zdate_confirmed_from— rosnąco po dacie potwierdzenia; stronicuj, przesuwającdate_confirmed_fromna datę ostatniego pobranego zamówienia. filter_order_source_iddziała tylko razem zfilter_order_source— samofilter_order_source_idzwracaERROR_BAD_ORDER_SOURCE. Jeśli filtr źródła pasuje do kilku połączeń, zwracany jestERROR_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_idjest wypełniane tylko dla zamówień ze sklepów internetowych.- Pola produktu
storage,storage_id,variant_id,warehouse_id,location,auction_id,attributes,weightpochodzą z pól elastycznych pozycji zamówienia (zapisywanych m.in. przezaddOrderiaddOrderProduct).
setOrderPayment
Dział zatytułowany „setOrderPayment”payment_doneustawia łą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 = 0nie zmienia płatności.
Pola dodatkowe
Dział zatytułowany „Pola dodatkowe”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.
ID pól takie jak w BaseLinkerze
Dział zatytułowany „ID pól takie jak w BaseLinkerze”Nowa instancja — pola jeszcze nie istnieją:
- 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”.
- Pobierz listę pól z BaseLinkera klienta:
getOrderExtraFields(igetOrderReturnExtraFields, jeśli używasz zwrotów) —extra_field_id,name,editor_type,options. - Załóż w Sellrocket definicje pól z
idrównymextra_field_idz BL — zobacz Pola elastyczne → Własne ID. Nazwę techniczną (fieldName) wybierz na stałe — później nie da się jej zmienić. - Sprawdź w Beel API:
getOrderExtraFieldszwraca ID jak w BaseLinkerze,setOrderFieldszcustom_extra_fields: { "135": "B2B" }zapisuje wartość,getOrderszinclude_custom_extra_fields: truezwracacustom_extra_fieldsz 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”.
Ograniczenia
Dział zatytułowany „Ograniczenia”- W trybie „ID wyliczone z nazwy pola” lista z
getOrderReturnExtraFieldsmoże nie zgadzać się z kluczamicustom_extra_fieldswgetOrderReturns. 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_idna liście pól jest zawsze wyliczany z nazwy pola (nie da się go ustawić). Odczyt produktu (getInventoryProductsData) zwraca klucz z nazwy pola — pole nazwaneextra_field|extra_field_<ID z BL>daje kluczextra_field_<ID z BL>jak w BaseLinkerze. Zapis kluczem z BaseLinkera waddInventoryProductjest 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.
addOrderReturndziała w dwóch trybach:- z
order_id— zwrot do istniejącego zamówienia; podaneorder_product_idmusi wskazywać pozycję tego zamówienia (inaczejERROR_BAD_ORDER_ITEM_ID), a pozycja bezorder_product_idjest dodawana do zwrotu jako nowa, - bez
order_id— zwrot samodzielny; pozycje nie mogą miećorder_product_id(inaczejERROR_BAD_ORDER_ID).
- z
status_idzwrotu istatus_idkażdej pozycji są wymagane i muszą istnieć w instancji (inaczejERROR_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) idelivery_price.refunded: trueoznacza zwrot całej tej kwoty — nie można podać innej kwoty refundacji. getOrderReturnszwraca maksymalnie 100 zwrotów na wywołanie — zawężaj wyniki filtrami (id_from,date_from). Polareference_numberiadmin_commentssą puste,date_in_status = 0;shop_order_id,order_return_sourceiorder_return_source_idnie są zwracane.
Magazyny i katalogi
Dział zatytułowany „Magazyny i katalogi”getInventoryWarehouseszwracawarehouse_type = "bl"i liczbowewarehouse_id. W stanach, lokalizacjach i liście magazynów katalogu (getInventories) magazyn ma kluczbl_{id}.reservationsjest zawszefalse, a rezerwacje wgetInventoryProductsStockzawsze0.- Stare API magazynowe (
getProductsListitd.) działa na domyślnym katalogu, widocznym jakobl_1.
Zestawy
Dział zatytułowany „Zestawy”- Stan zestawu jest wyliczany ze składników —
updateInventoryProductsStockodrzuca 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.
addInventoryProductzis_bundlenie może ustawiać stanów, a składniki muszą należeć do tego samego katalogu.
getJournalList
Dział zatytułowany „getJournalList”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.
createPackage
Dział zatytułowany „createPackage”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.

