API управління ставками. Документація для розробників

Опис і загальні принципи використання

API спроєктоване, слідуючи архітектурному стилю REST. Це означає, що для вказівки дії над ресурсом використовуються HTTP-методи. Підтримуються 4 методи: GET, POST, PUT, DELETE.

GET – отримати дані

PUT | POST – створити / відредагувати

DELETE – видалити

Якщо немає можливості посилати, або не підтримуються PUT | DELETE запити, видалення можна провести за допомогою запиту GET з параметром action = delete (GET /bids/123/?action = delete)

API підтримує версійність. Номер версії вказується при кожному запиті, наприклад: GET /api/v1/{resource}

Підтримуваний формат – json.

– Auth_token string, 32 symbols – доступний на сторінці «Аукціонні місця» акаунта магазину.

400 – Bad request. Непідтримуваний запит, неправильно сформований запит

403 – Unauthorized. Неправильний або не переданий авторизаційний ключ

404 – Not found. Не знайдено ресурс, що не передані обов'язкові параметри

500 – Internal server error.

200 – Success. Успішне отримання даних, видалення

201 – Created. Запис створена, відредагована

Є безліч REST-клієнтів. Для тестування GET-запитів достатньо браузера, для інших типів запитів можна використовувати cURL.

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

https://hotline.ua/api/v1/bids/?auth_token=1cf0ce29cd69f536959ff98bddb0a237

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

curl -X PUT 'https://hotline.ua/api/v1/bids/offers/48?cost=460&auth_token=1cf0ce29cd69f536959ff98bddb0a237'

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

curl -X POST -H 'Content-Type: application/json' -d '{"bids": [{"firm_offer_id": 1001, "cost": 600}]}' 'https://hotline.ua/api/v1/bids/?auth_token=1cf0ce29cd69f536959ff98bddb0a237'

Основні ресурси і приклади викликів

bids

GET /bids/offers – отримати список встановлених ставок по товарах

[
  {
    "cost": "500",
    "firm_offer_id": "1001"
  },
  {
    "cost": "220",
    "firm_offer_id": "1101"
  },
  {
    "cost": "340",
    "firm_offer_id": "1003"
  }
]

GET /bids/offers/{firmOfferId} – отримати встановлену ставку по ID пропозиції фірми.

firmOfferId – унікальний номер товару в базі даних фірми, який передається нам у файлі товарного фіду в поле <id>.

GET /bids/offers/{firmOfferId}/advices – отримати список ставок на перші 10 місць

GET /bids/offers/{firmOfferId}/advices/{place} – отримати значення ставки для потрапляння на вказане місце

GET /bids/offers/advices?firm_offer_id = id1, id2, id3 – отримати список ставок по зазначеному списку товарів

GET /bids/offers/advices?firm_offer_id = [{"firm_offer_id": "{id1}", "place": "{place1}"}, {"firm_offer_id": "{id2}", "place": "{place2}"] – отримати список ставок по зазначеному списку товарів і місцем для кожного

Максимальний розмір GET-запиту – 8 кілобайт.

Опис викликів далі аналогічно попереднім і є самодокументованим.

DELETE /bids

DELETE /bids/offers

DELETE /bids/offers/{firmOfferId}

Для запитів створення/редагування, як тіла запиту повинна бути використана json-рядок зі встановленим заголовком

Content-Type: application/json

PUT | POST /bids Тіло запиту: {"bids":[{"firm_offer_id": 1001, "cost": 610}]}

При одиночній установці ставок обов'язковим параметром є cost (int, значення ставки в коп.):

PUT | POST /bids/offers/{firmOfferId}?cost = {cost}

Існуючі обмеження

- 1 паралельний потік;

- 300 запитів на хвилину (якщо вам не вистачає цього обмеження, будь ласка, скористайтесь методами отриманная результатів у batch-запиті).