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 - Три недели