↑↓ вибірEnter відкритиEsc закрити

    1. Elbuz
    2. Керівництво користувача Elbuz
    3. AI-агенти, MCP і API

    Старий API Elbuz (v1): ключ і перехід на API v2

    8 хв читанняОновлено

    Старий API Elbuz (v1) працює далі для вже виданих ключів v1, але нових можливостей у ньому не буде. Нові ключі видаються для API v2: з правами конкретного співробітника, підтвердженням змін у «Пульсі» й захистом від дублів.

    Коли це знадобиться:

    • Інтеграція працює через api/login — що чим замінити у v2, зведено в таблицю.
    • Новий ключ відповідає «некоректний ключ» — він уже для API v2 і з api/login не працює.
    • Підряднику треба відкрити лише замовлення — ключ v2 від імені співробітника бачить тільки його вікна.
    • Ключ треба закрити негайно — «Активність» і дата закінчення діють і на вже виданий токен.

    З чого почати: переведіть ключ на v2 у його картці.

    Що є в старому API

    Як перевести інтеграцію на API v2

    Кожна відповідь старого несе заголовки Deprecation: @1791936000 (14.10.2026) і Link: </api/v2/openapi.json>; rel="successor-version", <https://elbuz.com/guide-api>; rel="deprecation". Дати вимкнення v1 немає, але нових можливостей у ньому не буде: ключ v1 працює з правами адміністратора, без прав співробітника й без журналу його дій.

    v1 (цей довідник)v2
    Вхідapi/login → api_token у тілі або адресізаголовок Authorization: Bearer elbz_… на кожному запиті, без сеансу
    Праваяк у адміністратора, на весь акаунтяк у співробітника, від імені якого виданий ключ: вікна, поля, «Чиї дані»
    Змінивиконуються одразуза режимом ключа: заявка в «Пульсі» (202) або одразу
    Помилкикод 200, три різні формати тіласправжній код HTTP, формат RFC 9457
    Сторінкиpage, max_rows до 500курсор, limit до 200
    Повтор після обривустворює дубльIdempotency-Key — дубля не буде
    Ліміт30 на хвилину як мінімальний проміжок120 за ковзну хвилину, заголовки RateLimit

    Як перевести ключ

    1. Відкрийте картку свого ключа v1 у вікні «API та токени доступу».
    2. У полі «Від імені співробітника» оберіть, чиї права отримає інтеграція. Ключ v1 бачив усе — перевірте, що співробітнику відкриті всі потрібні вікна й поля, інакше після переходу частина даних зникне з відповідей.
    3. Натисніть «Створити новий ключ» і підтвердьте «Новий ключ замінить поточний: інтеграції зі старим ключем перестануть працювати». Старі «Користувач» + «Ключ доступу» і вже видані токени перестають діяти одразу — переведіть інтеграцію в ту ж хвилину або заведіть для v2 окремий ключ «+» і переключайтеся, коли код буде готовий.
    4. Скопіюйте новий ключ — він показується один раз.
    Картка ключа API v2: від імені співробітника, режим змін, запобіжник і новий ключ
    1Від імені співробітника
    2Зміни даних
    3Новий ключ
    4Тільки для читання
    1. Від імені співробітника — чиї права й «Чиї дані» отримає ключ. Інших співробітників тут бачить лише той, у кого є доступ до вікна користувачів.
    2. Зміни даних — «Питати» (кожна зміна чекає в «Пульсі») або «Робити самому». Перемикає лише «Управління».
    3. Новий ключ показується один раз: скопіюйте його кнопкою «Копіювати» до закриття вікна.
    4. Тільки для читання — у ключа, створеного кнопкою «+», ввімкнено; у ключа, переведеного з v1, лишається як було.

    Новий ключ створюється в режимі «Питати (через «Пульс»)»: кожна зміна чекає підтвердження в «Пульсі». Інтеграції, яка має писати одразу (замовлення з сайту, ціни з облікової системи), «Управління» ставить у картці ключа «Робити самому». Докладно — API v2: зміни.

    Що чим замінюється

    v1v2
    api/login + api_tokenзаголовок Authorization: Bearer
    scope/describe scope=XGET /api/v2/openapi.json або 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; нові — /payment_types, /delivery_types
    scope/add document з проведеннямPOST /documents, потім POST /documents/{id}/sign
    scope/add X, X/add_batchPOST /X з Idempotency-Key, по одному запису
    scope/update X, X/updatePATCH /X/{id}
    scope/delete X, X/deleteDELETE /X/{id} — у кошик, для контрагентів, документів і статей (у v2 ще для угод, задач, нотаток, проєктів); товари, категорії, виробники, атрибути видаляються тільки у вікні
    scope/search productGET /products?q=…
    scope/add contractor_pricePOST /price_lists/{id}/import — фонова задача
    scope/add mail_sendPOST /mail_messages/{id}/reply — завжди через «Пульс»
    scope/add document_extended, scope/get print_templateвідповідника в v2 немає

    Маршрути api/order, api/cart, api/payment, api/shipping, api/coupon, api/voucher, api/reward, api/customer, api/currency прибрано: це залишки вітрини OpenCart, вони не працювали й відповідали помилкою. Довідник валют v1 — api/scope/get/currency — працює як раніше.

    Ключ v1: поля й обмеження

    Таблиця нижче — про картку ключа, створеного до 14.10.2026. У ній є попередження «Це ключ старого API (v1)…», поле «Ключ доступу» і кнопка «Генерувати». Ключ, створений кнопкою «+» зараз, — уже ключ v2: поля «Ключ доступу» в нього немає, а з api/login він не працює.

    Поле картки ключаПараметр у запитіЩо робить
    «Користувач»usernameімʼя для входу
    «Ключ доступу»keyсекрет; кнопка «Генерувати» створює його за вас
    «Активність»—вимкнений ключ не пускає ні на вхід, ні за вже виданим токеном
    «Тільки для читання»—будь-яка зміна даних відповідає помилкою; читання працює
    «IP-адреси для доступу»—перелік через кому, пробіл або з нового рядка. Порожньо — звідусіль
    «Дата закінчення доступу»—ключ працює по цю дату включно; порожня дата — безстроково
    «Примітка»—кому й навіщо виданий ключ

    Три поля закривають доступ миттєво, а не з наступного входу. «Активність», «Дата закінчення доступу» й «Тільки для читання» перечитуються з картки ключа на кожному запиті, тому діють і на вже виданий токен: вимкнули ключ або настав наступний день після дати — поточний токен перестає працювати без перелогіну. Це зручно, коли ключ треба відкликати негайно.

    Права доступу ключа v1 не діляться за довідниками. Ключ v1 — не користувач програми: відділи й групи прав на нього не діють, тому один токен читає замовлення, товари, контрагентів і все інше, що є в акаунті. Обмежити ключ можна тільки трьома полями картки — «Тільки для читання», «IP-адреси для доступу» і «Дата закінчення доступу».

    Якщо підряднику чи сторонній програмі треба бачити лише замовлення, ключ тут не допоможе: видайте ключ v2 від імені користувача у відділі, якому відкрито тільки вікно замовлень: ключ v2 отримує права саме цього співробітника.

    Заводьте окремий ключ на кожну інтеграцію: тоді відкликання одного не зупинить інші.

    Коли API не потрібне

    Перш ніж писати інтеграцію, перевірте готові механізми — вони закривають більшість задач без розробника:

    • Сайт на популярній — тунель пише товари, ціни й залишки прямо в базу сайту.
    • Маркетплейс — готові підключення вже є для десятка майданчиків.
    • Регулярний файл — вивантаження за розкладом у чи .

    API лишається для своєї логіки: нестандартний сайт, внутрішня система обліку, обмін, якого немає в готових форматах.

    Сценарії

    Сайт тільки забирає залишки й ціни

    Задача: сайт читає з Elbuz залишки й ціни і не повинен нічого змінювати в акаунті.

    Що ввімкнути: окремий ключ для сайту з прапорцем «Тільки для читання», у полі «IP-адреси для доступу» — адреса сервера сайту. Запит — api/scope/get з limit_field=sku,price,quantity, як у рецепті нижче.

    Що вийде: читання працює. Будь-який add, update чи delete цим ключем відповідає «немає дозволу на зміну даних» — навіть якщо в коді сайту помилка і він спробує щось записати. Запит з іншої адреси не пройде ні на вході, ні з уже виданим токеном.

    Тимчасовий доступ для стороннього розробника

    Задача: підрядник налаштовує інтеграцію, і доступ має закритися разом із проєктом.

    Що ввімкнути: окремий ключ, у «Дата закінчення доступу» — останній день робіт, у «Примітка» — кому й навіщо виданий.

    Що вийде: ключ працює по цю дату включно. Наступного дня його не пускає ні api/login, ні токен, отриманий раніше, — чекати, поки сеанс закінчиться сам, не треба. Закінчили раніше — зніміть «Активність», діє так само. Чого не станеться: інші ключі акаунта від цього не залежать, у кожного своя дата й свій прапорець.

    Обмежити такий ключ окремими довідниками не вийде — як дати підряднику лише замовлення.

    Перейти на v2 без простою

    Задача: інтеграція має працювати весь час, поки програміст переписує її на v2.

    Що ввімкнути: не чіпаючи ключ v1, створіть кнопкою «+» окремий ключ v2 від імені потрібного співробітника. Перевірте на ньому новий код.

    Що вийде: обидва ключі працюють паралельно. Коли код на v2 готовий, зніміть у ключі v1 «Активність» — його токени перестануть діяти одразу.

    Що робити, коли ключ не пускає

    Що ви бачитеЧому такЩо зробити
    Новий ключ: api/login відповідає «некоректний ключ»ключ створено для API v2, у нього немає поля «Ключ доступу»писати запити до /api/v2/… із заголовком Authorization: Bearer (API v2)
    Читання працює, запис відхиляєтьсяу ключа «Тільки для читання»; прапорець діє на всі маршрути, зокрема старізняти прапорець — діє одразу, без перелогіну
    Ключ перестав пускати, хоча активнийнастав день після «Дати закінчення доступу»посунути дату або очистити поле — тоді ключ безстроковий
    Після переходу на v2 частина даних зникла з відповідейключ v2 бачить лише вікна й поля свого співробітникавідкрити співробітнику потрібні вікна й поля (крок 2 переходу)

    Часті запитання

    Чи перестане працювати старий API?

    Дати вимкнення немає: ключі v1 працюють, як працювали. Але нових можливостей у v1 не буде, а «Створити новий ключ» у картці переводить ключ на v2 без повернення.

    Чи можна мати ключ v1 і ключ v2 одночасно?

    Так. Ключ, створений кнопкою «+», — окремий ключ v2, ключ v1 при цьому працює далі. Так інтеграцію переводять без простою (сценарій).

    API відповідає «УВАГА: некоректний ключ API!», хоча ключ скопійовано правильно. Що перевірити?

    У картці ключа — пару «Користувач» + «Ключ доступу», «Активність» і «Дату закінчення доступу»: на всі три причини текст однаковий. Немає поля «Ключ доступу» — це ключ v2. Інший текст помилки — відповідь API постачальника чи майданчика, не Elbuz.

    Чи можна зробити API-ключ підряднику, який бачить тільки замовлення?

    Ключем v1 — ні: він читає все в акаунті. Ключем v2 — так: видайте його від імені користувача у відділі, якому відкрите лише вікно замовлень (докладно).

    Які IP-адреси серверів Elbuz додати в білий список (whitelist)?

    Загального переліку немає: адреса залежить від сервера акаунта. Для постачальника з API вона написана у вікні «Налаштування параметрів доступу до API» джерела (підключення постачальника), для інших сервісів — напишіть на support@elbuz.com. Поле «IP-адреси для доступу» ключа — про інше: звідки пускати до Elbuz.

    Де це і хто має доступ

    Меню
    Кабінет → Налаштування системи → «Інші налаштування» → плитка «API та токени доступу»
    Право доступу
    вікно «API та токени доступу» у правах групи
    Підготувати
    співробітника, від імені якого працюватиме ключ v2
    Розділ «Інші налаштування» з плиткою «API та токени доступу»
    1Плитка «API та токени доступу»
    2Розділ «Інші налаштування»
    1. Плитка «API та токени доступу» — звідси відкривається список ключів API.
    2. Розділ «Інші налаштування» — сюди зібрані вікна, яких немає в головному меню.

    Суміжні теми

    Чи була стаття корисною?

    Не вистачає функції? Напишіть нам.

    Ми додамо її безкоштовно, якщо вона знадобиться й іншим.

    Якщо це потрібно тільки вам — домовимося окремо.

    Зміст статті

    Запропонувати доробку

    Спробувати безкоштовно