API
Вступ#
Розділ API дає змогу створювати облікові дані, за якими програми звертаються до API магазину на ocStore. Для кожного ключа API можна обмежити доступ за IP-адресами та переглянути активні сесії.
У ocStore 3 вбудований API насамперед використовується самою адмінкою: через нього працює створення та редагування замовлень у розділі Продажі → Замовлення. API користувача для цього вибирається в Система → Налаштування на вкладці Опції (поле Користувацькій API). Той самий механізм можуть використовувати зовнішні програми та доповнення (наприклад, для роботи з кошиком і замовленнями), але повноцінного API для керування каталогом, як у сторонніх інтеграціях з ERP, стандартний ocStore 3 не містить — такі інтеграції зазвичай реалізують окремі доповнення.
Як відкрити керування API#
Крок 1. Перейдіть до розділу API#
Увійдіть в адмінку і відкрийте Система → Користувачі → API.
Крок 2. Список API#
Ви побачите список наявних облікових даних API з колонками Назва API, Статус, Дата додавання та Дата оновлення.
Крок 3. Керування API#
Натисніть Додати, щоб створити новий ключ API, або Редагувати, щоб змінити налаштування наявного.
Огляд інтерфейсу#
Поля форми API#
Форма API має три вкладки: Загальні, IP-адреси та Сесія.
Вкладка «Загальні»
Основні облікові дані
- Назва API: (обов'язкове) унікальний ідентифікатор API, від 3 до 64 символів
- Ключ API: (обов'язкове) секретний ключ довжиною від 64 до 256 символів; кнопка Генерувати створює випадковий ключ
- Статус: вмикає або вимикає API без видалення
Вкладка «IP-адреси»
Засоби безпеки
- IP: список IP-адрес, з яких дозволено використовувати цей ключ API
- Поточна IP-адреса: над списком показано вашу поточну IP-адресу для довідки
- Керування адресами: кнопка Додати IP додає рядок, кнопка Видалити — прибирає адресу зі списку
Обмеження за IP-адресами — критично важливий засіб безпеки: лише авторизовані сервери можуть підключатися до API магазину. Запит з адреси, якої немає в списку, буде відхилено.
Вкладка «Сесія»
Активні сесії API
- Токен: токен сесії, виданий після успішного входу через API
- IP: IP-адреса, з якої відкрито сесію
- Дата додавання: коли сесію створено
- Дата оновлення: коли сесія востаннє використовувалася
Кнопкою Видалити можна примусово завершити сесію. Ця вкладка допомагає побачити, хто і звідки зараз користується ключем.
Завжди обмежуйте ключі API конкретними IP-адресами. ocStore показує вашу поточну IP-адресу на вкладці IP-адреси, щоб її було легко додати. Для робочих інтеграцій вказуйте статичні IP-адреси зовнішніх серверів.
Не видаляйте і не вимикайте API, вибраний у налаштуваннях магазину (поле Користувацькій API), — інакше перестане працювати створення та редагування замовлень в адмінці. Під час додавання чи редагування замовлення адмінка звертається до API з IP-адреси вашого сервера, тому ця адреса має бути в списку дозволених.
Створення нового ключа API#
Щоб налаштувати інтеграцію із зовнішньою програмою:
- Відкрийте Система → Користувачі → API і натисніть Додати.
- Введіть описову Назву API, з якої зрозуміле призначення (наприклад, «inventory-sync»).
- Натисніть Генерувати, щоб створити надійний Ключ API, і скопіюйте його в налаштування зовнішньої системи.
- Встановіть Статус «Включено».
- На вкладці IP-адреси додайте адреси, яким дозволено використовувати цей ключ:
- для тестування можна додати свою поточну IP-адресу (вона показана на вкладці);
- для робочого середовища — статичні IP-адреси ваших зовнішніх серверів.
- Натисніть Зберегти. Ключ API готовий до використання.
Примітка: в ocStore 3 ключ зберігається у відкритому вигляді й залишається видимим у формі API для користувачів з доступом до цього розділу. Тому обмежте доступ до розділу через групи користувачів.
Типові завдання#
Підключення зовнішньої програми#
Щоб підключити власну програму (наприклад, серверну частину мобільного застосунку) до магазину:
- Створіть новий API з назвою, наприклад, «mobile-app».
- Згенеруйте ключ і надійно збережіть його.
- Додайте IP-адреси серверів, з яких програма звертатиметься до API.
- У коді програми використовуйте назву та ключ API для входу (маршрут
api/login) і отриманий токен для подальших запитів. - Переглядайте вкладку Сесія, щоб переконатися, що API використовується правильно.
Заміна скомпрометованого ключа API#
Якщо є підозра, що ключ API скомпрометовано:
- Знайдіть API у списку і натисніть Редагувати.
- Змініть Статус на «Виключено», щоб негайно заблокувати доступ, і видаліть активні сесії на вкладці Сесія.
- Згенеруйте новий ключ (або створіть новий API з іншою назвою).
- Оновіть облікові дані в зовнішніх системах.
- Видаліть старий ключ API, коли всі системи переведено на новий.
Обмеження доступу до API конкретними серверами#
Для максимальної безпеки під час інтеграції з відомими серверами:
- З'ясуйте статичні IP-адреси всіх серверів, яким потрібен доступ до API.
- Під час створення чи редагування API додайте кожну адресу на вкладку IP-адреси.
- Перевірте підключення з кожного сервера, щоб переконатися, що адреси вказано правильно.
- Регулярно переглядайте вкладку Сесія, щоб переконатися, що API використовують лише авторизовані адреси.
Рекомендації#
Безпека та контроль доступу
Захист магазину
- Білий список IP: завжди обмежуйте ключі API конкретними IP-адресами
- Ротація ключів: періодично генеруйте нові ключі, особливо для інтеграцій з великим навантаженням
- Окремі ключі: створюйте окремі ключі для різних інтеграцій, щоб у разі проблеми можна було вимкнути лише одну з них
- Моніторинг: регулярно перевіряйте сесії API на незвичну активність
- Безпечне зберігання: зберігайте ключі API у змінних оточення або захищених файлах конфігурації, ніколи — у репозиторіях коду
Керування інтеграціями
Надійні підключення
- Описові назви: використовуйте назви API, з яких зрозуміле призначення інтеграції (наприклад, «erp-sync», «analytics-export», «mobile-backend»)
- Документація: ведіть облік, які ключі API використовують які системи, — це спрощує пошук проблем
- Тестове середовище: використовуйте окремі ключі для розробки, тестування та робочого магазину
- Обробка помилок: інтеграції мають правильно обробляти помилки API, особливо помилки автентифікації
- Оновлення: після оновлення ocStore або встановлення доповнень перевіряйте, чи не змінилися маршрути API
Ключі API дають доступ до даних і функцій магазину. Захищайте їх так само, як паролі адміністратора. Ніколи не розміщуйте ключі API в коді, який виконується на боці клієнта (JavaScript, мобільні застосунки, що розповсюджуються користувачам). Завжди використовуйте взаємодію «сервер — сервер» або захищений проксі.
Усунення несправностей#
Запити до API повертають помилку доступу
Проблеми з автентифікацією
- Облікові дані: перевірте назву та ключ API; ключ чутливий до регістру
- Статус API: переконайтеся, що API в адмінці має статус «Включено»
- Обмеження IP: переконайтеся, що IP-адреса сервера, який надсилає запит, є на вкладці IP-адреси
- Рішення: виправте облікові дані або IP-адреси й повторіть запит
Не працює створення або редагування замовлень в адмінці
Вбудований API адмінки
- API у налаштуваннях: перевірте, що в Система → Налаштування на вкладці Опції вибрано Користувацькій API і цей API увімкнено
- IP сервера: додайте на вкладку IP-адреси цього API IP-адресу, з якої ваш сервер звертається сам до себе (її показує повідомлення про помилку)
- Ключ: переконайтеся, що ключ API не порожній і має щонайменше 64 символи
API працює під час тестування, але не працює в робочому середовищі
Відмінності середовищ
- Інші IP-адреси: робочі сервери часто мають інші IP-адреси, ніж тестові, — оновіть список дозволених адрес
- Мережева конфігурація: брандмауери, проксі чи балансувальники навантаження (зокрема Cloudflare) можуть змінювати видиму IP-адресу джерела
- SSL/TLS: переконайтеся, що робочі сервери мають дійсні SSL-сертифікати, якщо використовується HTTPS
- Обмеження хостингу: перевірте, чи не обмежує хостинг кількість запитів
Не вдається видалити ключ API
Залежності
- Активні підключення: переконайтеся, що ключ зараз не використовують інші системи; спершу вимкніть його й простежте, чи не з'являються помилки
- Залежність від налаштувань: API, вибраний у налаштуваннях магазину, використовується адмінкою для роботи із замовленнями
- Права адміністратора: перевірте, що ваша група користувачів має право на зміну
user/api - Рішення: спершу вимкніть ключ, переконайтеся, що нічого не зламалося, і лише потім видаліть його
У сесіях є неочікувані підключення
Розслідування безпеки
- IP-адреси: перевірте, чи сесії відкрито з авторизованих адрес
- Журнали інтеграцій: перегляньте журнали підключених систем
- Негайні дії: якщо підозрюєте несанкціонований доступ, негайно вимкніть ключ API, видаліть сесії й з'ясуйте причину
- Запобігання: суворіше обмежте список IP-адрес і замініть ключ
«API — це мости, що з'єднують магазин із зовнішнім цифровим світом. Кожному мосту потрібні надійні ворота (обмеження за IP), пильна охорона (моніторинг) і регулярні перевірки (заміна ключів), щоб дані залишалися захищеними, а інтеграції — потужними».