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

Текущая версия на 18:26, 28 мая 2025

Внимание!
Данная статья предназначена для технических специалистов, обладающих, как минимум, начальными знаниями о принципах работы протокола HTTPS. Консультации по вопросам относящимся к стандартам HTTPS осуществляться не будут.

Содержание

1 API VINQU

API VINQU

Авторизация запросов

Значения параметров siteHash и accessHash вы можете взять в настройках интеграции своей учетной записи.

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

Операция: 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 клиента
file	Прикрепленный файл изображения. В curl запросе file=@"/path_to_image/image.jpg". Формат изображения: jpg/png
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.

@@ Строка 1: / Строка 1: @@
-{{Внимание|Данная статья предназначена для технических специалистов, обладающих, как минимум, начальными знаниями о принципах работы протокола HTTP. Консультации по вопросам относящимся к стандартам HTTP осуществляться не будут.}}
+{{Внимание|Данная статья предназначена для технических специалистов, обладающих, как минимум, начальными знаниями о принципах работы протокола HTTPS. Консультации по вопросам относящимся к стандартам HTTPS осуществляться не будут.}}
 __TOC__
-==Общая информация==
+<br />
+==API VINQU==
+===Авторизация запросов===
+Значения параметров '''siteHash''' и '''accessHash''' вы можете взять в [https://site.vinqu.com/?page=connect настройках интеграции своей учетной записи].
-Доступ к публичному 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].
+===Поиск одного вин запроса===
-Базовым URI для веб-службы является:
+'''Операция:''' vinquery/info/:id<br />'''Метод:''' GET
-<pre>
-https://publicapi.vinqu.com
-</pre>
-Обмен осуществляется в кодировке UTF-8.
-Для отладки вы можете воспользоваться расширением [https://chrome.google.com/webstore/detail/advanced-rest-client/hgmloofddffdnphfgcellkdfbfbjeloo?utm_source=chrome-ntp-icon 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 и телом ответа в виде [http://ru.wikipedia.org/wiki/JSON JSON]. Формат ответа определяется каждой операцией. Пример результата успешного выполнения запроса:
-<source lang="javascript" line="GESHI_FANCY_LINE_NUMBERS">
-[
-	{
-"vinquery": [
-{
-"_id": 455164,
-"resellerId": 248298,
-"siteId": 518087,
-"clientId": "522102",
-"guestInfo": {},
-"expertId": "565210",
-"carInfo": {
-"brand": "PEUGEOT",
-"model": "",
-"modificationId": 0,
-"modification": "",
-"vin": "Z8T4D5FS9DM010823",
-"frame": "",
-"hp": 0,
-"year": 0,
-"extraParams": {}
-},
-"parts": [
-{
-"partId": "5a1af310b44c1bf63d8b456a",
-"query": "Ремень доп .оборудования",
-"offers": [
-{
-"offerId": "5a1af3d2b44c1b983c8b456b",
-"brand": "Peugeot-Citroen",
-"number": "5750RG",
-"descr": "Ремень поликлиновый генератора",
-"quantity": 1,
-"expertId": "565210",
-"createdDateTime": 1511715794,
-"updatedDateTime": 1511715794,
-"deletedDateTime": 0,
-"deleted": false
-}
-]
-},
-{
-"partId": "5a1af310b44c1bf63d8b456b",
-"query": "Передние тормозные колодки",
-"offers": [
-{
-"offerId": "5a1af45eb44c1b983c8b456c",
-"brand": "Peugeot-Citroen",
-"number": "1613259380",
-"descr": "Дисковые тормозные колодки",
-"quantity": 1,
-"expertId": "565210",
-"createdDateTime": 1511715934,
-"updatedDateTime": 1511715934,
-"deletedDateTime": 0,
-"deleted": false
-}
-]
-},
-{
-"partId": "5a1af310b44c1bf63d8b456c",
-"query": "Фильтр воздушный",
-"offers": [
-{
-"offerId": "5a1af49cb44c1bae408b4567",
-"brand": "Peugeot-Citroen",
-"number": "1444XG",
-"descr": "Фильтр воздушный",
-"quantity": 1,
-"expertId": "565210",
-"createdDateTime": 1511715996,
-"updatedDateTime": 1511715996,
-"deletedDateTime": 0,
-"deleted": false
-}
-]
-},
-{
-"partId": "5a1af310b44c1bf63d8b456d",
-"query": "Фильтр салона",
-"offers": [
-{
-"offerId": "5a1af5a1b44c1ba13e8b4567",
-"brand": "Peugeot-Citroen",
-"number": "647975",
-"descr": "Фильтр салона угольный",
-"quantity": 1,
-"expertId": "565210",
-"createdDateTime": 1511716257,
-"updatedDateTime": 1511716257,
-"deletedDateTime": 0,
-"deleted": false
-}
-]
-},
-{
-"partId": "5a1af310b44c1bf63d8b456e",
-"query": "Фильтр маслянный",
-"offers": [
-{
-"offerId": "5a1af5fbb44c1b8f3d8b456c",
-"brand": "Peugeot-Citroen",
-"number": "9818914980",
-"descr": "Фильтр масляный",
-"quantity": 1,
-"expertId": "565210",
-"createdDateTime": 1511716347,
-"updatedDateTime": 1511716347,
-"deletedDateTime": 0,
-"deleted": false
-}
-]
-}
-],
-"createdDateTime": 1511715600,
-"updatedDateTime": 1511716409,
-"assignedDateTime": 1511715628,
-"acceptedDateTime": 1511715628,
-"completedDateTime": 1511716409,
-"processingTime": 809,
-"history": [
-{
-"timestamp": 1511715600,
-"status": "new",
-"state": "new",
-"event": "admin/deployAjaxAddQuery",
-"roleState": "new",
-"roleState_loc": "Новый"
-},
-{
-"timestamp": 1511715600,
-"state": "lock",
-"lockId": "163804",
-"event": "admin/setPriceBySite"
-},
-{
-"timestamp": 1511715601,
-"state": "processing_instock_wait",
-"expertId": "565210",
-"event": "admin/setPriceBySite"
-},
-{
-"timestamp": 1511715601,
-"state": "processing_instock_wait",
-"type": "pushHistory",
-"event": "admin/setPriceBySite",
-"event_text": "messageId:90803456"
-},
-{
-"timestamp": 1511715628,
-"state": "processing_instock",
-"expertId": "565210",
-"event": "vinqu/acceptQuery"
-},
-{
-"timestamp": 1511716409,
-"state": "completed",
-"expertId": "565210",
-"event": "vinqu/expertCompleteQuery"
-},
-{
-"timestamp": 1511889305,
-"state": "closed",
-"expertId": "565210",
-"event": "script/vinqu_close_queries"
-}
-],
-"statistics": [
-{
-"id": 565210,
-"rejectedSec": 0,
-"completedSec": 781,
-"completedCount": 1,
-"parts": 5,
-"offers": 5
-}
-],
-"status": "completed",
-"state": "closed"
-}
-],
-"total": 1
-}
-]
-</source>
-Любой ответ с HTTP-кодом 400 и более является ошибочным, в теле содержит код ошибки и, как правило, текстовое сообщение описывающее причины возникшей ошибки также в виде [http://ru.wikipedia.org/wiki/JSON JSON].
+id - Идентификатор запроса (Обязательный параметр)
-Пример сообщения об ошибке:
-<source lang="javascript" line="GESHI_FANCY_LINE_NUMBERS">
-{
-	"error": "User Authentication Error"
-}
-</source>
-==Операции==
-===Поиск===
-====Поиск одного вин запроса====
-'''Операция: vinquery/info/:id'''<br />
-'''Метод: GET'''
-:id - Идентификатор запроса (Обязательный параметр)
 Осуществляет поиск вин запроса по переданным параметрам.
@@ Строка 268: / Строка 52: @@
   |}
-<span>Информация о госте</span>
+Информация о госте
-    {| class="wikitable" style="margin-left:50px"
+{| class="wikitable"
-     !Поле
+ !Поле
-     !Описание
+ !Описание
-     |-
+ |-
-     !name
+ !name
-     |имя.
+ |имя.
-     |-
+ |-
-     !phone
+ !phone
-     |номер телефона.
+ |номер телефона.
-     |-
+ |-
-     !email
+ !email
-     |почта.
+ |почта.
-     |}
+ |}
 {| class="wikitable"
@@ Строка 297: / Строка 81: @@
 <span>Информация о авто</span>
-{| class="wikitable" style="margin-left:50px"
+{| class="wikitable"
   !Поле
   !Описание
@@ Строка 339: / Строка 123: @@
 <span>Информация о part</span>
-{| class="wikitable" style="margin-left:50px"
+{| class="wikitable"
   !Поле
   !Описание
@@ Строка 353: / Строка 137: @@
   |}
-<span>массив структур предложений, полученных от экспертов</span>
+массив структур предложений, полученных от экспертов
+{| class="wikitable"
-{| class="wikitable" style="margin-left:100px"
   !Поле
   !Описание
@@ Строка 421: / Строка 204: @@
 <span>массив структур с сообщениями</span>
-{| class="wikitable" style="margin-left:50px"
+{| class="wikitable"
   !Поле
   !Описание
@@ Строка 458: / Строка 241: @@
   |}
-<span id="search_articles"></span>
+===Поиск новых сообщений во всех чатах клиента===
+'''Операция:''' vinquery/chatList'''<br />Метод:''' GET
-====Поиск новых сообщений во всех чатах клиента====
-'''Операция: vinquery/chatList'''<br />
-'''Метод: GET'''
 Осуществляет поиск всех новых сообщений, максимум за последние 15 минут по всем чатам клиента.
 В случае отсутствия сообщений вернётся ошибка со статусом 404 и текстом `messages not found`
 '''Параметры запроса'''
@@ Строка 536: / Строка 315: @@
   |}
-====Поиск списка вин запросов====
+===Поиск списка вин запросов===
-'''Операция: vinquery/list'''<br />
+'''Операция:''' vinquery/list<br />'''Метод:''' GET
-'''Метод: GET'''
 Осуществляет поиск списка вин запросов по переданным параметрам.
 '''Параметры запроса'''
@@ Строка 566: / Строка 343: @@
 '''Поля ответа'''
 {| class="wikitable"
   !Поле
@@ Строка 580: / Строка 355: @@
 ===Добавить сообщение в чат===
-'''Операция: vinquery/addComment'''<br />
+'''Операция:''' vinquery/addComment<br />'''Метод:''' POST
-'''Метод: POST'''
 Осуществляет добавление нового сообщения в чат
@@ Строка 633: / Строка 407: @@
 ===Создание запроса===
-'''Операция: vinquery/add'''<br />
+'''Операция:''' vinquery/add
-'''Метод: POST'''
+'''Метод:''' POST
 Осуществляет создание нового вин запроса
@@ Строка 651: / Строка 426: @@
   !clientId
   |id клиента
+ |-
+ !file
+ |Прикрепленный файл изображения. В curl запросе file=@"/path_to_image/image.jpg". Формат изображения: jpg/png
   |-
   !carInfo
@@ Строка 656: / Строка 434: @@
   |}
-<span>Информация об автомобиле</span>
+Информация об автомобиле
-{| class="wikitable" style="margin-left:50px"
+{| class="wikitable"
   !Поле
   !Описание
@@ Строка 686: / Строка 464: @@
   |год выпуска.
   |}
 {| class="wikitable"
@@ Строка 707: / Строка 484: @@
 <span>Информация о госте</span>
-    {| class="wikitable" style="margin-left:50px"
+{| class="wikitable"
-     !Поле
+ !Поле
-     !Описание
+ !Описание
-     |-
+ |-
-     !name
+ !name
-     |имя.
+ |имя.
-     |-
+ |-
-     !phone
+ !phone
-     |номер телефона.
+ |номер телефона.
-     |-
+ |-
-     !email
+ !email
-     |почта.
+ |почта.
-     |}
+ |}
 '''Пример запроса'''
@@ Строка 749: / Строка 526: @@
 ===Получение марок===
-'''Операция: brands/get'''<br />
+'''Операция:''' brands/get
-'''Метод: GET'''
+'''Метод:''' GET
 Осуществляет поиск марок, подключённых сайту.
@@ Строка 770: / Строка 548: @@
 '''Поля ответа'''
 Получает массив структур следующего вида
 {| class="wikitable"
@@ Строка 787: / Строка 566: @@
 ===Выставить вин запрос на биржу===
-'''Операция: vinquery/on'''<br />
+'''Операция:''' vinquery/on
-'''Метод: POST'''
+'''Метод:''' POST
 Осуществляет выставление вин запроса на биржу.
@@ Строка 814: / Строка 594: @@
 '''Поля ответа'''
 Получает массив структур следующего вида
 {| class="wikitable"
@@ Строка 825: / Строка 606: @@
 ===Снять вин запрос с биржи===
-'''Операция: vinquery/off'''<br />
+'''Операция:''' vinquery/off
-'''Метод: POST'''
+'''Метод:''' POST
 Осуществляет снятие вин запроса с биржи.