Якщо в KeyCRM ще немає інтеграції з якимось сервісом, то ви можете отримувати замовлення по API чи самостійно доопрацювати потрібні можливості по нашому відкритому API.
Можливості API
API KeyCRM постійно вдосконалюється, додаються нові методи та розширюються наявні. Актуальний функціонал можна детально переглянути в нашій API-документації:
- Робота з воронками (Pipelines) дає можливість отримувати списки воронок і карток, створювати та оновлювати картки, додавати (оновлювати) оплату та файли для існуючих карток;
- Робота із замовленнями та їх асоціаціями (Order) дозволяє отримувати списки та дані по замовленю, створювати й оновлювати замовлення, створювати замовлення списком, додавати (оновлювати, видаляти) оплату, витрати, файли та теги. Також можна отримати списки тегів, джерел, статусів, платіжних методів, типів витрат, статусів товарів і методів доставки;
- Робота з покупцями (Buyer) дозволяє отримувати списки покупців та дані конкретного покупця, створювати, оновлювати й імпортувати їх;
- Робота з компаніями (Company) дозволяє отримувати списки компаній та інформацію по компанії, а також створювати та оновлювати їх;
- Робота з товарами (Products) надає можливість отримувати списки товарів, категорії товарів та дані по конкретному товару, створювати (оновлювати) й імпортувати товари, а також створювати нові варіанти товарів та категорії;
- Робота з варіантами товарів і залишками (Offer) дозволяє отримувати список залишків та варіантів товарів, редагувати варіант товару та оновлювати варіанти товарів на складі;
- Робота з користувацькими полями (Custom Fields) дозволяє отримувати список користувацьких полів;
- Робота з файловою системою (Storage) дозволяє отримувати список завантажених файлів та файлів по конкретній сутності, а також можливість завантажити файл на сервер і створює новий запис у файловій системі;
- Робота з оплатами (Payments) надає можливість отримувати списки зовнішніх транзакцій та додавати їх до оплат.
Що потрібно при роботі з API
При формуванні запитів враховуйте деякі рекомендації:
- Для авторизації потрібно передавати заголовок у форматі Bearer + APIkey.
"headers":{"authorization":["Bearer ваш-API-ключ"]}
-
В нас діє обмеження до 60 запитів на хвилину з однієї IP-адреси по API-ключу. Якщо частота запитів більше цього ліміту, запити починаються отримувати помилку «Too Many Requests».
Рекомендуємо оптимізувати ваш процес, щоб знизити кількість запитів. Наприклад, ви можете налаштувати паузу між запитами в 1 секунду;
-
На вашому сервері має бути коректний SSL сертифікат, щоб було безпечне з'єднання;
-
Запити мають відправляться з сервера, а не з браузера. Оскільки буде виникати помилка CORS і такі запити ми не обробляємо в цілях безпеки, в такому випадку API токен буде у відкритому доступі, інші користувачі зможуть його отримати та за його допомогою отримати доступ до особистих даних або редагувати інформацію користувачів;
-
Важливо в запитах використовувати строгу структуру методів, передавати дані в потрібних форматах та з відповідними типами даних. Обов'язково передавайте формат обміну даних - application/json.
Як працювати з документацією API
Відправляти запити з документації API немає можливості, але ви можете сформувати тестові запити, переглянути структуру та опис доступних методів й полів.
Для перевірки запиту можна використовувати програми для роботи з API, наприклад POSTMAN.
-
Щоб переглянути метод - розгорніть його.
На вкладці «Schema» детально описано кожен доступний параметр з вказанням типу даних і прикладом значення.
Приклад запиту містить всі доступні поля, але ви можете вказувати лише ті, які вам потрібно передати (не потрібно можна прибрати).
Звертаємо увагу, що в методах є обов'язкові поля, які на вкладці «Schema» позначені червоною зірочкою (*), ці поля мають передаватись в запиті.
В GET запитах ви побачите лише приклад відповіді, а в POST запитах приклад запита, який ви можете відправити та приклад полів які ви отримаєте у відповіді.
- В GET запитах за замовченням передаються тільки базові дані, щоб отримати усі доступні додаткові, додайте до запиту include, до кожного метода в документації додано список доступних.
При формуванні запита за замовленням встановлено виведення 15 елементів на сторінці, при потребі можна збільшити до 50 елементів.
У відповіді ви отримаєте кількість сторінок з вказаною кількістю елементів на ній, тому в URL ви можете змінювати сторінку, щоб переглянути всі елементи.
Також ви можете зробити скрипт який буде автоматично перемикати сторінки.
- В GET запитах можна використовувати доступні фільтри та декілька фільтрів відразу.
Якщо потрібно отримати список замовлень по даті закриття, оскільки стандартно в нас немає фільтра по даті закриття, можна використовувати 2 фільтри: дата оновлення та статус замовлення.
Щоб дізнатись id статусу замовлення потрібно робити додатковий запит на отримання статусів замовлення.
Приклад URL:
https://openapi.keycrm.app/v1/order?limit=15&page=1&sort=id&filter%5Bstatus_id%5D=98&filter%5Bcreated_between%5D=2024-09-24%2C2024-09-23
В даній статті розглянули можливості API KeyCRM та особливості використання.