Перейти до змісту

API — з чого почати➧

WildcoreDMS надає REST API, через який можна керувати обладнанням, користувачами та отримувати дані для інтеграцій (білінг, моніторинг, власні скрипти й портали).

Уся комунікація — звичайні HTTP-запити з тілом і відповідями у форматі JSON.

Базова адреса➧

Усі методи доступні за префіксом /api/v1 на вашому сервері:

https://<ваш-сервер>/api/v1/...

У прикладах цієї документації використовується демо-стенд: https://demo.wildcore.tools.

Де взяти опис методів (OpenAPI / Swagger)➧

Повний і завжди актуальний перелік методів описано специфікацією OpenAPI 3 і доступний прямо з вашого сервера:

  • Інтерактивний Swagger UI — зручно переглядати й пробувати методи в браузері: https://<ваш-сервер>/swagger/ (демо: demo.wildcore.tools/swagger)
  • Сирий файл специфікації (для імпорту в Postman/Insomnia, генерації клієнтів або передачі в ШІ): https://<ваш-сервер>/swagger/openapi.yaml

Підказка

Завантажений openapi.yaml — найкраще джерело для автоматизації: за ним можна згенерувати клієнтський код або скрипти. Див. Генерація скриптів за допомогою ШІ.

Авторизація➧

Підтримуються два способи доступу: токен та довірені мережі.

Спосіб 1. Токен авторизації (рекомендовано)➧

Токен прив'язаний до користувача й передається у заголовку X-Auth-Key.

Як отримати токен:

  • Через веб-панель — найпростіше: створіть користувача (наприклад api_user) і згенеруйте для нього ключ. Покрокова інструкція: Генерація API ключа.
  • Через консольну утиліту — на сервері з агентом: 
    wca user:generate-key api_user 365d
    де api_user — логін користувача, 365d — термін дії ключа. У відповідь повертається таблиця з ключем.

Як використовувати — додайте заголовок до кожного запиту:

curl "https://demo.wildcore.tools/api/v1/device" \
  --header "X-Auth-Key: ВАШ_КЛЮЧ"

Ключ також можна передати параметром запиту ?x-auth-key=ВАШ_КЛЮЧ — зручно для швидкої перевірки в браузері, але в скриптах надавайте перевагу заголовку (параметри потрапляють у логи).

Сесійний вхід

Веб-панель і застосунки логіняться методом POST /api/v1/auth з тілом {"login": "...", "password": "..."} — у відповідь приходить ключ сесії. Для інтеграцій зручніший постійний токен з user:generate-key.

Спосіб 2. Довірені мережі (без авторизації)➧

Можна дозволити доступ до API без ключа для запитів з довірених IP/підмереж.

  1. У веб-панелі відкрийте Конфігурація → Конфігурація системи → вкладка «Конфігурація».
  2. У блоці безпеки впишіть довірені мережі у форматі CIDR (наприклад 10.0.0.0/8, 192.168.1.10/32).

Запити без ключа, але з довіреної мережі, виконуються від вбудованого користувача sys (з повними правами).

Безпека

Довірені мережі вимикають перевірку ключа для всіх адрес зі списку — вмикайте їх лише для контрольованого внутрішнього сегмента. Для зовнішніх інтеграцій використовуйте токен з обмеженим терміном дії.

Формат відповіді➧

Успішні відповіді мають єдину «обгортку»:

{
  "statusCode": 200,
  "meta": null,
  "data": { }
}
  • statusCode — HTTP-код результату;
  • meta — додаткові дані (наприклад, пагінація), якщо застосовно;
  • data — корисне навантаження (об'єкт або масив).

У разі помилки statusCode містить відповідний код (4xx/5xx), а тіло — опис помилки.

Далі➧

SDK та інструменти➧

  • PHP-клієнт (експериментальний): github.com/meklis/wildcore-api-client (приклади).
  • Оскільки веб-панель — це SPA, будь-який метод можна підглянути у вкладці Network браузера (F12) і повторити у своєму коді.