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

Версия 17:04, 21 сентября 2020

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

Содержание

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

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

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

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

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

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

Запрос

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

Внимание! При включенной опции "Франчайзи: разрешить одинаковые логины у разных франчайзи" могут присутствовать клиенты с одинаковым 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	Ресурс заблокирован

@@ Строка 1: / Строка 1: @@
 {{Внимание|Данная статья предназначена для технических специалистов, обладающих, как минимум, начальными знаниями о принципах работы протокола HTTP. Консультации по вопросам относящимся к стандартам HTTP осуществляться не будут.}}
 __TOC__
-[[API.TecDoc]]
-[[API.ABCP.Admin]]
-[[API.TS.Client]]
-[[API.TS.Admin]]
-[[APIVINQU]]
 ==Общая информация==
@@ Строка 137: / Строка 127: @@
   |Ресурс заблокирован
   |}
-<!-- |-
- !directorFullName
+=== Методы API ===
- |ФИО директора -->
+* [[API.TecDoc|API TecDoc]]
+* [[API.ABCP.Client|API ABCP - Общий интерфейс]]
+* [[API.ABCP.Admin|API ABCP - Административный интерфейс]]
+* [[API.TS.Client|API TS - Общий интерфейс]]
+* [[API.TS.Admin|API TS - Административный интерфейс]]
+* [[APIVINQU|API VINQU]]
+<br />