API:Docs

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

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

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

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

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

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

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

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

Запрос

Запросы на получение и запись данных осуществляются с помощью HTTPS-методов GET и POST соответственно. В структуре сервиса имеется понятие операции. Операция указывается в качестве пути в URL. Параметры передаются как строка запроса HTTPS (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 в HTTPS-заголовке Content-Type необходимо передать медиа-тип данных запроса application/x-www-form-urlencoded и соответственно с данным типом сформировать тело HTTPS-запроса.

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

Ответ

В случае успешного исполнения операции, веб-служба вернет ответ с HTTPS-кодом 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 ]

Любой ответ с HTTPS-кодом 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-методы можно логически, структурно и функционально разделить на несколько категорий: