ENKatalog obejmuje 31 narzędzi xSale MCP. Stan na 2026-10-20. Narzędzia pozwalają odczytywać dane xSale, przygotowywać plany zmian i zapisywać wskazane zmiany. Dostęp zależy od zakresów połączenia i uprawnień użytkownika w danej organizacji.
Limity korzystania z MCP
Limity chronią płynność działania usługi. Dotyczzą żądań wysyłanych przez MCP do API xSale, a nie liczby wiadomości w rozmowie. Jedno wywołanie narzędzia może wykonać kilka żądań, np. odczytać dane, zapisać zmianę i sprawdzić wynik.
| Zakres żądań MCP → API xSale | Tempo uzupełniania limitu | Zapas na krótką serię żądań | Maksymalna liczba żądań równoległych |
|---|---|---|---|
| Użytkownik, łącznie dla jego firm | 60/min | 16 | 4 |
| Firma, łącznie dla jej użytkowników | 120/min | 10 | 4 |
| Instancja usługi MCP, wspólnie dla obsługiwanego ruchu | 240/min | 16 | 8 |
| Odczyt katalogu organizacji przy dostępie administracyjnym do wszystkich firm | 12/min | 2 | 1 |
Limit uzupełnia się stopniowo. Wartość 60/min nie oznacza możliwości wysłania 60 żądań naraz. Zapas na krótką serię, nazywany burst, określa maksymalną liczbę zgromadzonych pozwoleń. Dodatkowo obowiązuje limit żądań wykonywanych równocześnie.
Limity obowiązują jednocześnie. Dostępny limit użytkownika nie gwarantuje wykonania operacji, jeśli został wykorzystany limit firmy lub instancji. Usługa nie kolejkuje takich żądań i nie ponawia ich automatycznie. Stan konfiguracji: 20.10.2026.
Ochrona połączenia z serwerem MCP
Niezależnie od limitów API serwer MCP ogranicza przychodzące żądania HTTP: 120 na minutę z jednego adresu IP, 60 na minutę na użytkownika oraz 16 równoległych wywołań MCP. Dla połączeń anonimowych drugi limit także rozliczany jest według IP. Te limity działają w oknach minutowych. Nie należy ich sumować z limitami w tabeli.
Co zrobić po przekroczeniu limitu?
- Przy ograniczeniu wejścia serwer może zwrócić HTTP 429. Zmniejsz tempo i liczbę równoległych zadań.
- Przy ograniczeniu żądań do API narzędzie może zwrócić błąd
isError=true, np.rate_limit_user,rate_limit_companylubconcurrency_limit_user. Sam HTTP 200 nie oznacza wtedy wykonania zadania. - Jeśli odpowiedź zawiera
retryAfterMs, odczekaj wskazaną liczbę milisekund. Przy limicie równoległości czas może nie być podany; poczekaj na zakończenie trwających operacji. - Jeśli zadanie mogło już zmienić dane, najpierw sprawdź ich stan. Nie ponawiaj automatycznie całej operacji zapisu.
Wyższe limity na zamówienie
Możesz zamówić dodatkowe, wyższe limity korzystania z MCP dla swojej firmy. Napisz na helpdesk@xsale.ai lub skorzystaj z formularza kontaktowego. Podaj firmę, planowane zastosowanie, liczbę użytkowników oraz przewidywane obciążenie. Zakres zwiększenia i warunki zamówienia są ustalane indywidualnie.
Dla firmy można indywidualnie ustawić tempo żądań, zapas na krótką serię i równoległość. Zwiększenie limitu firmy samo w sobie nie zmienia limitu użytkownika, instancji ani ochrony połączenia. Dlatego przy zamówieniu trzeba uwzględnić cały planowany sposób pracy.
Wyższy limit ruchu nie oznacza automatycznego zwiększenia rozmiaru plików, zakresu dat, liczby wyników ani pozostałych ograniczeń poszczególnych narzędzi opisanych w katalogu. Nie zmienia też limitów i warunków konta ChatGPT, Claude ani innej aplikacji AI.
Jak czytać katalog?
- Odczyt pobiera dane i nie zmienia obiektu.
- Plan odczytuje stan i przygotowuje zmianę bez zapisu. Zwracany
changeTokensłuży do porównania stanu przed zapisem. Nie jest zgodą użytkownika ani blokadą edycji. - Zapis zmienia wskazane dane. Wymaga wcześniejszego planu, zakresów
mcp::readimcp::writeoraz odpowiednich praw użytkownika xSale.
Odczyty danych i plany korzystają z zakresu mcp::read. Zakresy MCP są inne niż zakresy logowania OIDC, takie jak openid i email. Samo zalogowanie nie nadaje prawa do odczytu lub zmiany danych biznesowych.
Poniżej podano techniczne nazwy narzędzi serwera. Klient AI może wyświetlać je z dodatkowym prefiksem. Po dodaniu lub zmianie narzędzi odśwież ich listę zgodnie z procedurą swojego klienta AI. Sposób odświeżania zależy od aplikacji.
Połączenie, organizacje i integracje
| Narzędzie | Tryb | Działanie i ograniczenia |
|---|---|---|
xsale_check_authentication |
Odczyt | Sprawdza uwierzytelnienie i delegację do API. Wynik nie potwierdza praw do danych biznesowych. |
xsale_list_organizations |
Odczyt | Zwraca dostępne organizacje. Do dalszych operacji używaj dokładnego pola name, bez skracania nazwy. |
xsale_list_integrations |
Odczyt | Listuje instalacje kanałów sprzedaży, ERP, WMS, hurtowni lub REST, po jednej kategorii na wywołanie. Nie ujawnia konfiguracji ani poświadczeń. HasErrors sygnalizuje opóźnione zadanie, a nie wynik sprawdzenia połączenia; unknown oznacza brak statusu w API. Kategorie inne niż kanały sprzedaży mają limit 200 rekordów i 256 KB. |
xsale_list_languages |
Odczyt | Zwraca języki organizacji, ich ID, kody i język domyślny. Limit: 1000 języków. |
Zamówienia i podsumowania
| Narzędzie | Tryb | Działanie i ograniczenia |
|---|---|---|
xsale_list_orders |
Odczyt | Pokazuje do 20 zamówień sprzedaży na wywołanie. Może filtrować jeden status. Obie daty zakupu podaj razem; zakres obejmuje maksymalnie 93 dni włącznie. Lista służy przeglądaniu, nie sumowaniu sprzedaży. |
xsale_get_order |
Odczyt | Pobiera szczegóły zamówienia wskazanego przez ID z listy: status, daty, kwoty, dostawę, płatność, pozycje i adresy. Nie zwraca zdjęć ani załączników. |
xsale_get_order_history |
Odczyt | Pokazuje historię jednego zamówienia, do 20 zdarzeń na stronę. Zmiany w trakcie przeglądania mogą przesunąć strony. |
xsale_list_order_statuses |
Odczyt | Listuje statusy, także ukryte i dotyczące innych dokumentów. Dla zamówień sprzedaży wybieraj wyłącznie isApplicableToSalesOrder=true. Ta flaga nie nadaje prawa do zapisu. Limit: 20 statusów na stronę. |
xsale_summarize_order_sales |
Odczyt | Zwraca liczbę zamówień sprzedaży i wartości produktów netto oraz brutto osobno dla każdej waluty. Obsługuje dziś, wczoraj, poprzedni miesiąc lub zakres do 93 dni włącznie. Nie obejmuje dostawy, nie przelicza walut i nie pomija automatycznie anulowanych zamówień. Sprawdź flagi kompletności sum. |
xsale_summarize_orders_by_status |
Odczyt | Zwraca do 200 widocznych statusów z licznikami zamówień. Obejmuje wszystkie typy zamówień i daty zakupu, niezależnie od filtrów listy. Nie jest raportem sprzedaży. |
xsale_plan_order_status_change |
Plan | Przygotowuje zmianę statusu jednego zamówienia sprzedaży. Zwraca stan obecny, żądany i token. Zmiana statusu może uruchomić procesy automatyczne. |
xsale_set_order_status |
Zapis | Ustawia status po ponownej kontroli typu i stanu planu. Przyjęcie przez API nie potwierdza zakończenia procesów automatycznych. |
Oferty i powiązania z towarami
| Narzędzie | Tryb | Działanie i ograniczenia |
|---|---|---|
xsale_list_offers |
Odczyt | Listuje do 20 ofert z filtrami, np. problemu synchronizacji, kanału, kodu lub nazwy. Ranking cen wymaga ID kanału i waluty, domyślnie PLN; obejmuje cały przefiltrowany zbiór przed podziałem na strony. Lista nie zwraca kwot ani stanów. Nie łącz hasSyncLog=false z syncIssue. |
xsale_get_offer |
Odczyt | Pobiera wybraną ofertę: warianty, towary, parametry, kanały, problemy oraz ceny i stany z logów. Zwraca dostępne adresy zdjęć, ale nie pobiera obrazów. Dane nie potwierdzają bieżącego stanu marketplace. |
xsale_verify_offer_article |
Odczyt | Sprawdza wskazany wariant i świeże dane powiązanego towaru xSale. Dla zestawu może wymagać ID komponentu. Porównuje EAN dokładnie, bez normalizacji; różnica nie dowodzi błędnego powiązania. Nie sprawdza stanu marketplace. ExternalId i ForeignId to różne identyfikatory. |
xsale_plan_offer_sales_channel_status_change |
Plan | Przygotowuje aktywację lub dezaktywację jednego kanału oferty. Nie jest planem archiwizacji całej oferty. |
xsale_set_offer_sales_channel_status |
Zapis | Zmienia aktywność wskazanego kanału po porównaniu tokenu. Aktywacja kanału w trakcie zamykania jest blokowana. Przyjęcie zmiany nie potwierdza synchronizacji. |
Ceny i stany z logów są osobnym odczytem. Nie stanowią jednej migawki z rankingiem listy ofert. Brak waluty w logu oznacza PLN; nie przypisuj logom waluty użytej w rankingu.
Nazwy i opisy w różnych językach
| Narzędzie | Tryb | Działanie i ograniczenia |
|---|---|---|
xsale_get_offer_translations |
Odczyt | Zwraca nazwę i opis oferty we wszystkich zapisanych językach. |
xsale_plan_offer_translation_change |
Plan | Przygotowuje nazwę lub opis dla jednego języka. Zwykły HTML i opis blokowy Allegro są różnymi formatami i nie mogą być podane razem. Pominięte pola zachowują wartość; nowe tłumaczenie wymaga nazwy. Pozostałe języki pozostają bez zmian. |
xsale_update_offer_translation |
Zapis | Zapisuje wskazane tłumaczenie po odczycie i porównaniu tokenu. Zachowuje pozostałe języki i pominięte pole. Sama zmiana nazwy zachowuje opis i jego typ. Zmiana może uruchomić synchronizację. |
Nazwa ma limit 2000 znaków, zwykły opis 100000 znaków, a JSON 512 KiB. Opis Allegro ma 1–100 sekcji po 1–2 elementy i limit 40000 bajtów UTF-8. Element TEXT obsługuje h1,h2,p,ul,ol,li,b bez atrybutów; IMAGE wymaga pictureId z galerii. W zwykłym HTML używaj htmlImageTag zwróconego przez odczyt galerii.
Parametry oferty i kanałów
| Narzędzie | Tryb | Działanie i ograniczenia |
|---|---|---|
xsale_get_offer_parameter_definitions |
Odczyt | Zwraca definicje parametrów kategorii kanału (target=product) lub parametrów sprzedażowych (target=sales), typy, ID i początkowe opcje słowników. Obsługuje Allegro, WooCommerce i Inpost Von Halsky. Odpowiedź API jest ograniczona do 2 MiB i 200 definicji; wynik MCP do 20 definicji na stronę. |
xsale_list_offer_parameter_options |
Odczyt | Listuje do 20 opcji jednego parametru na stronę. Filtry i strony działają lokalnie po pobraniu definicji do 2 MiB. Dla parametrów kategorii Inpost Von Halsky używa tekstowego ForeignId; Allegro i WooCommerce używają lokalnych ID liczbowych. Parametry sprzedażowe używają lokalnych ID liczbowych. |
xsale_plan_offer_parameter_change |
Plan | Przygotowuje zastąpienie parametrów własnej kategorii xSale albo zmianę parametrów kategorii lub sprzedażowych kanału. Wymaga właściwych ID i typów JSON. Pokazuje stan przed zmianą i żądane wartości. |
xsale_replace_offer_parameters |
Zapis | Zastępuje pełny zestaw parametrów własnej kategorii xSale. Pominięte parametry tej kategorii są usuwane; pusta lista usuwa wszystkie. MCP nie udostępnia definicji własnej kategorii: nie używaj zamiast nich ID definicji kanału. |
xsale_patch_offer_channel_parameters |
Zapis | Zmienia parametry kategorii wskazanego kanału po planie z definicjami target=product. Wymaga dodatnich ID kategorii i integracji. Zmiana kategorii może zmienić dostępne parametry. |
xsale_patch_offer_channel_sales_parameters |
Zapis | Zmienia wskazane parametry sprzedażowe kanału po planie z definicjami target=sales. Wymaga ID integracji i co najmniej jednego parametru. Nie przyjmuje ID kategorii. |
Galeria zdjęć oferty
| Narzędzie | Tryb | Działanie i ograniczenia |
|---|---|---|
xsale_get_offer_pictures |
Odczyt | Odczytuje wspólną galerię, kolejność i identyfikatory do 1000 zdjęć. Nie pobiera obrazów. htmlImageTag służy do zwykłego HTML, a descriptionReference do opisów blokowych. |
xsale_plan_offer_picture_upload |
Plan | Planuje dodanie jednego JPEG lub PNG do galerii, maksymalnie 20 MiB. Dane pliku muszą być w Base64 bez prefiksu data:; nazwa pliku ma do 100 znaków. Plan nie dodaje zdjęcia do opisu. |
xsale_upload_offer_picture |
Zapis | Dodaje zdjęcie zgodnie z planem i odczytuje galerię po przyjęciu pliku. pictureId identyfikuje powiązanie, a binaryDataId oryginalny plik. Dodanie do galerii nie umieszcza zdjęcia w opisie. |
xsale_plan_offer_picture_order_change |
Plan | Przygotowuje kolejność pełnej galerii: do 1000 wartości pictureId. Nie używaj binaryDataId. |
xsale_set_offer_picture_order |
Zapis | Zapisuje pełną kolejność po ponownym odczycie i porównaniu tokenu. Pozycje są zapisywane kolejno; API nie gwarantuje transakcji dla całej listy. |
Eksport zdjęć do kanałów zależy od ustawień integracji.
Jak bezpiecznie interpretować wyniki?
- Lista jest podzielona na strony. Pierwsza strona nie jest całym zbiorem. Równoczesne zmiany mogą przesuwać kolejne strony.
- Token planu porównuje znany stan, lecz nie zapewnia atomowego zapisu ani ochrony przed wszystkimi równoczesnymi zmianami.
- HTTP 204 potwierdza przyjęcie zmiany przez API. Nie potwierdza zakończenia synchronizacji ani procesów automatycznych.
- Przy
outcomeUnknownlubrequiresReadBackodczytaj obiekt przed kolejną próbą. Nie ponawiaj automatycznie dodania zdjęcia ani zapisu kolejności galerii. - Link do obiektu xSale otwiera firmę aktualnie wybraną w panelu. Nie przełącza organizacji ani nie zmienia praw. Sprawdź nazwę organizacji podaną obok linku.