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

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

Веб-сервис - это "шлюз", через который одна программа может обращаться к другой для получения (или передачи) нужной информации. Веб-сервис включает в себя список функций, посредством которых можно отправлять запросы (набор таких функций обычно называют термином API (application programming interface). Удобство веб-сервиса в том, что он доступен в интернете.

Как можно это использовать? Например, один сайт может обращаться к другому для получения информации о наличии товаров. Или программа 1С может обратиться к веб-сервису с таким же запросом. Или же 1С (или интернет-магазин) может обратиться к веб-сервису поставщику с целью автоматической отправки заказа поставщику.

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

URL для веб-службы (адрес хоста) следует уточнять у менеджеров

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

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

Запрос

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

Внимание! При включенной опции "Франчайзи: разрешить одинаковые логины у разных франчайзи" могут присутствовать клиенты с одинаковым email и номером мобильного телефона. В этом случае в качестве имени нужно использовать код клиента (id).

Параметр shipmentAddress становится обязательным для заполнения. Получить идентификатор адреса доставки можно с помощью операции basket/shipmentAddresses, если она не возвращает никаких значений, то shipmentAddress - является необязательным параметром. Если не используете доставку на адрес, а пользуетесь самовывозом, то необходимо передать shipmentAddress=0.

Каждая операция может иметь список дополнительных параметров, определяемых контекстом операции. Например, вызов операции "Поиск детали по номеру" может выглядеть следующим образом:

https://demo.public.api.abcp.ru/search/articles/?userlogin=username&userpsw=md5pass&number=01089&brand=Febi

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

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

Ответ

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

 1 [
 2 	{
 3 		"brand": "Hepu",
 4 		"articleCode": "P999",
 5 		"articleCodeFix": "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 		"articleCode": "01089",
16 		"articleCodeFix": "01089",
17 		"articleId": "37367",
18 		"description": "Антифриз 1.5 л синий",
19 		"availability": "1943",
20 		"deliveryPeriod": 3,
21 		"price": 233,
22 		"weight": "1.76"
23 	},
24 	{
25 		"brand": "Vaico Vemo",
26 		"articleCode": "V600020",
27 		"articleCodeFix": "V600020",
28 		"articleId": "4144961",
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 }

Типы ошибок

Код Описание
1 Ошибка синтаксиса запроса
2 Не найден обязательный параметр запроса
3 Неизвестная операция
4 Ошибка в параметре запроса
13 Неизвестная ошибка
102 Ошибка аутентификации пользователя
103 Доступ запрещен
104 Ошибка аутентификации сайта
201 Ошибка данных
202 Нарушение требования уникальности данных
301 Объект не найден
302 Ошибка кэша
303 Ресурс заблокирован

Методы API

API-методы можно логически, структурно и функционально разделить на несколько категорий:

API ABCP - Общий интерфейс
API ABCP - Административный интерфейс
API TS - Общий интерфейс
API TS - Административный интерфейс
API VINQU
API TecDoc
API Автосервис (CarCareModule)