API / Techniczne

⌘K
  2. Strona główna
  4. Dokumentacja
  6. API / Techniczne
  8. Obsługa integracji z włas...
  10. Kategorie sklepu własnego

Kategorie sklepu własnego

Do czego służy ta instrukcja

Ten artykuł pokazuje, jak zarządzać kategoriami dla integracji z własnym sklepem w xSale za pomocą REST API. Opisuje tworzenie kategorii i podkategorii (drzewa kategorii), sposoby pobierania kategorii oraz operacje administracyjne, takie jak zmiana nazwy, przenoszenie i archiwizacja.

Na początku znajdziesz skrótowy opis procesu i wymagania, a dalej część techniczną z endpointami i przykładami (pozostawioną bez zmian).

W tym artykule znajdziesz

  • kiedy warto budować drzewo kategorii przez API
  • wymagania i dane wejściowe
  • szybki przepis krok po kroku
  • typowe problemy i sposób weryfikacji

Kiedy stosować

To podejście sprawdza się, gdy oferty w xSale mają odzwierciedlać strukturę kategorii w Twoim sklepie. Najczęściej budujesz drzewo kategorii raz na starcie integracji, a potem utrzymujesz je w spójności (np. dodając nowe gałęzie lub przenosząc kategorie).

Wymagania

  • dostęp do REST API xSale (autoryzacja) dla właściwej organizacji
  • wartość organizationName
  • identyfikator integracji z własnym sklepem (id)
  • plan struktury kategorii (nazwy, zależności nadrzędna/podrzędna, opcjonalne zewnętrzne ID)

Szybki przepis (krok po kroku)

  1. Ustal ID integracji z własnym sklepem (możesz odczytać je w panelu xSale lub pobrać z API).
  2. Utwórz kategorie najwyższego poziomu, a następnie dodawaj podkategorie, przekazując ParentId.
  3. Jeśli potrzebujesz, pobierz kategorie (wyszukiwanie, podkategorie, gałąź) i zweryfikuj, czy struktura jest poprawna.
  4. W razie zmian użyj endpointów do zmiany nazwy, przenoszenia lub archiwizacji kategorii.

Typowe problemy i jak je sprawdzić

  • Błąd autoryzacji — sprawdź dane logowania/token oraz uprawnienia do REST API.
  • Błędne ID integracji — upewnij się, że przekazujesz właściwe id integracji sklepu własnego.
  • Nieprawidłowa struktura drzewa — sprawdź, czy podkategorie mają poprawnie ustawione ParentId.
  • Brak kategorii w wynikach — zweryfikuj filtry wyszukiwania oraz czy kategoria nie została zarchiwizowana.

Szczegóły techniczne

Do utworzenia ofert połączonych z integracją z własnym sklepem wymagane jest zdefiniowanie i przypisanie kategorii. Optymalnym rozwiązaniem jest stworzenie drzewa kategorii, które odzwierciedla strukturę kategorii i podkategorii we własnym sklepie. W tym wpisie znajdziesz szczegóły dotyczące tworzenia kategorii i podkategorii.

Dodawanie kategorii

Aby dodać nową kategorię, wykorzystaj endpoint:

POST /{organizationName}/integrations/{id}/categories

Jedynym obowiązkowym polem w zapytaniu jest Name – przekaż w nim nazwę tworzonej kategorii. Opcjonalnie możesz podać zewnętrzne ID kategorii (ForeignId) – wykorzystanie tej możliwości pozwala na optymalne zarządzanie mapowaniami kategorii pomiędzy sklepem a xSale.

Jeśli kategoria została prawidłowo utworzona, serwer zwróci kod odpowiedzi 201 oraz ID utworzonej kategorii.

Identyfikator integracji z własnym sklepem

Do przesłania zapytania wymagane jest ID integracji ze sklepem własnym. Możesz je sprawdzić na dwa sposoby:

1. W interfejsie aplikacji xSale

Otwórz integrację z własnym sklepem w xSale i odczytaj ID integracji z adresu URL. Przejdź do zakładki Integracje – Integracje i kliknij w kafelek swojej integracji z własnym sklepem. ID integracji zobaczysz w pasku przeglądarki:

2. Za pomocą REST API

Odpytaj endpoint GET /{organizationName}/integrations, aby pobrać listę integracji. Odpowiedź możesz zawęzić do integracji z własnym sklepem, używając filtra typein (podaj wartość 28).

Jeśli integracja nie została jeszcze utworzona, utwórz ją w interfejsie xSale lub dodaj integrację ze sklepem własnym przez REST API.

Dodawanie podkategorii

Aby dodać kategorię niższego rzędu, w zapytaniu na endpoint POST /{organizationName}/integrations/{id}/categories przekaż ID kategorii nadrzędnej (ParentId).

Pobieranie kategorii

Kategorie utworzone w xSale dla integracji z własnym sklepem możesz pobrać na kilka sposobów:

1. Wykorzystaj poniższy endpoint, który umożliwia wyszukiwanie wśród istniejących kategorii:

GET /{organizationName}/integrations/{id}/categories/search

W zapytaniu przekaż ID integracji z własnym sklepem. Możesz wyszukiwać po nazwie kategorii (name), ID kategorii (categoryidequals) i ID kategorii zewnętrznej (foreigncategoryidequals). Jeśli nie użyjesz dodatkowych filtrów, API zwróci tablicę złożoną z pełnych ścieżek dla wszystkich kategorii, zaczynając od kategorii najniższego rzędu, a kończąc na kategorii nadrzędnej.

2. Użyj endpointu zwracającego podkategorie dla wskazanej kategorii:

GET /{organizationName}/integrations/{id}/categories/subcategories

W zapytaniu przekaż ID integracji z własnym sklepem.

3. Pobierz całą gałąź dla wskazanej kategorii korzystając z endpointu:

GET /{organizationName}/integrations/{id}/categories/{categoryId}/branch

W zapytaniu przekaż ID integracji z własnym sklepem oraz ID kategorii.

4. Pobierz szczegóły wybranej kategorii wysyłając zapytanie na endpoint:

GET /{organizationName}/integrations/{id}/categories/{categoryId}

W zapytaniu przekaż ID integracji z własnym sklepem oraz ID kategorii.

REST API xSale udostępnia szereg endpointów do zarządzania kategoriami. Dzięki nim możesz wprowadzać zmiany w istniejących zasobach, np. zmienić nazwę, przenieść na inne miejsce w drzewie kategorii lub zarchiwizować kategorię.

REST API xSale udostępnia szereg endpointów do zarządzania kategoriami. Dzięki nim możesz wprowadzać zmiany w istniejących zasobach, np. zmienić nazwę, przenieść na inne miejsce w drzewie kategorii. Sprawdź szczegóły w interesującej Cię sekcji tego wpisu.

Zmiana nazwy kategorii

Aby zmienić nazwę kategorii, użyj endpointu:

PUT /{organizationName}/integrations/{id}/categories/{categoryId}/rename

Prześlij zapytanie na adres, w którym znajdzie się id integracji (id) do której należy kategoria, id kategorii (categoryId) oraz nowa nazwa kategorii (NewName), w body zapytania.

Zmiana położenia kategorii w drzewie

Możesz zmienić położenie kategorii i podkategorii w utworzonej strukturze, korzystając z endpointu:

PUT /{organizationName}/integrations/{id}/categories/{categoryId}/move

Przesyłając zapytanie użyj id integracji (id) do której należy kategoria, id kategorii (categoryId). Wskaż id docelowej kategorii (TargetCategoryId) w body zapytania.

Archiwizacja kategorii

Przeniesienie kategorii do archiwum sprawia, że nie jest możliwe jej dalsze używanie w ofertach. Aby zarchiwizować kategorię, użyj endpointu:

DELETE /{organizationName}/integrations/{id}/categories/{categoryId}

W zapytaniu prześlij id integracji (id), do której należy kategoria oraz id kategorii (categoryId).