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

Версия 10:07, 5 февраля 2018

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

Содержание

1 Общая информация
- 1.1 Запрос
- 1.2 Ответ
2 Операции

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

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

http://public.vinqu.api.abcp.ru/

Обмен осуществляется в кодировке 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 	"status": false,
3 	"error": "User Authentication Error"
4 }

Операции

Поиск

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

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

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

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

Параметр	Описание
id	Идентификатор запроса (Обязательный параметр)
resellerId	id сайта - клиента платформы ABCP, с которого был отправлен вин запрос (Может быть пустой)
locale	Локаль. Задается в формате language[_territory], например, ru_RU. (Может быть пустой, по умолчанию ru_RU)
siteId	id сайта, с которого был отправлен вин запрос (Может быть пустой).

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

http://public.vinqu.api.abcp.ru/vinquery/info?id=1234

Поля ответа

Поле	Описание
_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 юзера в системе.
comment	текст сообщения.

Поле	Описание
images	массив строк с названием изображений.
status	статус запроса.
state	текущее состояние запроса.

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

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

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

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

Параметр	Описание
resellerId	id реселлера
skip	начало выборки, по умолчанию 0
limit	сколько максимум выбрать. По умолчанию 30
locale	Локализация. По умолчанию ru_RU
filter	Фильтр - массив с возможными значениями.

Фильтр - массив с возможными значениями

Параметр	Описание
id	id запроса
resellerId	id реселлера
siteId	id сайта
clientId	id клиента
expertId	id эксперта.
vin	Значение vin.
frame	Значение фрейм.
stock	На бирже или нет флаг. 0 или 1.
accepted	Принят ли экспертом флаг 0 или 1.
clientIdNot	id клиента не равен переданному.
expertIdNot	id эксперта не равен переданному.
modificationId	id модификации.
createdDateTime	Время создания запроса. Ассоциативный массив, возможные ключи from и to, а значения timestamp.
updatedDateTime	Время обновления запроса. Ассоциативный массив, возможные ключи from и to, а значения timestamp.
assignedDateTime	Время назначения запроса. Ассоциативный массив, возможные ключи from и to, а значения timestamp.
acceptedDateTime	Время принятия запроса экспертом. Ассоциативный массив, возможные ключи from и to, а значения timestamp.
completedDateTime	Время завершения запроса. Ассоциативный массив, возможные ключи from и to, а значения timestamp.
brandNot	Бренд не должен быть равен переданному.
q	Поиск значения внутри carInfo по одному из полей.
partsQuery	Запрашиваемая запчасть.
expertIn	Массив id экспертов.
state	Массив состояний.

Пример запроса http://public.vinqu.api.abcp.ru/vinquery/list?filter[clientId]=522102&filter[state][]=closed&filter[vin]=Z8T4D5FS9DM010823&filter[expertId]=565210

Поля ответа

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

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

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

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

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

Параметр	Описание
resellerId	id реселлера
clientId	id клиента
carInfo	Информация об автомобиле. Ассоциативный массив следующего вида

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

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

Параметр	Описание
clientComment	Комментарий клиента.
file	название изображения, загруженного в наш file.api.
siteId	id сайта.
parts	Массив запчастей из запроса клиента.
guestInfo	Информация о госте.

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

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

Пример запроса http://public.vinqu.api.abcp.ru/vinquery/add

POST параметры

resellerId=13194&clientId=123&carInfo[brand]=LUXGEN&carInfo[model]=&carInfo[modificationId]=0&carInfo[modification]=&carInfo[hp]=0&carInfo[vin]=77998833225566787&carInfo[frame]=&carInfo[year]=0&clientComment=test&parts[0]=test

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

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

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

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

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

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

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

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

Параметр	Описание
siteId	id сайта
hash	хэш сайта

Пример запроса http://public.vinqu.api.abcp.ru/brands/get?siteId=440268

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

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

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

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

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

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

Параметр	Описание
id	id запроса
price	цена вин запроса
siteId	id сайта

Пример запроса http://public.vinqu.api.abcp.ru/vinquery/on?siteId=440268

POST параметры

id=999999999&partPrice=10&price=10&rating=90&siteId=440268

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

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

@@ Строка 747: / Строка 747: @@
   !id
   |id запроса
- |-
- !partPrice
- |цена за позицию
   |-
   !price
   |цена вин запроса
- |-
- !rating
- |минимальный рейтинг эксперта
   |-
   !siteId