Przejdź do głównej zawartości

Identyfikatory z BaseLinkera

Integracja przenoszona z BaseLinkera ma zwykle w kodzie identyfikatory z BaseLinkera: statusów zamówień, źródeł zamówień, kont kurierskich, pól dodatkowych. Na nowej instancji Sellrocket nadaje własne ID — część z nich możesz jednak ustawić tak, żeby Beel API zwracało te same ID co BaseLinker. Ta strona mówi, które ID da się zachować, jak to zrobić i które trzeba mapować w integracji. Najlepiej zrobić to przed pierwszymi zamówieniami na instancji.

Identyfikator w Beel API Skąd pochodzi ID jak w BaseLinkerze
status_id zamówienia ID statusu w Sellrocket tak — załóż statusy z ID z BL przed pierwszymi zamówieniami (Statusy zamówień)
status_id zwrotu ID statusu zwrotu w Sellrocket nie — mapuj w integracji (Statusy zwrotów)
order_source, order_source_id typ i ID źródła zapisane w połączeniu (kanale sprzedaży) tak — ustaw je w połączeniu przed pierwszymi zamówieniami (Źródła zamówień)
account_id konta kurierskiego ID źródła zapisane w połączeniu kurierskim tak w createPackage (Konta kurierskie)
extra_field_id pól dodatkowych zamówień i zwrotów zależy od opcji tak po włączeniu opcji — jak założyć pole z ID z BL, szczegóły: Różnice → Pola dodatkowe
extra_field_id i klucze text_fields pól dodatkowych produktów lista: wyliczany z nazwy pola; produkt: klucz z nazwy pola lista — nie; odczyt produktu — tak, gdy pole ma nazwę extra_field|extra_field_<ID z BL> (przykład krok po kroku)
courier_code, log_type w dzienniku — już takie same jak w BaseLinkerze
order_id, order_product_id, return_id, package_id nadaje Sellrocket nie — to nowe obiekty w nowym systemie

status_id w Beel API (getOrderStatusList, getOrders, setOrderStatus, addOrder) to ID statusu Sellrocket — to samo co w REST API (GET /api/v3/Statuses/GetAll).

Nowa instancja — zrób to przed pierwszymi zamówieniami i przed konfiguracją automatyzacji:

  1. Pobierz statusy z BaseLinkera klienta: getOrderStatusList (id, name, color).

  2. Sprawdź statusy w Sellrocket: GET /api/v3/Statuses/GetAll. ID z BL nie może być zajęte.

  3. Dla każdego statusu wywołaj POST /api/v3/Statuses z id z BaseLinkera:

    {
    "id": 12345,
    "name": "Do wysłania",
    "shortName": "Do wysłania",
    "color": "#3789FF"
    }

    Operacja jest asynchroniczna — zwraca zadanie (JobDTO); sprawdź, czy zakończyło się bez błędu.

  4. Sprawdź w Beel API: getOrderStatusList zwraca ID jak w BaseLinkerze.

Uwagi:

  • Statusy zakładane bez id dostają ID od 100 000 wzwyż. Jeśli ID statusu z BaseLinkera jest zajęte, status nie zostanie założony (zadanie kończy się błędem).
  • W każdej instancji jest status domyślny (ID 1 000 000 000) — zostaje na liście obok statusów z BaseLinkera.
  • ID statusu nie da się zmienić po założeniu (PUT /api/v3/Statuses/{statusId} nie przyjmuje id).

Instancja, która już działa: ID istniejących statusów nie zmienisz. Statusy są powiązane z zamówieniami, historią, automatyzacjami, uprawnieniami użytkowników i przyciskami w panelu — dlatego zalecamy mapowanie w integracji (ID z BaseLinkera → ID w Sellrocket). Jeśli zmiana ID jest konieczna, klient zgłasza to do wsparcia Sellrocket; wsparcie oceni skutki dla danej instancji.

status_id zwrotów i ich pozycji (getOrderReturns, addOrderReturn) to ID statusów zwrotów w Sellrocket. Nie da się ich założyć z własnym ID — mapuj je w integracji. Listę statusów zwrotów pobierzesz przez REST API — zobacz Zwroty (Beel API nie ma metody listy statusów zwrotów).

Źródło zamówienia w Sellrocket to połączenie — kanał sprzedaży (np. Allegro, sklep) albo „Pozostałe kanały” (zamówienia wprowadzane ręcznie lub z własnych źródeł). Każde połączenie może mieć zapisany zewnętrzny typ i ID źródła (externalSourceType, externalSourceId). Beel API używa ich zamiast danych Sellrocket:

Beel API Gdy połączenie ma zewnętrzny typ / ID W przeciwnym razie
klucz w getOrderSources, order_source externalSourceType typ połączenia Sellrocket (np. ALL, OS)
ID w getOrderSources, order_source_id externalSourceId ID połączenia w Sellrocket

Wpisz w połączeniu typ i ID źródła z BaseLinkera (getOrderSources w BL), a Beel API zwróci je bez zmian.

Nowa instancja — przed pierwszymi zamówieniami:

  1. Pobierz źródła z BaseLinkera klienta: getOrderSources.

  2. Własne źródła BaseLinkera (personal) — załóż połączenia „Pozostałe kanały” z ID z BaseLinkera przez POST /api/v3/Connections:

    {
    "id": 5821,
    "name": "Sprzedaż telefoniczna",
    "connectionType": "OS",
    "externalSourceType": "personal",
    "externalSourceId": "5821"
    }

    Operacja jest asynchroniczna (JobDTO). Źródło BaseLinkera o ID 0 (osobiście/telefon) załóż bez id, z externalSourceId = "0".

  3. Kanały sprzedaży (Allegro, Empik, Erli, sklepy…) — połączenie konfiguruje klient w panelu (logowanie do kanału). Potem uzupełnij w nim externalSourceType i externalSourceId z BaseLinkera: pobierz połączenie (GET /api/v3/Connections/{id}), zmień te dwa pola i wyślij całość przez PUT /api/v3/Connections/{id}.

  4. Sprawdź w Beel API: getOrderSources zwraca typy i ID jak w BaseLinkerze.

Typy połączeń Sellrocket (connectionType) dla najczęstszych źródeł z BaseLinkera:

BaseLinker Sellrocket BaseLinker Sellrocket
personal OS empik EMP
allegro ALL erli_connector ERLI
amazon AMZ emag EMAG

Pełną listę typów zwraca GET /api/v3/ConnectionDefinitions.

Instancja, która już działa: uzupełnij externalSourceType i externalSourceId przez PUT jak w kroku 3. Zamówienie zapamiętuje typ i ID źródła w chwili utworzenia — nowe ID dostaną tylko zamówienia utworzone po zmianie; wcześniejsze zostają z dotychczasowymi wartościami. ID samego połączenia nie da się zmienić (ma znaczenie tylko dla importu akcji z BaseLinkera — zobacz wyżej).

Filtry i dodawanie zamówień:

  • filter_order_source + filter_order_source_id w getOrders szukają połączenia po zewnętrznym typie i ID. Jeśli podasz sam typ, a takich połączeń jest kilka, dostaniesz ERROR_CONNECTIONS_COUNT (BaseLinker zwróciłby zamówienia ze wszystkich) — podawaj typ razem z ID.
  • custom_source_id w addOrder wskazuje połączenie „Pozostałe kanały” po externalSourceId, a gdy takiego nie ma — po ID połączenia Sellrocket. Bez custom_source_id zamówienie trafia do połączenia Beel API, z którego pochodzi token.
  • Zwroty: filter_order_return_source(_id) i custom_source_id w addOrderReturn używają typu i ID połączenia Sellrocket (bez zewnętrznych), a order_return_source(_id) nie jest zwracane.

Uwagi:

  • Połączenia zakładane bez id dostają ID od 100 000 wzwyż — ID z BaseLinkera może być zajęte. Sprawdź listę (GET /api/v3/Connections) przed założeniem.
  • externalSourceId musi być liczbą — inaczej Beel API zwróci ID połączenia Sellrocket.

createPackage szuka konta kurierskiego (account_id) najpierw po externalSourceId połączenia kurierskiego, a potem po ID połączenia Sellrocket. Żeby zachować account_id z BaseLinkera, wpisz go w externalSourceId połączenia kurierskiego (PUT /api/v3/Connections/{id}, jak przy źródłach zamówień). Bez account_id używane jest pierwsze połączenie danego kuriera.

getCourierAccounts zwraca ID połączeń Sellrocket — nie externalSourceId. Jeśli integracja pobiera listę kont z getCourierAccounts, dostanie inne ID niż te, które przekazuje do createPackage z BaseLinkera.

courier_code jest taki sam jak w BaseLinkerze (np. paczkomaty, dpd, gls).