Питання - Відповіді(FAQ) по Open API

Зібрали відповіді на найрозповсюдженіші питання в процесі роботи з API keyCRM

Написано Владислав Пономарь

Оновлено 3 дні тому

1. Як відбувається авторизація при підключенні до API?

Відповідь: Для авторизації потрібно передавати заголовок у форматі Bearer + APIkey.

"headers":{"authorization":["Bearer ваш-API-ключ"]}

2. Як дізнатися, які дані в які поля я можу передавати та отримувати?

Відповідь: В документації API описано кожен метод. Приклади запитів чи відповідей містять список усіх доступних параметрів для цього методу з описом поля та прикладом значення, яке можна скопіювати:

3. Чому назви стандартних статусів замовлень в OpenAPI повертаються англійською мовою?

Відповідь: За замовчуванням система створює стандартні статуси з англомовними назвами, тому саме так вони і повертаються в OpenAPI. Якщо потрібно, щоб статус повертався українською — достатньо просто відкрити його в налаштуваннях і перезберегти. Після цього API почне повертати локалізовану назву.

Винятком є системні статуси «Новий», «Виконано» та «Скасовано» — вони зарезервовані, тому змінити їх неможливо.

4. Як передати значення в декілька кастомних полів різних типів?

Відповідь: Пропишіть дані до кожного поля через кому в масиві custom_fields.

Якщо поле з типом список або мультисписок, то список значень потрібно передавати у параметрі value в масиві. Усі значення мають бути додані як опції в цьому полі.

"custom_fields": [
    {
      "uuid": "системна назва поля з CRM",
      "value": "Значення, яке потрібно записати в це поле"
    },
    {
      "uuid": "системна назва поля з CRM",
      "value": ["Опція 1", "Опція 2", "Опція 3"] 
    }
  ]

5. Чому GET-запитом я отримую не всі дані, як в прикладі в документації?

Відповідь: За замовчуванням передаються тільки базові дані. Щоб отримати усі доступні додаткові, додайте до запиту include. До кожного методу в документації додано список доступних.

6. Що значить помилка «Too Many Requests»?

Відповідь: В нас діє обмеження до 20 запитів на хвилину за API-ключем. Якщо частота запитів перевищує цей ліміт, запити починають отримувати цю помилку.

Рекомендуємо оптимізувати ваш процес, щоб зменшити кількість запитів. Наприклад, ви можете налаштувати паузу між запитами на 3 секунди.

7. Як спробувати зробити запит до API через документацію?

Відповідь: Для цього оберіть потрібний метод та натисніть «Test Request».

Далі введіть ваш API-ключ та заповніть інші обов'язкові поля з відміткою Required. За бажанням заповніть інші дані та натисніть «Send»:

8. Чому не створюється замовлення та отримую помилку «The source uuid has already been taken»?

Відповідь: Помилка означає, що в цьому джерелі вже є замовлення з цим номером з джерела (source_uuid). Відповідно, повторного замовлення з таким самим номером в цьому джерелі створено не може бути — це перевірка системи на дублікати.

Можливо, видалялися замовлення на сайті чи відновлювалася резервна копія (бекап). Оскільки, вірогідно, збилася нумерація на сайті, використані номери замовлень знову стали доступними для нових замовлень.

9. Чому не оновлюється залишок товару за ідентифікатором?

Відповідь: Скоріше за все, ви передали ідентифікатор, якого немає в системі. В методі на оновлення залишків потрібно передавати саме offer_id — ідентифікатор варіанта товару; він не дорівнює product_id (ідентифікатор товару).

Навіть якщо у вас товари без варіантів, кожен з них має offer_id. Оскільки для системи товар без варіантів означає товар в одному варіанті. Ідентифікатори варіантів можна отримати у файлі експорту або запитом на отримання списку варіантів товарів через API.

Якщо ви використовуєте артикули, то залишки можна оновлювати тільки передавши sku, без потреби отримувати та передавати ідентифікатори варіантів.

10. Не відправляються запити до API keyCRM взагалі — в чому може бути причина?

Відповідь: Перевірте основні моменти:

На вашому сервері коректний SSL-сертифікат;
Запити відправляються з сервера, а не з браузера;
Ваш хостинг-провайдер не блокує відправку запитів.

Якщо ви все перевірили і складність залишається — напишіть в нашу підтримку.

11. В замовленні та в товарі в каталозі були зміни, але дата в полі updated_at не оновилася. Чому?

Відповідь: Поки що не усі зміни сутності оновлюють дату в параметрі "updated_at".

Наприклад, на дату в "updated_at" замовлення не впливають зміни в полях:

Теги;
Відповідальні;
ЮТМ-мітки;
Файли;
Завдання;
Оплати;
Тип відвантаження.

На дату в "updated_at" товару не впливають зміни через API в полях:

Артикул (його додаванні, якщо поле було пустим);
Штрихкод;
Закупівельна вартість;
Вартість.

12. Як додати файл у картку воронки чи замовлення?

Відповідь: Щоб додати файл, спочатку його потрібно завантажити на сервер CRM. У відповіді ви отримаєте id (fileId) — ідентифікатор вашого файлу в системі.

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

13. Як отримати залишок з колонки «Доступно» з урахуванням резервів?

Відповідь: Як при отриманні загальних залишків по усіх складах, так і при отриманні залишків по кожному складу окремо, ви отримуєте кількість у двох полях:

«quantity» — загальна кількість залишків;
«reserve» — загальна кількість зарезервованих залишків.

Відповідно, ви можете при отриманні додати формулу розрахунку в скрипт і від загального залишку віднімати резерв, щоб записувати саме кількість, доступну до продажу, з урахуванням резерву по товарах.

14. Чому отримую помилку «The buyer.email must be a valid email address»?

Відповідь: Помилка означає, що переданий email не валідний. Адреса електронної пошти має бути в форматі xxx@xxx.xxx без пробілів і спецсимволів. Некоректні дані можуть спричинити додаткові проблеми, тому система перевіряє усі дані, які ви надсилаєте.

Рекомендуємо додати валідацію email на стороні вашого сайту, мобільного додатка чи іншої системи, яка передає дані через API. Це зменшить кількість помилок і забезпечить коректність контактної інформації. Також варто перевіряти дані на сервері для додаткового захисту від некоректного введення.

15. Як отримати колекцію методів для POSTMAN?

Відповідь: Щоб отримати готову колекцію методів, натисніть кнопку «Run in Postman» в документації. Для використання потрібно вказати ваш API-ключ у змінній api_token в колекції (Edit → Variables).

16. Чому я отримую замовлення, створені в інші дати, ніж вказую у фільтрі created_between?

Відповідь:

Фільтр created_between працює саме по даті створення в CRM ("created_at"), а не по даті створення на джерелі ("ordered_at"), яка може не збігатися з "created_at". Тому перевірте, чи вірні дати, які ви передаєте.
У всіх сутностях час використовується UTC (GMT+0), тому варто врахувати його при формуванні дати.

17. Як налаштувати передачу статусів замовлення з CRM на сайт?

Відповідь: Один з варіантів реалізації автоматичної зміни статусів замовлень із CRM на сайт:

На сайті додати скрипт, який отримуватиме та зберігатиме список статусів із CRM та прописати відповідність статусів між сайтом і CRM;
У CRM налаштувати тригер, який автоматично відправлятиме вебхук при зміні статусу замовлення;
Реалізувати скрипт на сайті, який прийматиме дані від CRM, знайде відповідне замовлення за його номером і змінюватиме статус на сайті відповідно до статусу в CRM.

Як це буде працювати:

Змінюється статус замовлення в CRM і спрацьовує тригер, який надсилає на сайт JSON з даними цього замовлення. Він включає "source_uuid" (номер замовлення на сайті) та "status_id" (ID статусу в CRM);
Скрипт на сайті приймає дані, знаходить замовлення за "source_uuid" і оновлює його статус відповідно до переданого "status_id" із CRM.

18. Як оптимізувати запити, щоб не отримати блокування?

Відповідь: Окрім налаштування затримки між запитами, рекомендуємо використовувати найбільш ефективні методи API для ваших задач:

Створення великої кількості товарів: використовуйте метод масового імпорту — до 100 товарів в одному запиті;
Створення великої кількості замовлень: метод масового імпорту — до 50 замовлень за раз;
Створення великої кількості покупців: метод масового імпорту — до 50 покупців в одному запиті;
Оновлення товарів: для зміни ціни, закупівельної вартості чи розмірів скористайтеся методом оновлення варіантів товару — до 10 000 товарів в одному запиті. Ідентифікатори варіантів не обов’язкові — достатньо артикулу й потрібних полів. Працює і для товарів без варіантів (вони мають один варіант за замовчуванням);
Отримання залишків: замість періодичних перевірок залишків через API, використовуйте вебхуки — це дозволяє отримувати оновлення автоматично;
Отримання змін статусу замовлення чи статусу оплати замовлення: замість отримання усіх замовлень і перевірки цих полів ви можете налаштувати відправку вебхуків саме по цих змінах;
Отримання списків (GET-запити): переконайтеся, що використовуєте максимальний доступний ліміт — ?limit=50. Якщо, наприклад, вказано ?limit=15 - кількість запитів зростає, що навантажує API. Або якщо вказана кількість понад 50, це виходить за ліміт і може призвести до блокування.

Це базові рекомендації. Якщо ви стикаєтеся із лімітами та не знаєте, як оптимізувати роботу з API — зверніться до нашої підтримки, і ми допоможемо.

19. Чому при отриманні картки чи замовлення з товарами id не відповідає id товару з каталогу?

Відповідь: При отриманні картки воронки або замовлення поле products.id не відповідає ідентифікатору товару з каталогу, оскільки це різні сутності.

products.id — це ідентифікатор товарної позиції саме в межах замовлення або картки, тобто конкретного запису товару, який був доданий у цю картку / замовлення.

Якщо товар повʼязаний з каталогом, то ідентифікатори передаються окремо:

При отриманні картки воронки додатково передається offer_id — ідентифікатор варіанту товару. За ним можна отримати варіант і product_id товару з каталогу, до якого належить цей варіант;
При отриманні замовлення передається обʼєкт offer, у якому:
- id — ідентифікатор варіанту товару;
- product_id — ідентифікатор товару з каталогу.

Теги: апі, помилка апі, запити api, робота з api, опенапі, опен апі, ліміти, оптимізація, запити

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