API v2 daje Twojemu programowi dostęp do katalogu, cenników, klientów, dokumentów, transakcji i organizera Elbuz z uprawnieniami jednego pracownika: zapytanie widzi i zmienia dokładnie to, co ten pracownik w oknach. Zmiany domyślnie czekają na zatwierdzenie w „Pulsie”.
Kiedy to się przyda:
- Strona ma pobierać ceny i stany — listę zmienionych produktów czyta się kursorem, bez luk.
- Zamówienia ze strony mają trafiać do Elbuz — ponowienie po zerwaniu połączenia nie utworzy duplikatu.
- Podwykonawca edytuje dane — każda jego zmiana trafia do „Pulsu” jako „było → będzie”.
- Integracja nie powinna widzieć wszystkiego — klucz dostaje okna, pola i „Czyje dane” swojego pracownika.
Od czego zacząć: wydaj klucz w oknie „API i tokeny dostępu”.
Co potrafi API v2
- Czytać listy z filtrami i kursorem — produkty, wiersze cenników, klientów, dokumenty, transakcje, zadania, e-maile, połączenia.
- Tworzyć i zmieniać rekordy — propozycją w „Pulsie” albo od razu, jeśli klucz ma na to zgodę.
- Wykonywać działania — zatwierdzić dokument, scalić duplikaty, uruchomić import cennika lub eksport.
- Nie tworzyć duplikatów przy ponowieniu zapytania po zerwaniu połączenia.
- Ograniczać dostęp uprawnieniami pracownika — bez osobnych ustawień w kluczu.
- Powiadamiać o zmianach webhookami, żeby nie odpytywać co minutę.
Jak wydać klucz i co on widzi
- W oknie „API i tokeny dostępu” kliknij „+”. Otworzy się karta nowego klucza.
- W polu „W imieniu pracownika” wybierz, czyje uprawnienia dostanie klucz. Listę pracowników widzi tylko ten, kto ma dostęp do okna użytkowników; pozostali wydają klucz wyłącznie na siebie.
- Pole „Użytkownik” to nazwa klucza. Pojawia się w tytułach propozycji w „Pulsie” („Klucz «site_sync»: zmienić produkt…”), więc nazwij klucz tak, by było jasne, czyja to integracja.
- Nowy klucz powstaje z zaznaczonym „Tylko do odczytu”. Jeśli integracja ma coś zmieniać — odznacz to pole.
- Kliknij „Utwórz klucz” i skopiuj wartość z pola „Nowy klucz” przyciskiem „Kopiuj”.
1
W imieniu pracownika2
Zmiany danych3
Bezpiecznik: zmian na godzinę4
Bieżący klucz5
Tylko do odczytu- W imieniu pracownika — czyje uprawnienia i dane dostaje klucz. Innych pracowników widzi tylko ten, kto ma dostęp do okna użytkowników.
- Zmiany danych — „Pytaj” (każda zmiana czeka w „Pulsie”) albo „Wykonuj samodzielnie”. Przełączyć może tylko „Zarząd”.
- Bezpiecznik — po tylu wykonanych zmianach w ciągu godziny klucz sam wraca do trybu „Pytaj”.
- Nowy klucz widać tylko raz: skopiuj go przyciskiem „Kopiuj”, zanim zamkniesz okno.
- Tylko do odczytu — zaznaczone w nowym kluczu; odznacz, jeśli klucz ma coś zmieniać.
Klucz jest pokazywany tylko raz. W bazie zapisuje się wyłącznie jego skrót (SHA-256) i pierwsze osiem znaków po elbz_ — po nich rozpoznasz klucz na liście („elbz_6caef5fd_…”). Zgubiony klucz? Kliknij „Utwórz nowy klucz”: stary przestaje działać w tej samej sekundzie, więc od razu podmień go w integracji.
Pozostałe pola karty działają przy każdym zapytaniu, bez ponownego wydawania klucza: odznaczone „Aktywność” — następne zapytanie dostanie 401; „Data wygaśnięcia dostępu” — klucz działa do tej daty włącznie; „Adresy IP z dostępem” — lista rozdzielona przecinkiem, spacją lub nową linią, puste pole — dostęp zewsząd.
Co widzi klucz
Zapytanie wykonuje się tak, jakby pracownik otworzył odpowiednie okno. Dlatego:
- Zasób jest dostępny, jeśli pracownik ma otwarte jego okno: produkty — okno produktów, dokumenty — dowolne z okien dokumentów. Nie ma okna — nie ma zasobu ani w opisie, ani na listach (404).
- Pole zamknięte do podglądu dla grupy pracownika (np. „Koszt własny”
price_cost) w ogóle nie występuje w odpowiedzi i nie można po nim filtrować. Pole, którego grupa pracownika nie może zmieniać, daje 422 przy zapisie: werrorsprzy polu jest przyczyna, dla produktu — „Zmiana tego pola jest zabroniona”. - „Czyje dane” działają tak samo jak w oknie: menedżer z „Tylko własne” dostanie tylko swoich klientów i swoje dokumenty; cudzy rekord po id — 404.
- Przyciski okna: tworzenie, usuwanie, zatwierdzanie dokumentu są sprawdzane według uprawnień do odpowiednich przycisków.
Osobnych „scope’ów” klucz nie ma. Aby zawęzić integrację, wydaj klucz pracownikowi z węższymi uprawnieniami — na przykład załóż użytkownika w dziale, który ma otwarte tylko okno zamówień.
Pierwsze zapytanie i format odpowiedzi
<twoja-domena> w przykładach to subdomena lub domena, pod którą otwierasz Elbuz. Jeśli Elbuz otwiera się na app.elbuz.com, dodaj do adresu zapytania parametr user_domain=<numer Twojego konta>: https://app.elbuz.com/api/v2/products?user_domain=123456789&limit=2. Gotowy adres swojego konta widać w karcie klucza, w wierszu „Opis metod (OpenAPI)”.
curl -s "https://<twoja-domena>/api/v2/products?limit=2&fields=product_id,name,price,quantity" \
-H "Authorization: Bearer elbz_xxxxxxxx_…"
Odpowiedź (konto demo, 14.10.2026):
{"data":[
{"product_id":1,"price":"4536","quantity":100,"name":"Marshall Willen Black and Brass (1006059)"},
{"product_id":2,"price":"0","quantity":0,"name":"ADATA 16 GB DDR4 3600 MHz XPG Spectrix D41 RGB Tungsten Gray (AX4U360016G18I-ST41)"}],
"has_more":true,
"next_cursor":"eyJrIjoiMiIsImgiOiJiZTExNWY1MSJ9"}
Format jest taki sam dla wszystkich zasobów: lista — {"data":[…],"has_more":…,"next_cursor":…}, pojedynczy rekord — {"data":{…}}. Wartości przychodzą tak:
- id, odwołania do innych rekordów, ilości i liczniki — jako liczby;
- flagi w rodzaju
flag_export—true/false; - kwoty i miary — jako ciąg dziesiętny (
"4536"); - kody zewnętrzne (
sku,uuid, kody kreskowe) — jako ciąg; - daty — w formacie RFC 3339 z przesunięciem strefy czasowej (
"2026-10-14T12:42:59+02:00").
Parametr fields= działa zarówno dla listy, jak i dla pojedynczego rekordu (GET /products/2?fields=product_id,sku,price). Nagłówek Accept-Language: pl przełącza język nazw pól w opisie zasobów.
Pełny opis wszystkich zasobów, pól i metod — GET /api/v2/openapi.json (OpenAPI 3.1) z tym samym kluczem; bez klucza — 401. Opis budowany jest pod uprawnienia właściciela klucza: nie ma w nim zasobów ani pól, których pracownik nie widzi. Krótki wykaz — GET /api/v2/: dla każdego zasobu operacje, działania i pola z oznaczeniami filter, sort, write.
Jak czytać listy: filtry, sortowanie, kursor
| Parametr | Co robi |
|---|---|
limit | rozmiar strony, domyślnie 50, najwyżej 200 |
fields=product_id,name | zostawić w odpowiedzi tylko te pola listy |
filter[pole]=wartość | równa się |
filter[pole][operator]=wartość | operatory ne, gt, gte, lt, lte, like (zawiera) |
filter[updated_since]=2026-10-01 | zmienione od daty — to samo co filter[date_modified][gte] |
sort=-quantity | sortowanie według jednego pola; minus — malejąco. Drugie pole po przecinku jest ignorowane |
q= | szybkie wyszukiwanie tekstowe (produkty) |
cursor= | wartość next_cursor z poprzedniej strony |
Filtrować i sortować można tylko według pól oznaczonych w opisie zasobu jako filter / sort. Nieznane pole — 400 z wyjaśnieniem: {"errors":{"nosuch":"not filterable"}}.
Jak działa kursor. Bez sort rekordy idą rosnąco po id, a kursor zapamiętuje ostatnie id: nowe rekordy, które pojawiły się w trakcie przeglądania, nie przesuwają stron. Z sort kursor zapamiętuje numer strony, więc rekord, który w trakcie przeglądania zmienił pozycję w sortowaniu, może trafić się dwa razy albo wypaść. Do synchronizacji używaj wariantu bez sort.
Kursor jest powiązany z filtrami i sortowaniem zapytania: zmienione filtry ze starym kursorem — 400 cursor does not match the query. Koniec listy — "has_more":false i "next_cursor":null.
Słowniki (currencies, warehouses, document_statuses i inne) są zwracane w całości, do 500 wierszy, bez kursora. Pozycje dokumentu — tylko razem z dokumentem: GET /api/v2/document_items?filter[document_id]=123; bez filtra — 400.
curl -s -g "https://<twoja-domena>/api/v2/products?filter[quantity][gt]=5&fields=product_id,name,quantity&limit=100" \
-H "Authorization: Bearer elbz_…"
Co się dzieje z zapytaniem o zmianę
| Zapytanie | Co robi |
|---|---|
POST /api/v2/{zasób} | utworzyć rekord |
PATCH /api/v2/{zasób}/{id} | zmienić przekazane pola (pozostałe zostają bez zmian) |
DELETE /api/v2/{zasób}/{id} | usunąć rekord: kontrahenta, dokument, transakcję, zadanie, notatkę, projekt, artykuł — do kosza; produkt, kategorię, producenta, atrybut, grupę atrybutów, follow-up — nieodwracalnie i domyślnie tylko propozycją w „Pulsie” (szczegóły); inne zasoby nie mają usuwania — 405 |
POST /api/v2/{zasób}/{id}/{działanie} | działanie: zatwierdzić dokument, scalić duplikaty, uruchomić eksport itp. |
Co stanie się z zapytaniem, decyduje pole „Zmiany danych” w karcie klucza.
„Pytaj (przez „Puls”)” — wartość domyślna. Elbuz sprawdza zapytanie uprawnieniami właściciela klucza (zasób, pole, przycisk, „Czyje dane”) i jeśli wszystko się zgadza, niczego nie zmienia, tylko tworzy propozycję w „Pulsie”. Integracja dostaje 202 Accepted i adres, pod którym śledzi decyzję:
HTTP/1.1 202 Accepted
Location: /api/v2/approvals/3629
{"data":{"status":"pending","approval_id":3629}}
Propozycję widzą pracownicy z dostępem do okna kluczy API: nazwę klucza, co chce zrobić, oraz starą i nową wartość każdego pola.
1
Zmiana przez API / MCP2
Co dokładnie się zmieni3
Akceptuj4
Odrzuć5
Przyjmij wszystkie z tego klucza6
Akceptuj i odtąd wykonuj automatycznie- Zmiana przez API / MCP — propozycja klucza; w tytule nazwa klucza i to, co chce zrobić.
- Wiersze pod tytułem pokazują: pole — było → będzie (dla nowego rekordu — wypełnione pola).
- Akceptuj — zmiana jest wykonywana od razu, a klucz dostaje wynik pod adresem propozycji (GET /api/v2/approvals/3629).
- Odrzuć — nic się nie zmienia, propozycja dostaje status rejected.
- Przyjmij wszystkie z tego klucza — wykonuje po kolei wszystkie oczekujące propozycje tego klucza; tryb klucza się nie zmienia.
- Akceptuj i odtąd wykonuj automatycznie — wykonuje propozycję i przełącza klucz na „Wykonuj samodzielnie” (tylko „Zarząd”).
GET /api/v2/approvals/3629 zwraca status: pending — czeka, approved — zaakceptowano i wykonano (w result — rekord po zmianie), auto — wykonano bez człowieka w trybie „Wykonuj samodzielnie”, rejected — odrzucono, nic nie zmieniono, error — zaakceptowano, ale wykonanie się nie powiodło, undone — zmianę cofnięto w „Co zrobiło AI”. Klucz widzi tylko swoje propozycje.
„Wykonuj samodzielnie” — zmiana wykonuje się od razu: utworzenie odpowiada 201 z nagłówkiem Location, edycja — 200 z rekordem po zmianie (w obu — także approval_id), usunięcie — 204 bez treści.
Każda zmiana i tak trafia do „Pulsu” ze statusem „AI wykonało samo” i jest widoczna w zakładce „Co zrobiło AI”, skąd można ją cofnąć. Włączyć „Wykonuj samodzielnie” może tylko „Zarząd”.
Bezpiecznik. Jeśli klucz w trybie „Wykonuj samodzielnie” wykonał w ciągu godziny tyle zmian, ile wpisano w polu „Bezpiecznik: zmian na godzinę” (domyślnie 500), następna zmiana już się nie wykonuje: klucz sam przełącza się na „Pytaj”, a w „Pulsie” pojawia się propozycja „Klucz «…» wprowadził N zmian w ciągu godziny i został wstrzymany — kontynuować bez potwierdzenia?”.
Dopóki nie zostanie zaakceptowana, wszystkie zmiany klucza idą jako propozycje (202).
Niezależnie od trybu klucza: odpowiedź klientowi na e-mail (/mail_messages/{id}/reply) i wiadomość na czacie (/chats/{id}/send) stają się propozycją w „Pulsie” własnego typu — jak e-maile przygotowywane przez samo AI Elbuz. Czekają na człowieka, dopóki „Zarząd” nie włączy dla tego typu „Wykonuj samodzielnie” w zakładce „Zaufanie”, a e-maila nie przepuści pracownik AI „Kontroler”.
- Klucz z „Tylko do odczytu” na każdą próbę zapisu dostaje 403.
- Własne subskrypcje webhooków klucz zmienia sam, bez propozycji.
Usuwanie produktów, kategorii, producentów, atrybutów i follow-upów
Te zasoby nie mają kosza: DELETE wywołuje tę samą funkcję co przycisk usuwania w oknie, a rekord znika na zawsze. Dlatego takie usunięcie domyślnie zawsze staje się propozycją w „Pulsie” (202) — niezależnie od trybu klucza, nawet w „Wykonuj samodzielnie”.
Od razu (204) usuwa tylko klucz, w którego karcie w bloku „Zachowanie zapytań” włączono „Zezwalaj na usuwanie bez potwierdzenia”. Tę opcję zmienia tylko „Zarząd”, a bezpiecznik zmian na godzinę działa także tutaj. Kluczy pracowników AI opcja nie dotyczy: usuwają tylko przez „Puls”. Takiego usunięcia nie da się cofnąć.
- Produkt — razem z jego produktami-opcjami, zdjęciami, plikami, wideo i kartą na stronie.
- Kategoria — z całą gałęzią podkategorii i produktami, dla których kategoria z gałęzi jest główna.
- Atrybut — razem z wartościami we wszystkich produktach.
- Grupa atrybutów — jej atrybuty przechodzą do grupy domyślnej; samej grupy domyślnej nie można usunąć (422).
Uprawnienie — to samo co w oknie: bez prawa do przycisku usuwania (dla produktów — „Usuń produkt”, dla kategorii — „Usuń kategorię”) klucz dostaje 403. Przez MCP usuwania nie ma wcale.
- Початок або кінець
- Дія або результат
- Розвилка: далі шлях залежить від відповіді
Co można cofnąć
Przycisk cofnięcia w „Co zrobiło AI” jest dla: edycji pól dowolnego zasobu (przywraca poprzednie wartości), utworzenia i usunięcia kontrahenta, dokumentu, transakcji, zadania, notatki, projektu, artykułu (przez kosz), utworzenia produktu, kategorii, producenta, atrybutu, grupy atrybutów i follow-upu (cofnięcie usuwa utworzony rekord nieodwracalnie), zatwierdzenia i cofnięcia zatwierdzenia, oznaczenia zadania jako „wykonane”.
Edycji pól nie da się cofnąć, jeśli te pola zmieniono już po API — odpowiedź „cofnij ręcznie”. Przycisku nie ma dla usunięcia produktu, kategorii, producenta, atrybutu, grupy atrybutów i follow-upu (nie mają kosza), utworzenia grupy kontrahentów, scalania duplikatów, przeniesienia transakcji na etap i uruchamiania zadań w tle.
Jak nie utworzyć duplikatu: Idempotency-Key
Każdy POST (tworzenie i działania) musi mieć nagłówek Idempotency-Key — dowolny unikalny ciąg do 255 znaków, np. . Bez niego — 400. Odpowiedź jest przechowywana 24 godziny: ponowienie z tym samym kluczem i tą samą treścią nie tworzy duplikatu, tylko zwraca zapisaną odpowiedź z nagłówkiem Idempotent-Replayed: true. Ten sam klucz z inną treścią — 422.
curl -s -X POST "https://<twoja-domena>/api/v2/contractors" \
-H "Authorization: Bearer elbz_…" -H "Content-Type: application/json" \
-H "Idempotency-Key: order-sync-2026-10-14-0001" \
-d '{"name":"Test API sp. z o.o.","email":"test-api@example.com"}'
Odpowiedź z błędem (400, 422) też jest zapamiętywana pod tym kluczem. Poprawiona treść — weź nowy Idempotency-Key, inaczej dostaniesz 422 „Idempotency-Key was used with another request”. Nie są zapisywane tylko 429 i błędy serwera.
Błędy i limity
Błędy przychodzą w formacie RFC 9457 (application/problem+json) z prawdziwym kodem HTTP:
{"type":"https://elbuz.com/problems/unprocessable","title":"Unprocessable","status":422,
"detail":"some fields cannot be written","errors":{"date_modified":"not writable"}}
| Kod | type | Kiedy |
|---|---|---|
| 400 | bad_request | brak Idempotency-Key, treść nie jest obiektem JSON, filtr po nieznanym polu, obcy kursor |
| 401 | unauthorized | brak nagłówka, klucz błędny, wyłączony lub wygasły, pracownik-właściciel nieaktywny |
| 403 | forbidden | adres spoza „Adresy IP z dostępem”, klucz „Tylko do odczytu”, brak uprawnienia do przycisku |
| 404 | not_found | zasobu nie ma lub jego okno jest zamknięte, rekordu nie widać według „Czyje dane” |
| 405 | method_not_allowed | zasób nie ma takiej operacji — np. DELETE /users/2 |
| 409 | conflict | taki rekord już istnieje (np. kontrahent z tymi samymi danymi) — w errors jego id |
| 422 | unprocessable | pola nie można zapisać, odwołanie do niewidocznego rekordu, ponowienie Idempotency-Key z inną treścią |
| 429 | rate_limited | przekroczono limit zapytań |
Każda odpowiedź ma nagłówek X-Request-Id — podaj go pomocy technicznej, a zapytanie zostanie odnalezione w dzienniku.
Limit — 120 zapytań na kroczącą minutę na klucz (więcej — tylko jeśli pomoc techniczna podniosła limit temu kluczowi); zapytania asystenta MCP tym samym kluczem liczą się do tego samego limitu. Ile zostało, widać w nagłówkach każdej odpowiedzi: RateLimit-Policy: "default";q=120;w=60 i RateLimit: "default";r=119;t=60 (r — ile zostało, t — sekund do zwolnienia). Przy 429 przyjdzie Retry-After — odczekaj podaną liczbę sekund.
Dlaczego 422 po PATCH, a część pól jest już zapisana
W produktach, producentach, kontrahentach, dokumentach i transakcjach pola zapisują się pojedynczo, tą samą drogą co edycja komórki w tabeli okna; w pozostałych zasobach — jednym wywołaniem funkcji zapisu. Pole, którego nie ma w opisie zasobu, pole techniczne albo zamknięte uprawnieniami jest odrzucane przed zapisem całego zapytania — 422 z listą pól.
Jeśli jednak w zasobie z zapisem pojedynczych pól jedno pole odrzuciła walidacja samego programu (niedozwolona wartość lub zakaz zmiany pola dla grupy — „Zmiana tego pola jest zabroniona”), odpowiedź też jest 422, ale pozostałe pola z tego samego zapytania są już zapisane: przed ponowieniem odczytaj rekord przez GET.
Jakie są zasoby
Poniższy zestaw dotyczy pracownika z pełnym dostępem; klucz dostaje tylko te zasoby, których okna są otwarte dla właściciela.
| Zasób | Operacje | Działania |
|---|---|---|
products | wszystko, usuwanie — nieodwracalne, propozycją w „Pulsie” | POST /products/batch — do 100 produktów na zapytanie: z product_id edycja, bez niego utworzenie; sekcje karty (texts, categories, attributes, images, stores i inne); enrich — wyszukiwanie treści, zawsze propozycją w „Pulsie” |
categories, manufacturers | wszystko, usuwanie — nieodwracalne, propozycją w „Pulsie” | merge |
attributes | wszystko, usuwanie — nieodwracalne, propozycją w „Pulsie” | merge |
attribute_groups | wszystko, usuwanie — nieodwracalne, propozycją w „Pulsie” | — |
supplier_products (wiersze cenników) | lista, rekord | — |
contractors | wszystko, usuwanie — do kosza | merge |
companies, contractor_groups | lista, rekord (grupy — także tworzenie i edycja) | — |
documents (+ document_items) | wszystko, usuwanie — do kosza | sign, unsign |
orders (zamówienia klientów) | lista, rekord | POST /orders/sync — zamówienia Twojego sklepu w paczce do 100: utworzyć nowe i zaktualizować już zaimportowane, szczegóły |
deals, pipelines | transakcje — wszystko, usuwanie do kosza; lejki — lista | move_stage |
tasks, notes, projects | wszystko, usuwanie — do kosza | done, reopen |
touches (follow-upy w kalendarzu) | wszystko, usuwanie — nieodwracalne, propozycją w „Pulsie” | — |
mail_messages, chats, chat_messages, calls | tylko odczyt | reply, send — zawsze przez „Puls” |
pulse_items | lista, rekord | accept, reject, accept_trust, undo |
users | tylko odczyt, bez haseł i kluczy logowania | — |
articles | wszystko, usuwanie — do kosza | — |
price_lists, export_templates, flows | lista, rekord | import / run — zadanie w tle |
import_templates, jobs, sales_report | tylko odczyt | — |
payroll (listy płac z wierszami i podsumowaniami) | tylko odczyt; filtry filter[period]=2026-10, filter[company_id], filter[status] | — |
webhooks, webhook_deliveries | webhooki tego klucza | — |
słowniki: document_types, document_statuses, payment_statuses, delivery_statuses, payment_types, delivery_types, stock_statuses, warehouses, stores, currencies, languages | tylko odczyt, całą listą | — |
Działania z zadaniem w tle (/price_lists/{id}/import, /export_templates/{id}/run, /flows/{id}/run) odpowiadają {"data":{"status":"queued","job_id":…}}, w trybie „Pytaj” — najpierw 202 i propozycją w „Pulsie”; postęp — GET /api/v2/jobs/{id}. Agregaty („ile zamówień według statusów”, „suma sprzedaży według menedżerów”) — GET /api/v2/query?spec={…}; lista encji i pól — ?spec={"describe":true}.
Pozycje dokumentu: produkt po product_id lub po nazwie
Pozycje dokumentu przekazuje się w POST /api/v2/documents tablicą item_list. Pozycja bez product_id, ale z name, też się zapisuje — Elbuz sam dobiera do niej produkt:
- najpierw szuka po kodzie kreskowym
ean, potem po kodzie produktusku, potem po dokładnej nazwie. Nazwa jest porównywana bez względu na wielkość liter, nadmiarowe spacje i cudzysłowy i zaliczana tylko wtedy, gdy produkt o takiej nazwie jest w bazie jeden; - jeśli nie znajdzie — tworzy nowy produkt z nazwą, kodem, kodem kreskowym i ceną pozycji w kategorii technicznej „Produkty - api_v2 - …”. Dokument, który asystent MCP lub agent AI w przeglądarce tworzy bez zatwierdzenia w „Pulsie”, umieszcza nowe produkty w „Produkty - mcp - …” lub „Produkty - ai - …”. Kategoria powstaje wyłączona i bez eksportu.
W dokumencie nie ma pozycji bez produktu: pozycja bez product_id i bez name nie jest zapisywana. product_id, którego nie ma w bazie albo którego klucz nie widzi, — 422 przed utworzeniem dokumentu, w errors — "item_list.0.product_id": "not found" (numer to pozycja w tablicy).
curl -s -X POST "https://<twoja-domena>/api/v2/documents" \
-H "Authorization: Bearer elbz_…" -H "Content-Type: application/json" \
-H "Idempotency-Key: order-1042" \
-d '{"type_id":3,"contractor_id":15,"item_list":[
{"product_id":2,"quantity":1,"price":"1890"},
{"name":"Kabel HDMI 2.1, 2 m","sku":"HDMI-21-2M","ean":"5900000000017","quantity":3,"price":"250"}]}'
Żeby produkty się nie mnożyły, przekazuj w pozycji product_id (zwraca go GET /products), a jeśli go nie masz — przynajmniej ean lub sku, takie same jak w karcie produktu w Elbuz. Wyszukiwanie po nazwie działa tylko przy dokładnym i jedynym dopasowaniu: inna nazwa w zamówieniu albo dwa produkty o tej samej nazwie — i powstaje nowa karta.
Nowe karty trafiają do kategorii technicznych „Produkty - api_v2 - …”: zaglądaj tam, żeby zauważyć pozycje, których Elbuz nie rozpoznał.
Scenariusze
Strona pobiera stany i ceny
Klucz w imieniu pracownika, który ma otwarte tylko okno produktów, z „Tylko do odczytu”. Co 10 minut — GET /products?filter[updated_since]=…&fields=product_id,sku,price,quantity bez sort, przeglądanie kursorem. Cena zakupu nie trafi do odpowiedzi, jeśli jej pole jest zamknięte dla grupy tego pracownika.
Zamówienia ze strony bez duplikatów
Klucz w trybie „Wykonuj samodzielnie” w imieniu menedżera działu sprzedaży. Nowe i zmienione zamówienia strona wysyła paczką do POST /orders/sync: Elbuz sam rozpozna już zaimportowane zamówienie po jego numerze na stronie i zaktualizuje płatność, dostawę i status, nie nadpisując statusu ustawionego przez menedżera. Format i zasady — zamówienia sklepu przez API.
Podwykonawca edytuje opisy, a Ty sprawdzasz
Klucz w trybie „Pytaj” w imieniu pracownika z uprawnieniem do okna produktów. Każdy PATCH trafia do „Pulsu” wierszem „Opis pełny: … → …”. Jeśli poprawki są dobre — „Przyjmij wszystkie z tego klucza”; jeśli ufasz wykonawcy — „Akceptuj i odtąd wykonuj automatycznie”.
Co zrobić, gdy zapytanie nie przechodzi
| Co widzisz | Dlaczego tak jest | Co zrobić |
|---|---|---|
| 401 „invalid, disabled or expired key” | klucz wydano ponownie, odznaczono „Aktywność” albo minęła data wygaśnięcia | sprawdź kartę klucza (wydanie klucza) |
| Na PATCH przychodzi 202, a dane się nie zmieniły | klucz jest w trybie „Pytaj” | zaakceptuj propozycję w „Pulsie” albo przełącz klucz (zmiany) |
| 403 „read-only key” | nowy klucz ma zaznaczone „Tylko do odczytu” | odznacz to pole w karcie klucza |
| W odpowiedzi brakuje pola, które jest w oknie | pole jest zamknięte dla grupy właściciela klucza | otwórz pole w uprawnieniach grupy albo wydaj klucz innemu pracownikowi |
| 422 „Idempotency-Key was used with another request” | ten sam klucz idempotencji z inną treścią | nowy Idempotency-Key (szczegóły) |
| 400 „cursor does not match the query” | kursor z zapytania z innymi filtrami | zacznij przeglądanie bez cursor |
Najczęstsze pytania
Czy można dać kluczowi dostęp tylko do zamówień?
Tak: wydaj klucz w imieniu pracownika, który ma otwarte tylko okno zamówień. Klucz dostaje uprawnienia konkretnego pracownika — okna, pola i „Czyje dane”.
Dlaczego zmiana przez API zwraca 202?
Klucz jest w trybie „Pytaj”: zmiana czeka na zatwierdzenie w „Pulsie”. Status — GET /api/v2/approvals/{id}. Aby zmieniać od razu, „Zarząd” przełącza klucz na „Wykonuj samodzielnie”.
Ile zapytań na minutę jest dozwolonych?
120 na kroczącą minutę na klucz, łącznie z zapytaniami MCP tym samym kluczem. Ile zostało — w nagłówku RateLimit, przy 429 — Retry-After.
Gdzie jest opis wszystkich metod?
GET https://<twoja-domena>/api/v2/openapi.json z kluczem w nagłówku (konto na app.elbuz.com — https://app.elbuz.com/api/v2/openapi.json?user_domain=<numer konta>; dokładny adres — w karcie klucza). Opis jest przygotowany pod uprawnienia właściciela klucza.
Czy można usunąć produkt przez API?
Tak, ale nieodwracalnie: produkty, kategorie, producenci, atrybuty, grupy atrybutów i follow-upy nie mają kosza. Domyślnie takie usunięcie jest propozycją w „Pulsie”; od razu — tylko kluczem z opcją „Zezwalaj na usuwanie bez potwierdzenia”. Do kosza przez API trafiają kontrahenci, dokumenty, transakcje, zadania, notatki, projekty i artykuły. Duplikaty kontrahentów, kategorii, producentów i atrybutów scala się działaniem merge.
Czy można zapisać kilka rekordów jednym zapytaniem?
Produkty i zamówienia: POST /products/batch przyjmuje do 100 produktów na zapytanie (z product_id — edycja, bez niego — utworzenie), POST /orders/sync — do 100 zamówień. Pozostałe rekordy — każdy osobnym zapytaniem; planuj wolumen pod 120 zapytań na minutę.
Czy stary api_token działa z v2?
Nie. api_token i logowanie api/login działają tylko ze starym API. Jak przenieść integrację — przejście na v2.
Gdzie to jest i kto ma dostęp
- Menu
- „Panel klienta” → „Ustawienia systemu” → „Inne ustawienia” → kafelek „API i tokeny dostępu”
- Adres API
https://<twoja-domena>/api/v2/; konto na app.elbuz.com —https://app.elbuz.com/api/v2/…?user_domain=<numer konta>- Uprawnienia
- okno „API i tokeny dostępu”; klucz dla innego pracownika — także dostęp do okna użytkowników
- Tryb „Wykonuj samodzielnie”
- włącza tylko „Zarząd”
- Przygotuj
- pracownika z takimi uprawnieniami, jakie ma dostać integracja
Powiązane tematy
- Jeśli dane mają czytać Claude, ChatGPT lub Cursor — podłącz asystenta AI przez MCP tym samym kluczem.
- Jeśli nie chcesz co minutę odpytywać API — webhooki API v2.
- Jeśli integracja wciąż używa
api/login— stare API v1 i przejście na v2. - Jeśli klucz nie widzi potrzebnych pól — użytkownicy i uprawnienia.
- Jeśli propozycji klucza w „Pulsie” jest dużo — „Puls”: akceptacja, zaufanie, cofanie.
