Документация для разработчиков "WEB-Service" REST API

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

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

http://b2motor.ru/api/webservice/

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

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

Запрос

Запросы на получение и запись данных осуществляются с помощью HTTP-методов GET и POST соответственно. В структуре сервиса имеется понятие операции. Операция указывается в качестве пути в URL. Параметры передаются как строка запроса HTTP (GET) или данными POST. Большая часть операций исполняется от имени конкретного пользователя и требует идентификации с помощью параметров userlogin (имя пользователя в системе) и userpsw (md5-хэш пароля пользователя). Md5-хэш можно сгенерировать выполнением функции (большая часть языков программирования имеет данную функцию в своем арсенале), либо воспользоваться online-генератором (например, md5x). Каждая операция может иметь список дополнительных параметров, определяемых контекстом операции. Например, вызов операции "Поиск детали по номеру" может выглядеть следующим образом:

http://b2motor.ru/api/webservice/search/articles/?userlogin=username&userpassw=md5pass&number=01089&brand=WEBER


Ответ

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

 1 [
 2 	{
 3 		"brand": "Hepu",
 4 		"article": "P999",
 5 		"articleFix": "P999",
 6 		"articleId": "2854918",
 7 		"description": "Антифриз [синий] 1,5л.",
 8 		"availability": "-1",
 9 		"deliveryPeriod": 3,
10 		"price": 231,
11 		"weight": "0"
12 	},
13 	{
14 		"brand": "Febi",
15 		"article": "01089",
16 		"articleFix": "01089",
18 		"description": "Антифриз 1.5 л синий",
19 		"availability": "1943",
20 		"deliveryPeriod": 3,
21 		"price": 233,
22 		"weight": "1.76"
23 	},
24 	{
25 		"brand": "Vaico Vemo",
26 		"article": "V600020",
27 		"articleFix": "V600020",
29 		"description": "Антифриз g-11 1.5л. концентрат",
30 		"availability": "-2",
31 		"deliveryPeriod": 3,
32 		"price": 235,
33 		"weight": "0"
34 	}
35 ]

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

1 {
2 	"errorCode": 102,
3 	"errorMessage": "User Authentication Error"
4 }


Описание команд


Поиск детали по номеру и бренду

Операция: search/product/
Метод: GET

Осуществляет поиск по номеру детали и бренду. Возвращает массив найденных деталей. Так как один и тот же производитель может иметь несколько общепринятых наименований (например, GM и General Motors), система постарается это учесть, используя собственную базу синонимов брендов.

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

Параметр Описание
userlogin Имя пользователя в системе
userpassw md5-хэш пароля пользователя в системе (выдается персональным менеджером)
article Искомый каталожный номер детали
brand Производитель (бренд) искомой детали
isАnalog Флаг "необходимость учитывать аналоги". 0 - отключено, 1 - включено (по умолчанию - 1)
isOnlineStocks Флаг "использовать online-склады". 0 - отключено, 1 - включено, Увеличивает время ожидания ответа (по умолчанию - 0)

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

http://b2motor.ru/api/webservice/search/product/?article=24-1106010&brand=ШАНС ПЛЮС&userlogin=username&userpassw=md5pass


Поля ответа

Метод возвращает массив объектов вида:

brand Имя производителя.
brandID Идентификатор производителя в системе b2motor.ru.
article Каталожный номер (артикул) детали.
articleFix "Очищенный" каталожный номер (артикул), содержащий только алфавитные и цифровые символы.
description Описание детали.
availability Наличие детали на складе. Отрицательные значения -1, -2 и -3 означают "неточное" наличие, которое на сайте выглядит как "+", "++" и "+++" соответственно. Отрицательное значение -10 означает наличие "под заказ".
packing Мин. партия для заказа (кратность).
deliveryPeriod Срок поставки (в днях).
deliveryPeriodMax Максимальный срок поставки (в днях).
distributorID Идентификатор поставщика (Необходим при включении веб-проценки и прайсов)
storeID Идентификатор склада выписки товара.
storeDescription Описание склада выписки товара.
price Цена в рублях.
weight Вес одной единицы товара в килограммах.
lastUpdateTime Время последнего обновления элемента
noReturn Флаг "Без возврата(1-товар без возврата, не относится к товарам ненадлежащего качества)"
code Внутренний код детали используется для заказа
detailGroup Группы деталей, относительно искомой детали.(Original - Искомая деталь;ReplacementOriginal - Оригинальная замена на искомую деталь (замена того же производителя);ReplacementNonOriginal - Не оригинальная замена (аналог) на искомую деталь (замена от другого производителя)).

Добавление товаров в корзину

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

Метод добавляет товар в корзину. Обязательно необходимы бренд, артикул, код товара, идентификатор склада и идентификатор поставщика. При добавлениипозиции, которая уже была ранее добавлена в корзину значение quantity будет прибавлено к существующему.


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

Параметр Описание
userlogin Имя пользователя в системе
userpassw md5-хэш пароля пользователя в системе (выдается персональным менеджером)
positions Набор добавляемых деталей


Расшифровка параметра positions

Параметр Описание
brand Имя производителя.
article аталожный номер (артикул) детали.
distributorID Идентификатор поставщика.
storeID Идентификатор склада выписки товара.
quantity Количество товара, необходимое для добавления
price Цена за единицу товара
code Внутренний код детали используется для заказа

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

http://b2motor.ru/api/webservice/basket/add/?userlogin=username&userpassw=md5pass

 1 {
 2 	"positions":
 3 	    [
 4 		  {
 5 			"brand": "САЗ",
 6 			"article": "2121-2915402",
 7 			"distributorID": "1",
 8 			"storeID": "0007",
 9 			"quantity": "6",
10 			"price": "427",
11 			"code": "078733",
12 		  },
13 		  {
14 			"brand": "AVS",
15 			"article": "A78220S",
16 			"distributorID": "1",
17 			"storeID": "0999",
18 			"quantity": "2",
19 			"price": "175",
20 			"code": "701072",
21 		  }
22 	    ]
23 }


Поля ответа

Метод возвращает объект вида:

status Общий статус операции (0 - в добавлении эллементов произошли какие либо ошибки (в массиве positions необходимо отслеживать errorCode с кодом ошибки по конкретным эллементам), 1 - все товары были добавлены в корзину без ошибок)
positions Набор добавляемых деталей

Расшифровка параметра positions

Параметр Описание
brand Имя производителя.
article аталожный номер (артикул) детали.
description Описание детали.
deliveryPeriod Минимальный порог предполагаемой даты поставки до клиента.
deliveryPeriodMax Максимальный порог предполагаемой даты поставки до клиента.
distributorID Идентификатор поставщика.
storeID Идентификатор склада выписки товара.
quantity Количество товара, добавленного в корзину(не путайти с количеством товара в самой корзине).
price Цена за единицу товара.
weight Вес одной единицы товара в килограммах.
code Внутренний код детали используется для заказа.
canBay Доступен для добавления в заказ(1 - доступен, 0- недоступен к заказу(не попадет в заказ)).
errorCode Код ошибки (если она есть).
errorMessage Текст сообщения об ошибке при статусе (если она есть).

Изменение количества товаров в корзине

Операция: basket/edit/
Метод: GET

метод меняет количество товара на quantity


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

Параметр Описание
userlogin Имя пользователя в системе
userpassw md5-хэш пароля пользователя в системе (выдается персональным менеджером)
basketId Идентификатор элемента в корзине
quantity Количество товара в корзине на которое будет ЗАМЕНЕНО старое значение(если свойство отсутствует делает количество равным 1)

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

http://b2motor.ru/api/webservice/basket/edit/?basketId=167846&quantity=12&userlogin=username&userpassw=md5pass


Параметры ответа

Метод возвращает объект вида:

status Статус операции (0 - изменение количества завершилось ошибкой, 1 - успешное изменение количество)
errorCode Код ошибки (при статусе 0).
errorMessage Текст сообщения об ошибке при статусе (при статусе 0).

Удаление элементов корзины

Операция: basket/delete/
Метод: GET

метод удаляет один или несколько эллементов корзины


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

Параметр Описание
userlogin Имя пользователя в системе
userpassw md5-хэш пароля пользователя в системе (выдается персональным менеджером)
basketId Идентификатор элемента в корзине(строка либо массив)

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

http://b2motor.ru/api/webservice/basket/delete/?basketId[0]=167846&basketId[1]=167847&userlogin=username&userpassw=md5pass


Параметры ответа

Метод возвращает объект вида:

status Статус операции (0 - удаление эллементов завершилось ошибкой, 1 - успешное удаление количество)
positions Набор удаляемых эллементов корзины
errorCode Код ошибки (при статусе 0).
errorMessage Текст сообщения об ошибке при статусе (при статусе 0).

Расшифровка параметра positions

Параметр Описание
status Статус операции (0 - удаление эллемента завершилось ошибкой, 1 - удаление изменение количество)
basketId Идентификатор удаляемого эллемента
errorCode Код ошибки (при статусе 0).
errorMessage Текст сообщения об ошибке при статусе (при статусе 0).

полная очистка корзины

Операция: basket/clear/
Метод: GET

метод удаляет ВСЕ эллементы корзины


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

Параметр Описание
userlogin Имя пользователя в системе
userpassw md5-хэш пароля пользователя в системе (выдается персональным менеджером)

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

http://b2motor.ru/api/webservice/basket/clear/?userlogin=username&userpassw=md5pass


Параметры ответа

Метод возвращает объект вида:

status Статус операции (0 - очистка корзины завершилась ошибкой, 1 - успешная очистка корзины)
errorCode Код ошибки (при статусе 0).
errorMessage Текст сообщения об ошибке при статусе (при статусе 0).

Получение списка товаров в корзине

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

метод удаляет ВСЕ эллементы корзины


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

Параметр Описание
userlogin Имя пользователя в системе
userpassw md5-хэш пароля пользователя в системе (выдается персональным менеджером)

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

http://b2motor.ru/api/webservice/basket/list/?userlogin=username&userpassw=md5pass


Параметры ответа

Метод возвращает объект вида:

status Статус корзины (0 - если среди эллементов корзины есть недоступные для оформления заказа, 1 - все эллементы доступны для заказа)
positions Массив обьектов эллементов корзины

Расшифровка параметра positions

Параметр Описание
brand Имя производителя.
article аталожный номер (артикул) детали.
description Описание детали.
deliveryPeriod Минимальный порог предполагаемой даты поставки до клиента.
deliveryPeriodMax Максимальный порог предполагаемой даты поставки до клиента.
distributorID Идентификатор поставщика.
storeID Идентификатор склада выписки товара.
quantity Количество товара, добавленного в корзину(не путайти с количеством товара в самой корзине).
price Цена за единицу товара.
weight Вес одной единицы товара в килограммах.
code Внутренний код детали используется для заказа.
canBay Доступен для добавления в заказ(1 - доступен, 0- недоступен к заказу(не попадет в заказ)).
errorCode Код ошибки (если она есть).
errorMessage Текст сообщения об ошибке при статусе (если она есть).

Оформление корзины в заказ

Операция: orders/add/
Метод: GET

метод добавляет эллементы корзины в заказ (возможно частичное оформление)


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

Параметр Описание
userlogin Имя пользователя в системе
userpassw md5-хэш пароля пользователя в системе (выдается персональным менеджером)
basketId Идентификатор элемента в корзине(строка либо массив)

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

http://b2motor.ru/api/webservice/orders/add/?userlogin=username&userpassw=md5pass


Параметры ответа

Метод возвращает объект вида:

status Статус операции (0 - ошибки при оформлении заказа, 1 - заказ оформлен полностью)
orders Обьект содержащий информацию о заказе со списком эллементов
errorCode Код ошибки (если она есть).
errorMessage Текст сообщения об ошибке при статусе (если она есть).

Узел orders возвращает набор объектов вида

number Номер заказа(Идентификатор заказа в системе)
statusCode Код статуса заказа.
sum Сумма заказа.
comment Коментарий к заказу
positions Массив обьектов элементов корзины

Расшифровка параметра positions

Параметр Описание
brand Имя производителя.
article аталожный номер (артикул) детали.
description Описание детали.
deliveryPeriod Минимальный порог предполагаемой даты поставки до клиента.
deliveryPeriodMax Максимальный порог предполагаемой даты поставки до клиента.
distributorID Идентификатор поставщика.
storeID Идентификатор склада выписки товара.
quantity Количество товара, добавленного в корзину(не путайти с количеством товара в самой корзине).
price Цена за единицу товара.
weight Вес одной единицы товара в килограммах.
code Внутренний код детали используется для заказа.
canBay Доступен для добавления в заказ(1 - доступен, 0- недоступен к заказу(не попадет в заказ)).
errorCode Код ошибки (если она есть).
errorMessage Текст сообщения об ошибке при статусе (если она есть).

Список заказов/заказ детально

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

метод добавляет эллементы корзины в заказ (возможно частичное оформление)


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

Параметр Описание
userlogin Имя пользователя в системе
userpassw md5-хэш пароля пользователя в системе (выдается персональным менеджером)
number Номер заказа (необходим для деталировки конкретного заказа)
format (необязательный) - формат вывода результата. По умолчанию отображается информация только по заказам. При значении "1" - к заказам добавляется информация по всем позициям. Если используется number, тозначение автоматически равно "1"

Пример запроса на полный список заказов

http://b2motor.ru/api/webservice/orders/list/?userlogin=username&userpassw=md5pass
http://b2motor.ru/api/webservice/orders/list/?format=1&userlogin=username&userpassw=md5pass


Пример запроса на деталировку заказа

http://b2motor.ru/api/webservice/orders/list/?number=957831&userlogin=username&userpassw=md5pass


Параметры ответа

Метод возвращает объект вида:

Параметр Описание
count Колличество заказов в выдаваемом результате
orders массив обьектов с информацией о заказах
errorCode Код ошибки (если она есть).
errorMessage Текст сообщения об ошибке (если она есть).

Расшифровка orders

number Номер заказа (идентификатор заказа).
date Дата создания заказа в системе.
statusCode Код статуса заказа.
statusName Статус заказа.
sum Сумма заказа.
Quantity Количество позиций.
comment Комментарий к заказу.
positions Список позиций заказа (если format=1 или запрашивается number).
errorCode Код ошибки (если она есть).
errorMessage Текст сообщения об ошибке при статусе (если она есть).

Расшифровка параметра positions

Параметр Описание
brand Имя производителя.
article аталожный номер (артикул) детали.
description Описание детали.
deliveryPeriod Минимальный порог предполагаемой даты поставки до клиента.
deliveryPeriodMax Максимальный порог предполагаемой даты поставки до клиента.
distributorID Идентификатор поставщика.
storeID Идентификатор склада выписки товара.
quantity Количество товара, добавленного в корзину(не путайти с количеством товара в самой корзине).
price Цена за единицу товара.
weight Вес одной единицы товара в килограммах.
code Внутренний код детали используется для заказа.
canBay Доступен для добавления в заказ(1 - доступен, 0- недоступен к заказу(не попадет в заказ)).
errorCode Код ошибки (если она есть).
errorMessage Текст сообщения об ошибке при статусе (если она есть).