Схема¶

Всі запити до API виконуються через HTTPS, і доступні за адресою https://api.bm.parts. Всі дані відправляються і повертаються в JSON форматі.

curl -i https://api.bm.parts/profile/me

HTTP/2 200 OK
Server: nginx
Date: Thu, 26 Jul 2018 12:02:51 GMT
Content-Type: application/json; charset=utf-8
Connection: keep-alive
Status: 200 OK
X-BM-Build-ID: 4687
X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 4987
X-RateLimit-Reset: 1350085394
Content-Length: 5
Cache-Control: max-age=0, private, must-revalidate
X-Content-Type-Options: nosniff

Всі дати вертаються в форматі ISO 8601: YYYY-MM-DDTHH:MM:SSZ.

Аутентифікація¶

Є два методи для аутентифікації запитів на BM API v2 - за заголовком або за сесією в cookie. Також варто звернути увагу, що частина запитів можуть повертати 404 Not Found, замість 403 Forbidden, щоб попередити випадкове отримання даних неавторизованими користувачами.

Аутентифікація по API ключу¶

API ключ передається в заголовку в форматі Authorization: API-КЛЮЧ. Час життя ключа складає один рік з моменту його генерації. Приклад запиту по API-ключу:

curl -H "Authorization: API-КЛЮЧ" https://api.bm.parts/profile/me

Щоб отримати API ключ, перейдіть за адресою https://login.bm.parts/api/ і згенеруйте API ключ, як показано на малюнку.

Попередження

Не передавайте нікому Ваші API ключі. У випадку компрометації ключа, відразу заблокуйте його.

curl -H "cookie: session=5c682932-7c03-4abe-854c-febd8f5ef848..." https://api.bm.parts/profile/me

Cross Origin Resource Sharing¶

API підтримує Cross Origin Resource Sharing (CORS) для AJAX запитів з будь-якого домену. Ви можете ознайомитись з CORS W3C Recommendation або з цим вступом Посібника по безпеці HTML 5.

Нижче наведено приклад запиту відправлений з браузера при завантаженні сторінки http://example.com:

Це приклад запиту відправлений з браузера при відкритті сторінки http://example.com:

curl -i https://api.bm.parts -H "Origin: http://example.com"
HTTP/1.1 302 Found
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: ETag, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

Так виглядає попередній запит CORS:

curl -i https://api.bm.parts -H "Origin: http://example.com" -X OPTIONS
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Authorization, Content-Type, If-Match, If-Modified-Since, If-None-Match, If-Unmodified-Since, X-Requested-With
Access-Control-Allow-Methods: GET, POST, PATCH, PUT, DELETE
Access-Control-Expose-Headers: ETag, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
Access-Control-Max-Age: 86400

Посторінковий вивід¶

Запити, які вертають велику кількість елементів будуть розділені на сторінки, по 30 елементів за замовчуванням. Ви можете вказати наступні сторінки використовуючи параметр ?page. Для деяких ресурсів, ви можете використовувати власні розміри сторінок до 100, використовуючи параметр ?per_page.

Приклад запиту з використанням пагінації:

curl 'https://api.bm.parts/documents/list?page=2&per_page=100'

Обмеження кількості запитів¶

Для запитів з використанням аутентифікації по сесії або API ключу, Ви Можете зробити до 10000 запитів в годину. Аутентифіковані запити асоціюються з контрагентом користувача, незалежно від типу токена, що використовується. Це означає, що всі додатки і браузери, авторизовані користувачем будуть ділити одну квоту в 10000 запитів в годину, навіть якщо вони використовують різні токени одного користувача.

Для неавторизованих запитів ліміт складає 120 запитів в годину. Неавторизовані запити асоціюються

з IP-адресою, з якого відбувається запит

Заголовок відповіді на будь-який API запит вертає ваш поточний ліміт:

curl -i https://api.bm.parts/profile/me
HTTP/1.1 200 OK
Date: Mon, 01 Jul 2013 17:27:06 GMT
Status: 200 OK
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 56
X-RateLimit-Reset: 1372700873

Якщо вам потрібно отримати час в іншому форматі, підійде будь-яка сучасна мова програмування.

Наприклад, якщо ви відкриєте консоль браузера, ви можете легко отримати час обнулення як об’єкт JavaScript Date.

new Date(1519173436* 1000)
// => Wed Feb 21 2018 02:37:16 GMT+0200 (MSK)

Якщо ви перевищите лімат запитів, у відповідь на запит повернеться помилка:

HTTP/1.1 403 Forbidden
Date: Tue, 20 Aug 2013 14:50:41 GMT
Status: 403 Forbidden
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1377013266

{
   "message": "Превышен лимит запросов API для xxx.xxx.xxx.xxx.",
   "documentation_url": "https://developer.bm.parts/"
}

Обов’язковий заголовок User agent¶

Всі запити API ПОВИННІ містити валідний заголовок User-Agent. Запити без цього заголовку будуть відхилені. Використовуйте ваш код контрагента, або назву вашого додатку для заголовку User-Agent. Це дозволить нам зв’язатись з вами якщо виникнуть проблеми.

Приклад:

User-Agent: Awesome-BM-Parts-App

cURL відправляє валідний User-Agent за замовчуванням. Якщо ви передасте не валідний заголовок User-Agent через cURL (або через інший клієнт), ви отримаєте відповідь 403 Forbidden:

curl -iH 'User-Agent: ' https://api.bm.parts/
HTTP/1.0 403 Forbidden
Connection: close
Content-Type: text/html; charset=utf-8

Запрос отклонен по административным причинам.
Пожалуйста, убедитесть что в вашем запросе есть заголовок User-Agent.
Посмотрите https://developer.bm.parts/ для другой информации.

Вказівка періоду в запитах¶

Запити, які потребують вказання періоду, наприклад, список документів, дозволяють задати період в декількох форматах. Період може бути вказано або заданими константами, або конкретними датами.

&period={2018-02-23T00:00:01Z,2018-02-28T23:59:59Z}

&period={2018-02-01,2018-01-31}

&period={2018-02-01,}

Сортування результатів¶

В запитах, які підтримують сортування використовується параметр direction, котрий може приймати значення:

Локалізація¶

В більшості запитів присутня локалізація відповіді. Для визначення мови використовується header Accept-Language. Значення які приймаються: ru і uk, для російської і української мови відповідно. За замовчуванням використовується українська мова.