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/loginnie 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 | |
|---|---|---|
| Logowanie | api/login → api_token w treści lub adresie | nagłówek Authorization: Bearer elbz_… w każdym zapytaniu, bez sesji |
| Uprawnienia | jak u administratora, na całe konto | jak u pracownika, w imieniu którego wydano klucz: okna, pola, „Czyje dane” |
| Zmiany | wykonywane od razu | zależnie od trybu klucza: propozycja w „Pulsie” (202) lub od razu |
| Błędy | kod 200, trzy różne formaty treści | prawdziwy kod HTTP, format RFC 9457 |
| Strony | page, max_rows do 500 | kursor, limit do 200 |
| Powtórzenie po przerwaniu | tworzy duplikat | Idempotency-Key — duplikatu nie będzie |
| Limit | 30 na minutę jako minimalny odstęp | 120 na kroczącą minutę, nagłówki RateLimit |
Jak przenieść klucz
- Otwórz kartę swojego klucza v1 w oknie „API i tokeny dostępu”.
- 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.
- 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.
- Skopiuj nowy klucz — jest pokazywany tylko raz.
1
W imieniu pracownika2
Zmiany danych3
Limit bezpieczeństwa: zmian na godzinę4
Bieżący klucz5
Tylko do odczytu- W imieniu pracownika — czyje uprawnienia i dane otrzymuje klucz. Innych pracowników widzi tylko osoba z dostępem do okna użytkowników.
- Zmiany danych — „Pytaj” (każda zmiana czeka w „Pulsie”) lub „Wykonuj samodzielnie”. Przełączyć może tylko „Zarząd”.
- Limit bezpieczeństwa — po tylu wykonanych zmianach w ciągu godziny klucz sam wraca do trybu „Pytaj”.
- Nowy klucz jest pokazywany raz: skopiuj go przyciskiem „Kopiuj”, zanim zamkniesz okno.
- 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
| v1 | v2 |
|---|---|
api/login + api_token | nagłówek Authorization: Bearer |
scope/describe scope=X | GET /api/v2/openapi.json lub GET /api/v2/ |
scope/get product / product_price / document / contractor / contractor_group / company / category / manufacturer / attribute / attribute_block | GET /products, /supplier_products, /documents (+ /document_items?filter[document_id]=), /contractors, /contractor_groups, /companies, /categories, /manufacturers, /attributes, /attribute_groups |
scope/get article | GET /articles |
scope/get document_type / document_status / document_payment_status / document_delivery_status / stock_status / warehouse / store / currency / language | GET /document_types, /document_statuses, /payment_statuses, /delivery_statuses, /stock_statuses, /warehouses, /stores, /currencies, /languages; nowe — /payment_types, /delivery_types |
scope/add document z zatwierdzeniem | POST /documents, potem POST /documents/{id}/sign |
scope/add X, X/add_batch | POST /X z Idempotency-Key, po jednym rekordzie |
scope/update X, X/update | PATCH /X/{id} |
scope/delete X, X/delete | DELETE /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 product | GET /products?q=… |
scope/add contractor_price | POST /price_lists/{id}/import — zadanie w tle |
scope/add mail_send | POST /mail_messages/{id}/reply — zawsze przez „Puls” |
scope/add document_extended, scope/get print_template | w 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 klucza | Parametr w zapytaniu | Co robi |
|---|---|---|
| „Użytkownik” | username | nazwa do logowania |
| „Klucz dostępu” | key | sekret; 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 widzisz | Dlaczego tak jest | Co 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 odrzucany | klucz ma „Tylko do odczytu”; ustawienie działa na wszystkie trasy, także stare | odznacz pole — działa od razu, bez ponownego logowania |
| Klucz przestał wpuszczać, choć jest aktywny | nadszedł 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 odpowiedzi | klucz v2 widzi tylko okna i pola swojego pracownika | otwó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
1
API i tokeny dostępu2
Inne ustawienia- API i tokeny dostępu — otwiera listę kluczy API.
- Inne ustawienia — zbiera okna, których nie ma w menu głównym.
Powiązane tematy
- Jeśli piszesz nową integrację — API v2: klucze, uprawnienia, format.
- Jeśli integracja działa jeszcze na v1 i trzeba znaleźć operację lub zrozumieć błąd — dokumentacja starego API v1.
- Jeśli integracja zapisuje produkty i ceny na działającym koncie — co API v1 robi z danymi.
- Jeśli do Elbuz trzeba podłączyć Claude lub ChatGPT — podłączyć asystenta AI.
- Jeśli kluczowi v2 trzeba zawęzić uprawnienia — użytkownicy i uprawnienia.
