Загальна інформація про роботу з API
У Pricer24 є API, який можна використовувати для інтеграції з вашими обліковими системами. Звертаємо вашу увагу на те, що API є не у всіх тарифних планах.
Загальна інформація
- End-point для роботи з API – https://api.pricer24.com/
- API використовує REST-архитектуру
- Усі запити і відповіді API використовують формат JSON
- Для роботи з API вам потрібен ключ
- Опис існуючих методів та їх параметрів можна побачити у Swagger: ви можете надіслати готові запити та подивитися на відповідь сервера
Обмеження
- Не більше ніж 10 запитів у секунду
- Час виконання запиту – 60 секунд
- При отриманні трьох помилок протягом 60 секунд ключ буде заблокований на 30 секунд
Авторизація
Для авторизації необхідно до запиту додавати query-параметр ApiKey зі значенням вашого ключа. В загальному вигляді ваш запит буде виглядати так:https://api.pricer24.com/v1/{назва_ресурсу}?ApiKey={key}&Param1={value1}&Param2={value2}
Отримання API-ключа
- У системі переходимо у Налаштування → Компанія → Користувачі
- Натискаємо кнопку «Створити» на верхній панелі і створюємо нового користувача
- Відкриваємо створеного користувача
- У вкладці «Ролі» додаємо користувачу необхідні права
- У вкладці «API-ключі» натискаємо на кнопку «Створити»
Створений ключ автоматично копіюється в буфер обміну. Тепер можна використовувати його для інтеграції.
«Пагінація»
Більшість GET-методів в API підтримують пагінацію (посторінкову видачу). Для роботи з пагінацією вам необхідно використовувати query-параметри:
- MaxResultCount – скільки записів необхідно повернути
- SkipCount – скільки записів необхідно пропустити
Особливості
- Максимально можливе значення для MaxResultCount = 1000, якщо передати більше значення, ви отримаєте помилку
- За замовчуванням MaxResultCount = 10, якщо параметр не передавати, сервер поверне лише 10 записів
- За замовчуванням SkipCount = 0
- Загальна кількість записів міститься у властивості totalCount об'єкта result:
У загальному вигляді ваш запит буде виглядати GET https://api.pricer24.com/v1/{method}?SkipCount={PageSize}*{PageNumber-1}&MaxResultCount={PageSize}&ApiKey={key}, де:
- PageSize – розмір сторінки
- PageNumber – номер сторінки
Кількість сторінок можна обчислити за простою формулою Ceil(TotalCount / PageSize), де _Ceil _– округлення вгору до цілого.
Приклад
Якщо загальна кількість записів = 2700, і ми будемо отримувати відповідь по 1000 записам, для отримання усіх записів необхідно буде відправити 3 запити:
https://api.pricer24.com/v1/{имя_ресурса}?SkipCount=0&MaxResultCount=1000&ApiKey={key}– отримуємо першу 1000 записівhttps://api.pricer24.com/v1/{имя_ресурса}?SkipCount=1000&MaxResultCount=1000&ApiKey={key}– отримуємо наступну 1000 записівhttps://api.pricer24.com/v1/{имя_ресурса}?SkipCount=2000&MaxResultCount=1000&ApiKey={key}– отримуємо останні 700 записів
Query-параметр Include
Для того, щоб відповідь була мінімальною за розміром, за замовчуванням повертається мінімальна інформація про об'єкти. Для отримання розширеної інформації необхідно передавати query-параметр Include, де через знак коми необхідно перерахувати, за якими об'єктами потрібна розширена інформація.
Приклад
При надсиланні запиту GET https://api.pricer24.com/v1/contractors?ApiKey={key} без Include сервер поверне таку відповідь:
Масиви об'єктів contractorPriceTypes та contractorWarehouses мають значення null, так як не повертаються сервером.
Однак, якщо надіслати запит GET https://api.pricer24.com/v1/contractors?ApiKey={key}&Include=PriceTypes,Warehouses, то відповідь вже буде містити ціни і склади контрагента:
Обробка помилок
Сервер повертає стандартні коди відповідей:
- 200 – запит успішно виконано
- 401 – помилка авторизації
- 403 – не вистачає прав
- 404 – метод не знайдено
- 501 – внутрішня помилка серверу, скоріше за все запит складено некоректно
У випадку помилки інформація про неї буде повернена в об’єкті error:
Також для визначення, чи успішний запит, чи ні, можна обробляти властивість success, де true – запит виконано успішно, **false ** – під час виконання виникла помилка.
Оновлено: 28/08/2024
Дякуємо!