Открыть главное меню
ABCP Documentation

APIVINQU: различия между версиями

Статья Обсуждение
м (Убрал копипасту)
Строка 2: Строка 2:
 
__TOC__
 
__TOC__
  
−
== Общая информация ==
+
==Общая информация==
  
 
Доступ к публичному VINQU API осуществляется посредством HTTP-запросов и реализован с использованием принципов [http://ru.wikipedia.org/wiki/REST#RESTful_.D0.B2.D0.B5.D0.B1-.D1.81.D0.BB.D1.83.D0.B6.D0.B1.D1.8B REST].
 
Доступ к публичному VINQU API осуществляется посредством HTTP-запросов и реализован с использованием принципов [http://ru.wikipedia.org/wiki/REST#RESTful_.D0.B2.D0.B5.D0.B1-.D1.81.D0.BB.D1.83.D0.B6.D0.B1.D1.8B REST].
Строка 14: Строка 14:
 
Для отладки вы можете воспользоваться расширением [https://chrome.google.com/webstore/detail/advanced-rest-client/hgmloofddffdnphfgcellkdfbfbjeloo?utm_source=chrome-ntp-icon Advanced REST Client] для обозревателя Google Chrome.
 
Для отладки вы можете воспользоваться расширением [https://chrome.google.com/webstore/detail/advanced-rest-client/hgmloofddffdnphfgcellkdfbfbjeloo?utm_source=chrome-ntp-icon Advanced REST Client] для обозревателя Google Chrome.
  
−
=== Запрос ===
+
===Запрос===
  
 
Запросы на получение и запись данных осуществляются с помощью HTTP-методов GET и POST соответственно.
 
Запросы на получение и запись данных осуществляются с помощью HTTP-методов GET и POST соответственно.
Строка 23: Строка 23:
 
В HTTP-заголовке Accept необходимо передать ожидаемый тип данных ответа. В настоящее время реализован только тип JSON, и, в любом случае, будет возвращен он. Тем не менее, при разработке клиента, необходимо учитывать указанную особенность и передавать заголовок '''Accept''' со значением ''application/json''.
 
В HTTP-заголовке Accept необходимо передать ожидаемый тип данных ответа. В настоящее время реализован только тип JSON, и, в любом случае, будет возвращен он. Тем не менее, при разработке клиента, необходимо учитывать указанную особенность и передавать заголовок '''Accept''' со значением ''application/json''.
  
−
=== Ответ ===
+
===Ответ===
  
 
В случае успешного исполнения операции, веб-служба вернет ответ с HTTP-кодом 200 и телом ответа в виде [http://ru.wikipedia.org/wiki/JSON JSON]. Формат ответа определяется каждой операцией. Пример результата успешного выполнения запроса:
 
В случае успешного исполнения операции, веб-служба вернет ответ с HTTP-кодом 200 и телом ответа в виде [http://ru.wikipedia.org/wiki/JSON JSON]. Формат ответа определяется каждой операцией. Пример результата успешного выполнения запроса:
−
<source lang=javascript line=GESHI_FANCY_LINE_NUMBERS>
+
<source lang="javascript" line="GESHI_FANCY_LINE_NUMBERS">
 
[
 
[
 
{
 
{
Строка 214: Строка 214:
 
Любой ответ с HTTP-кодом 400 и более является ошибочным, в теле содержит код ошибки и, как правило, текстовое сообщение описывающее причины возникшей ошибки также в виде [http://ru.wikipedia.org/wiki/JSON JSON].
 
Любой ответ с HTTP-кодом 400 и более является ошибочным, в теле содержит код ошибки и, как правило, текстовое сообщение описывающее причины возникшей ошибки также в виде [http://ru.wikipedia.org/wiki/JSON JSON].
 
Пример сообщения об ошибке:
 
Пример сообщения об ошибке:
−
<source lang=javascript line=GESHI_FANCY_LINE_NUMBERS>
+
<source lang="javascript" line="GESHI_FANCY_LINE_NUMBERS">
 
{
 
{
 
"error": "User Authentication Error"
 
"error": "User Authentication Error"
Строка 220: Строка 220:
 
</source>
 
</source>
  
−
== Операции ==
+
==Операции==
−
=== Поиск ===
+
===Поиск===
−
==== Поиск одного вин запроса ====
+
====Поиск одного вин запроса====
 
'''Операция: vinquery/info/:id'''<br />
 
'''Операция: vinquery/info/:id'''<br />
 
'''Метод: GET'''
 
'''Метод: GET'''
Строка 460: Строка 460:
 
<span id="search_articles"></span>
 
<span id="search_articles"></span>
  
−
==== Поиск новых сообщений во всех чатах клиента ====
+
====Поиск новых сообщений во всех чатах клиента====
 
'''Операция: vinquery/chatList'''<br />
 
'''Операция: vinquery/chatList'''<br />
 
'''Метод: GET'''
 
'''Метод: GET'''
Строка 536: Строка 536:
 
  |}
 
  |}
  
−
==== Поиск списка вин запросов ====
+
====Поиск списка вин запросов====
 
'''Операция: vinquery/list'''<br />
 
'''Операция: vinquery/list'''<br />
 
'''Метод: GET'''
 
'''Метод: GET'''
Строка 579: Строка 579:
 
  |}
 
  |}
  
−
=== Добавить сообщение в чат ===
+
===Добавить сообщение в чат===
 
'''Операция: vinquery/addComment'''<br />
 
'''Операция: vinquery/addComment'''<br />
 
'''Метод: POST'''
 
'''Метод: POST'''
Строка 610: Строка 610:
  
 
'''POST параметры'''
 
'''POST параметры'''
−
  userId=123&id=321&comment=Test query&siteHash=fa9839689336b1fc63c0e86a7cbeb558ce51ea12&stockEnable=1&accessHash=123456
+
  userId=123&id=321&comment=Test query&siteHash=fa9839689336b1fc63c0e86a7cbeb558ce51ea12&accessHash=123456
  
 
'''Поля ответа в случае успеха'''
 
'''Поля ответа в случае успеха'''
Строка 632: Строка 632:
 
  |}
 
  |}
  
−
=== Создание запроса ===
+
===Создание запроса===
 
'''Операция: vinquery/add'''<br />
 
'''Операция: vinquery/add'''<br />
 
'''Метод: POST'''
 
'''Метод: POST'''
Строка 747: Строка 747:
 
  |}
 
  |}
  
−
=== Получение марок ===
+
===Получение марок===
  
 
'''Операция: brands/get'''<br />
 
'''Операция: brands/get'''<br />
Строка 785: Строка 785:
 
  |}
 
  |}
  
−
=== Выставить вин запрос на биржу ===
+
===Выставить вин запрос на биржу===
  
 
'''Операция: vinquery/on'''<br />
 
'''Операция: vinquery/on'''<br />
Строка 820: Строка 820:
 
  |-
 
  |-
 
  !status
 
  !status
−
  |Статус true | false.
+
  | Статус true |false.
 
  |}
 
  |}
  
−
=== Снять вин запрос с биржи ===
+
===Снять вин запрос с биржи===
  
 
'''Операция: vinquery/off'''<br />
 
'''Операция: vinquery/off'''<br />
Строка 858: Строка 858:
 
  |-
 
  |-
 
  !status
 
  !status
−
  |Статус true | false.
+
  | Статус true |false.
 
  |}
 
  |}

Версия 11:31, 16 января 2020

vertical-align:middle;
Внимание!
Данная статья предназначена для технических специалистов, обладающих, как минимум, начальными знаниями о принципах работы протокола HTTP. Консультации по вопросам относящимся к стандартам HTTP осуществляться не будут.

Общая информация

Доступ к публичному VINQU API осуществляется посредством HTTP-запросов и реализован с использованием принципов REST. Базовым URI для веб-службы является: 

https://publicapi.vinqu.com

Обмен осуществляется в кодировке UTF-8.

Для отладки вы можете воспользоваться расширением Advanced REST Client для обозревателя Google Chrome.

Запрос

Запросы на получение и запись данных осуществляются с помощью HTTP-методов GET и POST соответственно. В структуре сервиса имеется понятие операции. Операция указывается в качестве пути в URL. Параметры передаются как строка запроса HTTP (GET) или данными POST.

При использовании метода POST в HTTP-заголовке Content-Type необходимо передать медиа-тип данных запроса application/x-www-form-urlencoded и соответственно с данным типом сформировать тело HTTP-запроса.

В HTTP-заголовке Accept необходимо передать ожидаемый тип данных ответа. В настоящее время реализован только тип JSON, и, в любом случае, будет возвращен он. Тем не менее, при разработке клиента, необходимо учитывать указанную особенность и передавать заголовок Accept со значением application/json.

Ответ

В случае успешного исполнения операции, веб-служба вернет ответ с HTTP-кодом 200 и телом ответа в виде JSON. Формат ответа определяется каждой операцией. Пример результата успешного выполнения запроса: 

  1 [
  2 	{
  3 "vinquery": [
  4 {
  5 "_id": 455164,
  6 "resellerId": 248298,
  7 "siteId": 518087,
  8 "clientId": "522102",
  9 "guestInfo": {},
 10 "expertId": "565210",
 11 "carInfo": {
 12 "brand": "PEUGEOT",
 13 "model": "",
 14 "modificationId": 0,
 15 "modification": "",
 16 "vin": "Z8T4D5FS9DM010823",
 17 "frame": "",
 18 "hp": 0,
 19 "year": 0,
 20 "extraParams": {}
 21 },
 22 "parts": [
 23 {
 24 "partId": "5a1af310b44c1bf63d8b456a",
 25 "query": "Ремень доп .оборудования",
 26 "offers": [
 27 {
 28 "offerId": "5a1af3d2b44c1b983c8b456b",
 29 "brand": "Peugeot-Citroen",
 30 "number": "5750RG",
 31 "descr": "Ремень поликлиновый генератора",
 32 "quantity": 1,
 33 "expertId": "565210",
 34 "createdDateTime": 1511715794,
 35 "updatedDateTime": 1511715794,
 36 "deletedDateTime": 0,
 37 "deleted": false
 38 }
 39 ]
 40 },
 41 {
 42 "partId": "5a1af310b44c1bf63d8b456b",
 43 "query": "Передние тормозные колодки",
 44 "offers": [
 45 {
 46 "offerId": "5a1af45eb44c1b983c8b456c",
 47 "brand": "Peugeot-Citroen",
 48 "number": "1613259380",
 49 "descr": "Дисковые тормозные колодки",
 50 "quantity": 1,
 51 "expertId": "565210",
 52 "createdDateTime": 1511715934,
 53 "updatedDateTime": 1511715934,
 54 "deletedDateTime": 0,
 55 "deleted": false
 56 }
 57 ]
 58 },
 59 {
 60 "partId": "5a1af310b44c1bf63d8b456c",
 61 "query": "Фильтр воздушный",
 62 "offers": [
 63 {
 64 "offerId": "5a1af49cb44c1bae408b4567",
 65 "brand": "Peugeot-Citroen",
 66 "number": "1444XG",
 67 "descr": "Фильтр воздушный",
 68 "quantity": 1,
 69 "expertId": "565210",
 70 "createdDateTime": 1511715996,
 71 "updatedDateTime": 1511715996,
 72 "deletedDateTime": 0,
 73 "deleted": false
 74 }
 75 ]
 76 },
 77 {
 78 "partId": "5a1af310b44c1bf63d8b456d",
 79 "query": "Фильтр салона",
 80 "offers": [
 81 {
 82 "offerId": "5a1af5a1b44c1ba13e8b4567",
 83 "brand": "Peugeot-Citroen",
 84 "number": "647975",
 85 "descr": "Фильтр салона угольный",
 86 "quantity": 1,
 87 "expertId": "565210",
 88 "createdDateTime": 1511716257,
 89 "updatedDateTime": 1511716257,
 90 "deletedDateTime": 0,
 91 "deleted": false
 92 }
 93 ]
 94 },
 95 {
 96 "partId": "5a1af310b44c1bf63d8b456e",
 97 "query": "Фильтр маслянный",
 98 "offers": [
 99 {
100 "offerId": "5a1af5fbb44c1b8f3d8b456c",
101 "brand": "Peugeot-Citroen",
102 "number": "9818914980",
103 "descr": "Фильтр масляный",
104 "quantity": 1,
105 "expertId": "565210",
106 "createdDateTime": 1511716347,
107 "updatedDateTime": 1511716347,
108 "deletedDateTime": 0,
109 "deleted": false
110 }
111 ]
112 }
113 ],
114 "createdDateTime": 1511715600,
115 "updatedDateTime": 1511716409,
116 "assignedDateTime": 1511715628,
117 "acceptedDateTime": 1511715628,
118 "completedDateTime": 1511716409,
119 "processingTime": 809,
120 "history": [
121 {
122 "timestamp": 1511715600,
123 "status": "new",
124 "state": "new",
125 "event": "admin/deployAjaxAddQuery",
126 "roleState": "new",
127 "roleState_loc": "Новый"
128 },
129 {
130 "timestamp": 1511715600,
131 "state": "lock",
132 "lockId": "163804",
133 "event": "admin/setPriceBySite"
134 },
135 {
136 "timestamp": 1511715601,
137 "state": "processing_instock_wait",
138 "expertId": "565210",
139 "event": "admin/setPriceBySite"
140 },
141 {
142 "timestamp": 1511715601,
143 "state": "processing_instock_wait",
144 "type": "pushHistory",
145 "event": "admin/setPriceBySite",
146 "event_text": "messageId:90803456"
147 },
148 {
149 "timestamp": 1511715628,
150 "state": "processing_instock",
151 "expertId": "565210",
152 "event": "vinqu/acceptQuery"
153 },
154 {
155 "timestamp": 1511716409,
156 "state": "completed",
157 "expertId": "565210",
158 "event": "vinqu/expertCompleteQuery"
159 },
160 {
161 "timestamp": 1511889305,
162 "state": "closed",
163 "expertId": "565210",
164 "event": "script/vinqu_close_queries"
165 }
166 ],
167 "statistics": [
168 {
169 "id": 565210,
170 "rejectedSec": 0,
171 "completedSec": 781,
172 "completedCount": 1,
173 "parts": 5,
174 "offers": 5
175 }
176 ],
177 "status": "completed",
178 "state": "closed"
179 }
180 ],
181 "total": 1
182 }
183 ]

Любой ответ с HTTP-кодом 400 и более является ошибочным, в теле содержит код ошибки и, как правило, текстовое сообщение описывающее причины возникшей ошибки также в виде JSON. Пример сообщения об ошибке: 

1 {
2 	"error": "User Authentication Error"
3 }

Операции

Поиск

Поиск одного вин запроса

Операция: vinquery/info/:id
Метод: GET

id - Идентификатор запроса (Обязательный параметр)

Осуществляет поиск вин запроса по переданным параметрам.

Параметры запроса

Параметр Описание
siteHash хэш сайта, с которого был отправлен вин запрос (Обязательный).
accessHash хэш доступа к API (Обязательный).

Пример запроса 

https://publicapi.vinqu.com/vinquery/info/518346?siteHash=fa9839689336b1fc63c0e86a7cbeb558ce51ea12&accessHash=12345

Поля ответа

Поле Описание
_id id запроса.
resellerId id реселлера.
siteId id сайта.
clientId id клиента.
guestInfo Информация о госте.

Информация о госте

Поле Описание
name имя.
phone номер телефона.
email почта.
Поле Описание
expertId id эксперта.
carInfo информация о авто.

Информация о авто

Поле Описание
brand бренд.
model модель.
modificationId id модификации.
modification модификация.
vin вин номер.
frame фрейм номер.
hp лошадиные силы.
year год выпуска.
extraParams дополнительные параметры.
Поле Описание
parts массив с информацией о запрашиваемых запчастях следующего вида.

Информация о part

Поле Описание
partId уникальный id.
query запрос пользователя для поиска.
offers массив структур предложений, полученных от экспертов в следующем виде.

массив структур предложений, полученных от экспертов

Поле Описание
offerId уникальный id.
brand бренд.
number номер запчасти.
descr описание.
quantity количество.
expertId id эксперта.
createdDateTime timestamp создания предложения.
updatedDateTime timestamp обновления предложения.
deletedDateTime timestamp удаления предложения.
deleted флаг удалено ли предложение.
Поле Описание
createdDateTime timestamp создания запроса.
updatedDateTime timestamp обновления запроса.
assignedDateTime timestamp назначения запроса на эксперта.
acceptedDateTime timestamp принятия запроса экспертом.
completedDateTime timestamp завершения запроса.
processingTime время в секундах на выполнение запроса.
clientComment комментарий клиента.
chat массив структур с сообщениями в следующем виде.

массив структур с сообщениями

Поле Описание
timestamp отметка времени.
userId глобальный id юзера в системе.
expertId id эксперта, обрабатывающего запрос.
roleState состояние запроса.
roleState_loc состояние запроса в локализации (по умолчанию ru_RU - русская).
comment текст сообщения.
Поле Описание
images массив строк с названием изображений.
status статус запроса.
state текущее состояние запроса.

Поиск новых сообщений во всех чатах клиента

Операция: vinquery/chatList
Метод: GET

Осуществляет поиск всех новых сообщений, максимум за последние 15 минут по всем чатам клиента. В случае отсутствия сообщений вернётся ошибка со статусом 404 и текстом `messages not found`


Параметры запроса

Параметр Описание
siteHash хэш сайта (Обязательный параметр)
accessHash хэш доступа к API (Обязательный).
timestamp отметка времени, начиная с которой показывать сообщения
locale локализация (про умолчанию ru_RU) возможные значения (ru_RU , en_US)

Пример запроса 

https://publicapi.vinqu.com/vinquery/chatList?siteHash=fa9839689336b1fc63c0e86a7cbeb558ce51ea12&accessHash=123456&timestamp=1533642418

Поля ответа в случае успешно выполненного запроса

Поле Описание
chatList массив, у которого ключ - номер запроса, значение - массив структур chatItem.

структура chatItem

Поле Описание
timestamp отметка времени.
userId id клиента.
expertId id эксперта, обрабатывающего запрос.
roleState состояние запроса.
roleState_loc состояние запроса локализованное.
comment текст сообщения.

Поля ответа в случае ошибки

Поле Описание
Error текст ошибки.

Поиск списка вин запросов

Операция: vinquery/list
Метод: GET

Осуществляет поиск списка вин запросов по переданным параметрам.


Параметры запроса

Параметр Описание
siteHash хэш сайта (Обязательный параметр)
accessHash хэш доступа к API (Обязательный).
skip начало выборки, по умолчанию 0
limit сколько максимум выбрать. По умолчанию 30


Пример запроса https://publicapi.vinqu.com/vinquery/list?siteHash=fa9839689336b1fc63c0e86a7cbeb558ce51ea12&accessHash=123456

Поля ответа


Поле Описание
vinquery Массив структур вин запроса (пример выше в vinquery/info).
total Количество найденных запросов.

Добавить сообщение в чат

Операция: vinquery/addComment
Метод: POST

Осуществляет добавление нового сообщения в чат

Параметры запроса

Параметр Описание
siteHash хэш сайта (Обязательный)
accessHash хэш доступа к API (Обязательный).
userId id клиента
id id запроса
comment Текст сообщения

Пример запроса https://publicapi.vinqu.com/vinquery/addComment

POST параметры 

userId=123&id=321&comment=Test query&siteHash=fa9839689336b1fc63c0e86a7cbeb558ce51ea12&accessHash=123456

Поля ответа в случае успеха

Поле Описание
Status true или false

Поля ответа в случае ошибки

Поле Описание
Error Текст ошибки

Создание запроса

Операция: vinquery/add
Метод: POST

Осуществляет создание нового вин запроса

Параметры запроса

Параметр Описание
siteHash хэш сайта (Обязательный)
accessHash хэш доступа к API (Обязательный).
clientId id клиента
carInfo Информация об автомобиле. Ассоциативный массив следующего вида

Информация об автомобиле

Поле Описание
brand бренд.
model модель.
modificationId id модификации.
modification модификация.
vin вин номер.
frame фрейм номер.
hp лошадиные силы.
year год выпуска.


Параметр Описание
clientComment Комментарий клиента.
parts Массив запчастей из запроса клиента.
stockEnable флаг 1 или 0, отправлять ли запрос на биржу.
guestInfo Информация о госте.

Информация о госте

Поле Описание
name имя.
phone номер телефона.
email почта.

Пример запроса https://publicapi.vinqu.com/vinquery/add

POST параметры 

clientId=123&carInfo[brand]=Luxgen&carInfo[vin]=222AAA11111111111&parts[]=test&parts[]=test1&clientComment=Test query&siteHash=fa9839689336b1fc63c0e86a7cbeb558ce51ea12&stockEnable=1&accessHash=123456

Поля ответа в случае успеха

Поле Описание
QueryId id запроса

Поля ответа в случае ошибки

Поле Описание
Error Текст ошибки

Получение марок

Операция: brands/get
Метод: GET

Осуществляет поиск марок, подключённых сайту.

Параметры запроса

Параметр Описание
hash хэш сайта (Обязательный)
accessHash хэш доступа к API (Обязательный).

Пример запроса https://publicapi.vinqu.com/brands/get?hash=fa9839689336b1fc63c0e86a7cbeb558ce51ea12&accessHash=123456

Поля ответа Получает массив структур следующего вида

Поле Описание
brand Бренд.
price Цена
enabled включен или нет on или off

Выставить вин запрос на биржу

Операция: vinquery/on
Метод: POST

Осуществляет выставление вин запроса на биржу.

Параметры запроса

Параметр Описание
id id запроса
siteHash хэш сайта (Обязательный)
accessHash хэш доступа к API (Обязательный).

Пример запроса https://publicapi.vinqu.com/vinquery/on

POST параметры 

id=999999999&siteHash=fa9839689336b1fc63c0e86a7cbeb558ce51ea12&accessHash=123456

Поля ответа Получает массив структур следующего вида

Поле Описание
status false.

Снять вин запрос с биржи

Операция: vinquery/off
Метод: POST

Осуществляет снятие вин запроса с биржи.

Параметры запроса

Параметр Описание
id id запроса
siteHash хэш сайта (Обязательный)
accessHash хэш доступа к API (Обязательный).

Пример запроса https://publicapi.vinqu.com/vinquery/off

POST параметры 

id=123&siteHash=fa9839689336b1fc63c0e86a7cbeb558ce51ea2a&accessHash=123456

Поля ответа Получает массив структур следующего вида

Поле Описание
status false.
Источник — https://www.abcp.ru/w/index.php?title=APIVINQU&oldid=8884