Старий API Elbuz (v1) працює далі для вже виданих ключів v1, але нових можливостей у ньому не буде. Нові ключі видаються для API v2: з правами конкретного співробітника, підтвердженням змін у «Пульсі» й захистом від дублів.
Коли це знадобиться:
- Інтеграція працює через
api/login— що чим замінити у v2, зведено в таблицю. - Новий ключ відповідає «некоректний ключ» — він уже для API v2 і з
api/loginне працює. - Підряднику треба відкрити лише замовлення — ключ v2 від імені співробітника бачить тільки його вікна.
- Ключ треба закрити негайно — «Активність» і дата закінчення діють і на вже виданий токен.
З чого почати: переведіть ключ на v2 у його картці.
Що є в старому API
- Перехід на v2 — чим v2 відрізняється і який ресурс v2 замінює кожну операцію v1.
- Ключ v1 — поля картки й три способи обмежити доступ, які діють миттєво.
- Довідник API v1 — вхід, операції
describe,get,add,update,delete, фільтри, помилки й готові рецепти. - Що API v1 робить з даними — ручні правки, обрив і повтор пакета, чия ціна лишиться, відкат.
- Готові обміни без програміста — тунель, маркетплейси, вивантаження за розкладом.
Де це і хто має доступ
- Меню
- Кабінет → Налаштування системи → «Інші налаштування» → плитка «API та токени доступу»
- Право доступу
- вікно «API та токени доступу» у правах групи
- Підготувати
- співробітника, від імені якого працюватиме ключ v2
1
Плитка «API та токени доступу»2
Розділ «Інші налаштування»- Плитка «API та токени доступу» — звідси відкривається список ключів API.
- Розділ «Інші налаштування» — сюди зібрані вікна, яких немає в головному меню.
Як перевести інтеграцію на API v2
Кожна відповідь старого API несе заголовки 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 |
Як перевести ключ
- Відкрийте картку свого ключа v1 у вікні «API та токени доступу».
- У полі «Від імені співробітника» оберіть, чиї права отримає інтеграція. Ключ v1 бачив усе — перевірте, що співробітнику відкриті всі потрібні вікна й поля, інакше після переходу частина даних зникне з відповідей.
- Натисніть «Створити новий ключ» і підтвердьте «Новий ключ замінить поточний: інтеграції зі старим ключем перестануть працювати». Старі «Користувач» + «Ключ доступу» і вже видані токени перестають діяти одразу — переведіть інтеграцію в ту ж хвилину або заведіть для v2 окремий ключ «+» і переключайтеся, коли код буде готовий.
- Скопіюйте новий ключ — він показується один раз.
1
Від імені співробітника2
Зміни даних3
Новий ключ4
Тільки для читання- Від імені співробітника — чиї права й «Чиї дані» отримає ключ. Інших співробітників тут бачить лише той, у кого є доступ до вікна користувачів.
- Зміни даних — «Питати» (кожна зміна чекає в «Пульсі») або «Робити самому». Перемикає лише «Управління».
- Новий ключ показується один раз: скопіюйте його кнопкою «Копіювати» до закриття вікна.
- Тільки для читання — у ключа, створеного кнопкою «+», ввімкнено; у ключа, переведеного з v1, лишається як було.
Новий ключ створюється в режимі «Питати (через «Пульс»)»: кожна зміна чекає підтвердження в «Пульсі». Інтеграції, яка має писати одразу (замовлення з сайту, ціни з облікової системи), «Управління» ставить у картці ключа «Робити самому». Докладно — API v2: зміни.
Що чим замінюється
| v1 | v2 |
|---|---|
api/login + api_token | заголовок Authorization: Bearer |
scope/describe scope=X | GET /api/v2/openapi.json або 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; нові — /payment_types, /delivery_types |
scope/add document з проведенням | POST /documents, потім POST /documents/{id}/sign |
scope/add X, X/add_batch | POST /X з Idempotency-Key, по одному запису |
scope/update X, X/update | PATCH /X/{id} |
scope/delete X, X/delete | DELETE /X/{id} — у кошик, для контрагентів, документів і статей (у v2 ще для угод, задач, нотаток, проєктів); товари, категорії, виробники, атрибути видаляються тільки у вікні |
scope/search product | GET /products?q=… |
scope/add contractor_price | POST /price_lists/{id}/import — фонова задача |
scope/add mail_send | POST /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 не потрібне
Перш ніж писати інтеграцію, перевірте готові механізми — вони закривають більшість задач без розробника:
- Сайт на популярній CMS — тунель пише товари, ціни й залишки прямо в базу сайту.
- Маркетплейс — готові підключення вже є для десятка майданчиків.
- Регулярний файл — вивантаження за розкладом у XML чи XLSX.
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 v2: ключі, права, формат.
- Якщо інтеграція ще на v1 і треба знайти операцію чи розібрати помилку — довідник старого API v1.
- Якщо інтеграція пише товари й ціни на живому акаунті — що API v1 робить з даними.
- Якщо до Elbuz треба підключити Claude чи ChatGPT — підключити AI-асистента.
- Якщо ключу v2 треба звузити права — користувачі й права.