↑↓ wybierzEnter otwórzEsc zamknij

    1. Elbuz

    API v2: jak podłączyć własny program do danych Elbuz

    14 min czytaniaZaktualizowano

    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

    Jak wydać klucz i co on widzi

    1. W oknie „API i tokeny dostępu” kliknij „+”. Otworzy się karta nowego klucza.
    2. 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.
    3. 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.
    4. Nowy klucz powstaje z zaznaczonym „Tylko do odczytu”. Jeśli integracja ma coś zmieniać — odznacz to pole.
    5. Kliknij „Utwórz klucz” i skopiuj wartość z pola „Nowy klucz” przyciskiem „Kopiuj”.
    Karta klucza API v2: w imieniu pracownika, tryb zmian danych, bezpiecznik i nowy klucz
    1W imieniu pracownika
    2Zmiany danych
    3Bezpiecznik: zmian na godzinę
    4Bieżący klucz
    5Tylko do odczytu
    1. W imieniu pracownika — czyje uprawnienia i dane dostaje klucz. Innych pracowników widzi tylko ten, kto ma dostęp do okna użytkowników.
    2. Zmiany danych — „Pytaj” (każda zmiana czeka w „Pulsie”) albo „Wykonuj samodzielnie”. Przełączyć może tylko „Zarząd”.
    3. Bezpiecznik — po tylu wykonanych zmianach w ciągu godziny klucz sam wraca do trybu „Pytaj”.
    4. Nowy klucz widać tylko raz: skopiuj go przyciskiem „Kopiuj”, zanim zamkniesz okno.
    5. 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: w errors przy 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

    ParametrCo robi
    limitrozmiar strony, domyślnie 50, najwyżej 200
    fields=product_id,namezostawić 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-01zmienione od daty — to samo co filter[date_modified][gte]
    sort=-quantitysortowanie 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ę

    ZapytanieCo 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.

    Propozycja klucza API w „Pulsie”: utworzenie kontaktu „Test API Ltd”
    1Zmiana przez API / MCP
    2Co dokładnie się zmieni
    3Akceptuj
    4Odrzuć
    5Przyjmij wszystkie z tego klucza
    6Akceptuj i odtąd wykonuj automatycznie
    1. Zmiana przez API / MCP — propozycja klucza; w tytule nazwa klucza i to, co chce zrobić.
    2. Wiersze pod tytułem pokazują: pole — było → będzie (dla nowego rekordu — wypełnione pola).
    3. Akceptuj — zmiana jest wykonywana od razu, a klucz dostaje wynik pod adresem propozycji (GET /api/v2/approvals/3629).
    4. Odrzuć — nic się nie zmienia, propozycja dostaje status rejected.
    5. Przyjmij wszystkie z tego klucza — wykonuje po kolei wszystkie oczekujące propozycje tego klucza; tryb klucza się nie zmienia.
    6. 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.

    Droga zapytania o zmianę: sprawdzenie uprawnień — zawsze; dalej tryb klucza decyduje, czy wykonać teraz, czy utworzyć propozycję
    taknienietaktakniePytajWykonuj samodzielnietaknieZapytanie POST, PATCH lubDELETEKlucz „Tylko do odczytu”?403, nic nie zmienionoUprawnienia właściciela kluczapozwalają?403, 404 lub 422 z przyczynąE-mail lub wiadomość do klienta?Propozycja w „Pulsie”, odpowiedź202Tryb kluczaBezpiecznik na godzinęwyczerpany?Klucz przechodzi w „Pytaj”, w„Pulsie” propozycja kontynuacjiWykonano od razu: 200, 201 lub204, wpis w „Co zrobiło AI”
    • Початок або кінець
    • Дія або результат
    • Розвилка: далі шлях залежить від відповіді

    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"}}
    KodtypeKiedy
    400bad_requestbrak Idempotency-Key, treść nie jest obiektem JSON, filtr po nieznanym polu, obcy kursor
    401unauthorizedbrak nagłówka, klucz błędny, wyłączony lub wygasły, pracownik-właściciel nieaktywny
    403forbiddenadres spoza „Adresy IP z dostępem”, klucz „Tylko do odczytu”, brak uprawnienia do przycisku
    404not_foundzasobu nie ma lub jego okno jest zamknięte, rekordu nie widać według „Czyje dane”
    405method_not_allowedzasób nie ma takiej operacji — np. DELETE /users/2
    409conflicttaki rekord już istnieje (np. kontrahent z tymi samymi danymi) — w errors jego id
    422unprocessablepola nie można zapisać, odwołanie do niewidocznego rekordu, ponowienie Idempotency-Key z inną treścią
    429rate_limitedprzekroczono 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óbOperacjeDziałania
    productswszystko, 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, manufacturerswszystko, usuwanie — nieodwracalne, propozycją w „Pulsie”merge
    attributeswszystko, usuwanie — nieodwracalne, propozycją w „Pulsie”merge
    attribute_groupswszystko, usuwanie — nieodwracalne, propozycją w „Pulsie”—
    supplier_products (wiersze cenników)lista, rekord—
    contractorswszystko, usuwanie — do koszamerge
    companies, contractor_groupslista, rekord (grupy — także tworzenie i edycja)—
    documents (+ document_items)wszystko, usuwanie — do koszasign, unsign
    orders (zamówienia klientów)lista, rekordPOST /orders/sync — zamówienia Twojego sklepu w paczce do 100: utworzyć nowe i zaktualizować już zaimportowane, szczegóły
    deals, pipelinestransakcje — wszystko, usuwanie do kosza; lejki — listamove_stage
    tasks, notes, projectswszystko, usuwanie — do koszadone, reopen
    touches (follow-upy w kalendarzu)wszystko, usuwanie — nieodwracalne, propozycją w „Pulsie”—
    mail_messages, chats, chat_messages, callstylko odczytreply, send — zawsze przez „Puls”
    pulse_itemslista, rekordaccept, reject, accept_trust, undo
    userstylko odczyt, bez haseł i kluczy logowania—
    articleswszystko, usuwanie — do kosza—
    price_lists, export_templates, flowslista, rekordimport / run — zadanie w tle
    import_templates, jobs, sales_reporttylko odczyt—
    payroll (listy płac z wierszami i podsumowaniami)tylko odczyt; filtry filter[period]=2026-10, filter[company_id], filter[status]—
    webhooks, webhook_deliverieswebhooki tego klucza—
    słowniki: document_types, document_statuses, payment_statuses, delivery_statuses, payment_types, delivery_types, stock_statuses, warehouses, stores, currencies, languagestylko 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 produktu sku, 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

    Najczęstsze problemy
    Co widziszDlaczego tak jestCo zrobić
    401 „invalid, disabled or expired key”klucz wydano ponownie, odznaczono „Aktywność” albo minęła data wygaśnięciasprawdź kartę klucza (wydanie klucza)
    Na PATCH przychodzi 202, a dane się nie zmieniłyklucz 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 okniepole jest zamknięte dla grupy właściciela kluczaotwó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 filtramizacznij 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

    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