UNC Апи
Этот документ описывает взаимодествие с торговой площадкой UNC.UA посредством програмного интерфейса (АПИ) .
Наш АПИ поддерживает запросы по стандарту GraphQL, это значит что все запросы к нему должны передаваться GET запросом в формате отдалённо напоминающем JSON. В качестве ответа всегда приходит JSON
Точкой входа для всех запросов является адрес https://unc.ua/api/v1
Например, следующий запрос "получить текущий язык интерфейса"
query{ language }
нужно выполнять так https://unc.ua/api/v1?query=query%7Blanguage%7D и в ответ мы получим такие данные
{"data":{"language":"RU"}}
на данный момент используется только два языка: RU, UK.
Запросы могут быть двух типов: query и mutation.
query
Получение какой-либо информации (если вы имеете к ней доступ)
- Получить общедоступную информацию о лоте по его id
query { auction ( id:301 ) { name seller_text category_id description type_transaction starting_price price quantity duration is_auto_republish conditions_transfer images categories { id name next { id name next { id name next { id name next { id name }}}}} location { id name next { id name next { id name }}} } }
Ответ:
{ "data": { "auction": { "name": "Рождественская открытка \"Ребенок\"", "seller_text": null, "category_id": 2798, "description": "<p>\r\n\t Рождественская открытка \"Ребенок, мальчик, дети\". Тисненая. Обратная сторона чистая.\r\n</p>", "type_transaction": "STANDART", "starting_price": 39, "price": 0, "quantity": 1, "duration": "WEEK3", "is_auto_republish": 1, "conditions_transfer": "Укрпочта, Новая почта", "images": [ "/i2/8/thumbs/large_ee13ce6a80ecdd6290eac365c187da55_1138.jpg", "/i2/8/thumbs/large_681a26bbf68aeb0140e17430a34377c5_1140.jpg" ], "categories": { "id": 2798, "name": "Різдво", "next": { "id": 2082, "name": "Вітальні до 1920 (імена, привіти)", "next": { "id": 2023, "name": "Филокартия (листівки)", "next": null } } }, "location": { "id": 2813, "name": "Киев", "next": { "id": 87, "name": "Киевская обл.", "next": { "id": 2, "name": "Украина" } } } } } }
также можно получать одновременно несколько лотов
(в данном случае фрагменты позволяют сокращать объём запросов)
query { a1 : auction ( id:19 ) { ...afields }, a4 : auction ( id:22 ) { ...afields }, } fragment afields on Auction { id name description }
Ответ:
{ "errors": [ { "message": "Аукцион не найден или у вас нет допуска", "category": "graphql", "locations": [ { "line": 2, "column": 10 } ], "path": [ "a1" ] } ], "data": { "a1": null, "a4": { "id": "22", "name": "Устав Харьковской Торгово-Промышленной и Трудовой Артели - 1910 г", "description": "<p>\r\n\t Формат близкий к А6. 24 стр.\r\n</p>" } } }
- Авторизация, получение токена и идентификатора для загрузки картинок
query { login ( login:"tester", password:"kjsdhkashjkh" ) { token identifier } }
Ответ в случае ошибки:
{ "errors": [ { "message": "password: Неправильний логін або пароль", "category": "graphql", "locations": [ { "line": 2, "column": 5 } ], "path": [ "login" ] } ], "data": { "login": null } }
Ответ в случае успеха:
{ "data": { "login": { "token": "R~F6pDWMA1GLAEfdFbAljFcK1y7oWyAQ", "identifier": "49b354897d845044299bc53638fb405f" } } }
- Запрос информации о пользователе по его логину (перечислены только доступные поля)
query { user ( login:"tester" ) { login rating createtime } }
Ответ:
{ "data": { "user": { "login": "tester", "rating": 0, "createtime": "2018-04-01 00:59:52" } } }
- Запрос информации о себе по токену (см. Авторизация)
query { user ( token: "R~F6pDWMA1GLAEfdFbAljFcK1y7oWyAQ" ) { login rating createtime firstname lastname about id_city id_region id_country email telephone language social_page_fb social_page_vk add_contact_info terms_delivery consent_recive_notification location { id name next { id name next { id name }}} } }
Запросы могут состоять из нескольких подзапросов
query { auction(id:301) { name seller_text category_id description type_transaction starting_price price quantity duration id_country id_region id_city is_auto_republish conditions_transfer images }, category : catalog(kind:category,id:2798) {id name parent}, country : catalog(kind:country,id:2) {id name parent}, region : catalog(kind:region,id:87) {id name parent}, city : catalog(kind:city,id:2813) {id name parent} }
- Примеры получения различных данных из справочников
kind является EnumType поэтому значения без кавычек , если не указан то поиск выполняется по странам
query { catalog ( kind:city, id:[111,112,113], parent:1 ) { id name parent } }
Список категорий верхнего уровня:
query { catalog ( kind:category ) { id name } }
Следующего уровня:
query { catalog ( kind:category, parent:2008 ) { id name } }
Запрос категории по id:
query { catalog ( kind:category, id:2041 ) { id name parent} }
Запрос нескольких категорий по id:
query { catalog( kind:category, id:[2041, 2042] ) { id name parent } }
Список стран:
query { catalog { id name } }
Список регионов страны:
query { catalog ( kind:region, parent:100 ) { id name parent } }
Список городов в регионе:
query { catalog ( kind:city, parent:846 ) { id name parent } }
Запрос одной страны по id:
query { catalog ( id:5 ) { id name parent } }
Запрос нескольких городов:
query { catalog ( kind:city, id:[3063, 3064, 3065, 3066] ) { id name parent } }
mutation
Сохранение\изменение какой-либо информации (если имеется на это разрешение)
- Меняем язык интерфейса
mutation { language( set:UK ) }
- Регистрация пользователя (в случае успеха код возврата это ID пользователя)
mutation { registration( email:"test@google.com", login:"tester", firstname:"Tester", lastname:"Testerovich", telephone:"+380661112233", password:"kjsdhkashjkh", confirmPassword:"kjsdhkashjkh", agreeLicense:false ) { error text code } }
Ответ:
{ "data": { "registration": { "error": null, "text": "Проверьте почту для завершения регистрации.", "code": 768 } } }
- Меняем настройки в своём аккаунте
mutation { user ( token:"R~F6pDWMA1GLAEfdFbAljFcK1y7oWyAQ", about:"Astronomy, ML" ) { login about } }
- Создание лота
в поле images каждый путь в картинке должен начинаться идентификатора, полученного при авторизации пользователя. Часть в имени картинки после /thumbs/ может быть набором произвольных букв и цифр. После сохранения у картинки меняется путь по которому она будет доступна, поэтому запрашивайте его, чтобы узнать реальный путь.
mutation { createAuction ( token: "R~F6pDWMA1GLAEfdFbAljFcK1y7oWyAQ", name: "Рождественская открытка \"Анжела2\"", description: "Тут нечего добавить", category_id: 2798, type_transaction: STANDART, starting_price: 29, price: 0, quantity: 1, duration: WEEK3, is_auto_republish: 1, id_country: 2, id_region: 87, id_city: 2813, conditions_transfer: "Укрпочта, Новая почта", images: [ "b012104028bb91b9e97e982125bf369b/thumbs/63f8a67910613c3aed5053b6aed54fbd.jpeg", "b012104028bb91b9e97e982125bf369b/thumbs/87ef26593cb8306c266e0ede00ab6b9e.jpg" ] ) { auction_id name seller_text category_id description type_transaction starting_price price quantity duration is_auto_republish id_country id_region id_city conditions_transfer images } }
- Редактирование лота
mutation { auction ( id:22, name:"New name", token:"R~F6pDWMA1GLAEfdFbAljFcK1y7oWyAQ" ) { name } }
- Удаление лота
mutation { deleteAuction ( id:19, token:"R~F6pDWMA1GLAEfdFbAljFcK1y7oWyAQ" ) { name } }
Перечислимые типы
-
Тип сделки
- STANDART - Стандартный аукцион
- START_ONE - От 1 грн
- SALE - Фиксированная цена
-
Продолжительность торгов
- WEEK1 - Одна неделя
- WEEK2 - Две недели
- WEEK3 - Три недели