↑↓ wybierzEnter otwórzEsc zamknij

    1. Elbuz

    Stare API Elbuz (v1): klucz i przejście na API v2

    5 min czytaniaZaktualizowano

    Stare API Elbuz (v1) nadal działa dla już wydanych kluczy v1, ale nowych funkcji w nim nie będzie. Nowe klucze są wydawane dla API v2: z uprawnieniami konkretnego pracownika, zatwierdzaniem zmian w „Pulsie” i ochroną przed duplikatami.

    Kiedy to się przyda:

    • Integracja działa przez api/login — co czym zastąpić w v2, zebrano w tabeli.
    • Nowy klucz odpowiada „nieprawidłowy klucz” — jest już kluczem API v2 i z api/login nie działa.
    • Wykonawca ma widzieć tylko zamówienia — klucz v2 w imieniu pracownika widzi tylko jego okna.
    • Klucz trzeba natychmiast zamknąć — „Aktywność” i data wygaśnięcia działają też na już wydany token.

    Od czego zacząć: przenieś klucz na v2 w jego karcie.

    Co jest w starym API

    • Przejście na v2 — czym różni się v2 i który zasób v2 zastępuje każdą operację v1.
    • Klucz v1 — pola karty i trzy sposoby ograniczenia dostępu, które działają natychmiast.
    • Dokumentacja API v1 — logowanie, operacje describe, get, add, update, delete, filtry, błędy i gotowe przepisy.
    • Co API v1 robi z danymi — ręczne poprawki, przerwanie i powtórzenie pakietu, czyja cena zostanie, wycofanie zmian.
    • Gotowe wymiany danych bez programisty — tunel, marketplace’y, eksport według harmonogramu.

    Jak przenieść integrację na API v2

    Każda odpowiedź starego zawiera nagłówki Deprecation: @1791936000 (14.10.2026) i Link: </api/v2/openapi.json>; rel="successor-version", <https://elbuz.com/guide-api>; rel="deprecation". Daty wyłączenia v1 nie ma, ale nowych funkcji w nim nie będzie: klucz v1 działa z uprawnieniami administratora, bez uprawnień pracownika i bez dziennika jego działań.

    v1 (ta dokumentacja)v2
    Logowanieapi/login → api_token w treści lub adresienagłówek Authorization: Bearer elbz_… w każdym zapytaniu, bez sesji
    Uprawnieniajak u administratora, na całe kontojak u pracownika, w imieniu którego wydano klucz: okna, pola, „Czyje dane”
    Zmianywykonywane od razuzależnie od trybu klucza: propozycja w „Pulsie” (202) lub od razu
    Błędykod 200, trzy różne formaty treściprawdziwy kod HTTP, format RFC 9457
    Stronypage, max_rows do 500kursor, limit do 200
    Powtórzenie po przerwaniutworzy duplikatIdempotency-Key — duplikatu nie będzie
    Limit30 na minutę jako minimalny odstęp120 na kroczącą minutę, nagłówki RateLimit

    Jak przenieść klucz

    1. Otwórz kartę swojego klucza v1 w oknie „API i tokeny dostępu”.
    2. W polu „W imieniu pracownika” wybierz, czyje uprawnienia otrzyma integracja. Klucz v1 widział wszystko — sprawdź, czy pracownik ma otwarte wszystkie potrzebne okna i pola, inaczej po przejściu część danych zniknie z odpowiedzi.
    3. Kliknij „Utwórz nowy klucz” i potwierdź komunikat „Nowy klucz zastąpi bieżący: integracje ze starym kluczem przestaną działać”. Stare „Użytkownik” + „Klucz dostępu” i już wydane tokeny przestają działać od razu — przenieś integrację w tej samej minucie albo utwórz dla v2 osobny klucz przyciskiem „+” i przełącz się, gdy kod będzie gotowy.
    4. Skopiuj nowy klucz — jest pokazywany tylko raz.
    Karta klucza API v2: w imieniu pracownika, tryb zmian danych, limit bezpieczeństwa i nowy klucz
    1W imieniu pracownika
    2Zmiany danych
    3Limit bezpieczeństwa: zmian na godzinę
    4Bieżący klucz
    5Tylko do odczytu
    1. W imieniu pracownika — czyje uprawnienia i dane otrzymuje klucz. Innych pracowników widzi tylko osoba z dostępem do okna użytkowników.
    2. Zmiany danych — „Pytaj” (każda zmiana czeka w „Pulsie”) lub „Wykonuj samodzielnie”. Przełączyć może tylko „Zarząd”.
    3. Limit bezpieczeństwa — po tylu wykonanych zmianach w ciągu godziny klucz sam wraca do trybu „Pytaj”.
    4. Nowy klucz jest pokazywany raz: skopiuj go przyciskiem „Kopiuj”, zanim zamkniesz okno.
    5. Tylko do odczytu — włączone dla nowego klucza; odznacz, jeśli klucz ma coś zmieniać.

    Nowy klucz jest tworzony w trybie „Pytaj (przez „Puls”)”: każda zmiana czeka na zatwierdzenie w „Pulsie”. Dla integracji, która ma zapisywać od razu (zamówienia ze strony, ceny z systemu księgowego), „Zarząd” ustawia w karcie klucza „Wykonuj samodzielnie”. Szczegóły — API v2: zmiany.

    Co czym się zastępuje

    v1v2
    api/login + api_tokennagłówek Authorization: Bearer
    scope/describe scope=XGET /api/v2/openapi.json lub GET /api/v2/
    scope/get product / product_price / document / contractor / contractor_group / company / category / manufacturer / attribute / attribute_blockGET /products, /supplier_products, /documents (+ /document_items?filter[document_id]=), /contractors, /contractor_groups, /companies, /categories, /manufacturers, /attributes, /attribute_groups
    scope/get articleGET /articles
    scope/get document_type / document_status / document_payment_status / document_delivery_status / stock_status / warehouse / store / currency / languageGET /document_types, /document_statuses, /payment_statuses, /delivery_statuses, /stock_statuses, /warehouses, /stores, /currencies, /languages; nowe — /payment_types, /delivery_types
    scope/add document z zatwierdzeniemPOST /documents, potem POST /documents/{id}/sign
    scope/add X, X/add_batchPOST /X z Idempotency-Key, po jednym rekordzie
    scope/update X, X/updatePATCH /X/{id}
    scope/delete X, X/deleteDELETE /X/{id} — do kosza, dla kontrahentów, dokumentów i artykułów (w v2 także dla transakcji, zadań, notatek, projektów); produkty, kategorie, producentów i atrybuty usuwa się tylko w oknie
    scope/search productGET /products?q=…
    scope/add contractor_pricePOST /price_lists/{id}/import — zadanie w tle
    scope/add mail_sendPOST /mail_messages/{id}/reply — zawsze przez „Puls”
    scope/add document_extended, scope/get print_templatew v2 brak odpowiednika

    Trasy api/order, api/cart, api/payment, api/shipping, api/coupon, api/voucher, api/reward, api/customer, api/currency usunięto: to pozostałości witryny OpenCart, nie działały i odpowiadały błędem. Słownik walut v1 — api/scope/get/currency — działa jak dotąd.

    Klucz v1: pola i ograniczenia

    Tabela poniżej dotyczy karty klucza utworzonego przed 14.10.2026. Jest w niej ostrzeżenie „To klucz starego API (v1)…”, pole „Klucz dostępu” i przycisk „Generuj”. Klucz utworzony teraz przyciskiem „+” jest już kluczem v2: nie ma pola „Klucz dostępu” i nie działa z api/login.

    Pole karty kluczaParametr w zapytaniuCo robi
    „Użytkownik”usernamenazwa do logowania
    „Klucz dostępu”keysekret; przycisk „Generuj” tworzy go za Ciebie
    „Aktywność”—wyłączony klucz nie wpuszcza ani przy logowaniu, ani z już wydanym tokenem
    „Tylko do odczytu”—każda zmiana danych kończy się błędem; odczyt działa
    „Adresy IP z dostępem”—lista rozdzielona przecinkiem, spacją lub nową linią. Puste — z dowolnego adresu
    „Data wygaśnięcia dostępu”—klucz działa do tej daty włącznie; pusta data — bezterminowo
    „Uwagi”—komu i po co wydano klucz

    Trzy pola zamykają dostęp natychmiast, a nie od następnego logowania. „Aktywność”, „Data wygaśnięcia dostępu” i „Tylko do odczytu” są odczytywane z karty klucza przy każdym zapytaniu, więc działają też na już wydany token: wyłączysz klucz lub nadejdzie dzień po dacie — bieżący token przestaje działać bez ponownego logowania. To wygodne, gdy klucz trzeba natychmiast odwołać.

    Uprawnień klucza v1 nie da się podzielić według słowników. Klucz v1 nie jest użytkownikiem programu: działy i grupy uprawnień na niego nie działają, więc jeden token czyta zamówienia, produkty, kontrahentów i wszystko inne, co jest na koncie. Klucz można ograniczyć tylko trzema polami karty — „Tylko do odczytu”, „Adresy IP z dostępem” i „Data wygaśnięcia dostępu”.

    Jeśli wykonawca lub zewnętrzny program ma widzieć tylko zamówienia, ten klucz nie pomoże: wydaj klucz v2 w imieniu użytkownika z działu, któremu otwarto tylko okno zamówień — klucz v2 otrzymuje uprawnienia właśnie tego pracownika.

    Twórz osobny klucz dla każdej integracji: wtedy odwołanie jednego nie zatrzyma pozostałych.

    Kiedy API nie jest potrzebne

    Zanim napiszesz integrację, sprawdź gotowe mechanizmy — rozwiązują większość zadań bez programisty:

    • Strona na popularnym — tunel zapisuje produkty, ceny i stany bezpośrednio do bazy danych strony.
    • Marketplace — gotowe połączenia są już dla kilkunastu platform.
    • Regularny plik — eksport według harmonogramu do lub .

    API zostaje dla własnej logiki: niestandardowa strona, wewnętrzny system księgowy, wymiana danych, której nie ma w gotowych formatach.

    Scenariusze

    Strona tylko pobiera stany i ceny

    Zadanie: strona czyta z Elbuz stany i ceny i nie może niczego zmieniać na koncie.

    Co włączyć: osobny klucz dla strony z zaznaczonym „Tylko do odczytu”, w polu „Adresy IP z dostępem” — adres serwera strony. Zapytanie — api/scope/get z limit_field=sku,price,quantity, jak w przepisie.

    Efekt: odczyt działa. Każde add, update czy delete tym kluczem kończy się odpowiedzią „brak uprawnień do zmiany danych” — nawet jeśli w kodzie strony jest błąd i spróbuje ona coś zapisać. Zapytanie z innego adresu nie przejdzie ani przy logowaniu, ani z już wydanym tokenem.

    Tymczasowy dostęp dla zewnętrznego programisty

    Zadanie: wykonawca konfiguruje integrację, a dostęp ma się zamknąć razem z projektem.

    Co włączyć: osobny klucz, w „Data wygaśnięcia dostępu” — ostatni dzień prac, w „Uwagi” — komu i po co go wydano.

    Efekt: klucz działa do tej daty włącznie. Następnego dnia nie wpuszcza go ani api/login, ani token otrzymany wcześniej — nie trzeba czekać, aż sesja wygaśnie sama. Skończyliście wcześniej — odznacz „Aktywność”, działa tak samo. Czego nie będzie: inne klucze konta od tego nie zależą, każdy ma własną datę i własne pole wyboru.

    Ograniczyć takiego klucza do wybranych słowników się nie da — jak dać wykonawcy tylko zamówienia.

    Przejść na v2 bez przestoju

    Zadanie: integracja ma działać przez cały czas, gdy programista przepisuje ją na v2.

    Co włączyć: nie ruszając klucza v1, utwórz przyciskiem „+” osobny klucz v2 w imieniu właściwego pracownika. Sprawdź na nim nowy kod.

    Efekt: oba klucze działają równolegle. Gdy kod na v2 jest gotowy, odznacz w kluczu v1 „Aktywność” — jego tokeny od razu przestaną działać.

    Co zrobić, gdy klucz nie wpuszcza

    Co widziszDlaczego tak jestCo zrobić
    Nowy klucz: api/login odpowiada „nieprawidłowy klucz”klucz utworzono dla API v2, nie ma pola „Klucz dostępu”wysyłaj zapytania do /api/v2/… z nagłówkiem Authorization: Bearer (API v2)
    Odczyt działa, zapis jest odrzucanyklucz ma „Tylko do odczytu”; ustawienie działa na wszystkie trasy, także stareodznacz pole — działa od razu, bez ponownego logowania
    Klucz przestał wpuszczać, choć jest aktywnynadszedł dzień po „Dacie wygaśnięcia dostępu”przesuń datę lub wyczyść pole — wtedy klucz jest bezterminowy
    Po przejściu na v2 część danych zniknęła z odpowiedziklucz v2 widzi tylko okna i pola swojego pracownikaotwórz pracownikowi potrzebne okna i pola (krok 2 przejścia)

    Najczęstsze pytania

    Czy stare API przestanie działać?

    Daty wyłączenia nie ma: klucze v1 działają jak dotąd. Ale nowych funkcji w v1 nie będzie, a „Utwórz nowy klucz” w karcie przenosi klucz na v2 bez możliwości powrotu.

    Czy można mieć jednocześnie klucz v1 i klucz v2?

    Tak. Klucz utworzony przyciskiem „+” to osobny klucz v2, a klucz v1 działa dalej. Tak przenosi się integrację bez przestoju (scenariusz).

    API odpowiada „UWAGA: nieprawidłowy klucz API!”, choć klucz skopiowano poprawnie. Co sprawdzić?

    W karcie klucza — parę „Użytkownik” + „Klucz dostępu”, „Aktywność” i „Datę wygaśnięcia dostępu”: dla wszystkich trzech przyczyn tekst jest taki sam. Nie ma pola „Klucz dostępu” — to klucz v2. Inny tekst błędu to odpowiedź API dostawcy lub platformy, nie Elbuz.

    Czy można dać wykonawcy klucz API, który widzi tylko zamówienia?

    Kluczem v1 — nie: czyta wszystko na koncie. Kluczem v2 — tak: wydaj go w imieniu użytkownika z działu, któremu otwarto tylko okno zamówień (szczegóły).

    Jakie adresy IP serwerów Elbuz dodać do białej listy (whitelist)?

    Wspólnej listy nie ma: adres zależy od serwera konta. Dla dostawcy z API jest podany w oknie źródła „Ustawienia parametrów dostępu do API” (podłączenie dostawcy), w sprawie innych usług napisz na support@elbuz.com. Pole klucza „Adresy IP z dostępem” dotyczy czegoś innego: skąd wpuszczać do Elbuz.

    Gdzie to jest i kto ma dostęp

    Menu
    Panel klienta → Ustawienia systemu → „Inne ustawienia” → kafelek „API i tokeny dostępu”
    Uprawnienia
    okno „API i tokeny dostępu” w uprawnieniach grupy
    Przygotuj
    pracownika, w imieniu którego będzie działać klucz v2
    Okno ustawień systemu, sekcja „Inne ustawienia” z zestawem kafelków, w tym „API i tokeny dostępu”
    1API i tokeny dostępu
    2Inne ustawienia
    1. API i tokeny dostępu — otwiera listę kluczy API.
    2. Inne ustawienia — zbiera okna, których nie ma w menu głównym.

    Powiązane tematy

    Czy ten artykuł był pomocny?

    Brakuje funkcji? Napisz do nas.

    Dodamy ją za darmo, jeśli przyda się też innym.

    Jeśli potrzebujesz jej tylko ty — umówimy się osobno.

    Spis treści

    Zaproponuj usprawnienie

    Wypróbuj Elbuz za darmo