Описание API системы

Скачать инструкцию для работы с API одним файлом можно тут.

Базовые параметры

• Адрес API: http://zakaz.mxgroup.ru/mxapi/
• Сервис принимает запросы при помощи HTTP GET и POST запросов. Нужная функция передается в параметре "m".

Авторизация

Для начала использования API сайта необходимо авторизоваться, сделать это можно несколькими способами

1. Авторизация с использованием уникального номера сессии

Авторизация происходит при помощи следующего запроса:

/mxapi/?m=login&login=<ЛОГИН>&password=<ПАРОЛЬ>

Функция на это отправит следующий ответ при правильных логине и пароле:

1 <?xml version="1.0"?>
2 <doc>
3 <status>ok</status>
4 <session>НОМЕР_СЕССИИ</session>
5 </doc>

При неверных логине или пароле будет следующий ответ:

1 <?xml version="1.0"?>
2 <doc>
3 <error>Bad login or password</error>
4 </doc>
            

После этого НОМЕР_СЕССИИ необходимо будет передавать при каждом запросе в параметре session. Например так:

/mxapi/?session=sa_403e06b8a53487844e2a58bffbcfc0a9802&m=getstores

Для того, что бы сервер забыл данные сессии необходимо выполнить функцию "logout":

/mxapi/?session=sa_403e06b8a53487844e2a58bffbcfc0a9802&m=logout

на что сервер должен ответить:

1 <?xml version="1.0"?>
2 <doc>
3 <status>ok</status>
4 </doc>

2. Авторизация с передачей логина и пароля

Если необходимо выполнить единичный запрос и нет необходимости и желания создавать сессию, то можно логин и пароль передать в запросе при помощи параметров "login" и "password":

/mxapi/?m=<ДЕЙСТВИЕ>&login=<ЛОГИН>&password=<ПАРОЛЬ>

Если логин или пароль были указаны неверные, то сервер вернет следующий ответ:

1 <?xml version="1.0"?>
2 <doc>
3 <error>Bad login or password</error>
4 </doc>

Поддерживаемые функции

1. Получение доступных точек продаж: getstores

Данная функция не принимает никаких параметров и возвращает все доступные пользователю точки продаж, по всем доступным договорам.
Пример использования:
Запрос:

/mxapi/?session=<НОМЕР_СЕССИИ>&m=getstores

Ответ сервера:

1 <?xml version="1.0"?>
2 <doc>
3 <result>
4 <id>81</id>
5 <name>Владивосток</name>
6 </result>
7 <result>
8 <id>83</id>
9 <name>Новосибирск</name>
10 </result>
11 <result>
12 <id>82</id>
13 <name>Иркутск</name>
14 </result>
15 </doc>

Здесь:

• id – номер торговой точки из таблицы supplier.SupplierID
• name — Название торговой точки

2. Поиск, получение цены и доступного количества деталей: search

Данная функция принимает один обязательный параметр: "zapros" - артикул необходимого товара/оем номер/каталожный номер/номер 1с/етс, а так же необязательный параметр:

• store - идентификатор интересующей торговой точки, если не указан - показать по всем доступным торговым точкам, идентификатор торговой точки можно получить при помощи запроса getstore.
• version - версия алгортима поиска. может принимать значения 1 и 2. По умолчанию используется версия 2, которая отличается от версии 1 наличием поля "Код доставки" (deliveryroute)

Пример использования:
Запрос:

/mxapi/?session=<НОМЕР_СЕССИИ>&m=search&zapros=48815-60050&version=2

Ответ сервера:

1 <?xml version="1.0"?>
2 <doc>
3 <zapros>48815-60050</zapros>
4 <result>
5 <code>111-00012</code>
6 <name>Втулка переднего стабилизатора LAND CRUISER80 90-92 FR</name>
7 <price>180</price>
8 <discountprice>173</discountprice>
9 <id>81</id>
10 <count>7</count>
11 <storename>Владивосток</storename>
12 </result>
13 <result>
14 <code>111-00013</code>
15 <name>Втулка переднего стабилизатора LAND CRUISER80 90-92 FR усиленная</name>
16 <price>250</price>
17 <discountprice>230</discountprice>
18 <id>81</id>
19 <count>3</count>
20 <storename>Владивосток</storename>
21 </result>
22 <result>
23 <code>111-00012</code>
24 <name>Втулка переднего стабилизатора LAND CRUISER80 90-92 FR</name>
25 <price>180</price>
26 <discountprice>173</discountprice>
27 <id>82</id>
28 <count>10-100</count>
29 <storename>Иркутск</storename>
30 <deliveryroute>train:VVO000086-VOP</deliveryroute>
31 </result>
32 </doc>
            

Здесь:

• zapros — поисковый запрос
• name — название товара
• code – код товара 1с
• price — цена товара
• discountprice – цена товара со скидкой данного покупателя.
• result — массив данных для каждого результата поиска
• id — идентификатор точки продаж из базы ОЗ
• storename — название точки продаж
• count — количество запрошенного товара по данной точке продаж
• deliveryroute — код типа/машрута доставки

Пример с указанием точки продаж:
Запрос:

/mxapi/?session=<НОМЕР_СЕССИИ>&m=search&zapros=48815-60050&store=81

Ответ сервера:

1 <?xml version="1.0"?>
2 <doc>
3 <zapros>48815-60050</zapros>
4 <result>
5 <code>111-00012</code>
6 <name>Втулка переднего стабилизатора LAND CRUISER80 90-92 FR</name>
7 <price>180</price>
8 <discountprice>173</discountprice>
9 <count>7</count>
10 </result>
11 <result>
12 <code>111-00013</code>
13 <name>Втулка переднего стабилизатора LAND CRUISER80 90-92 FR усиленная</name>
14 <price>250</price>
15 <discountprice>230</discountprice>
16 <count>3</count>
17 </result>
18 </doc>

Здесь:

• zapros — запрашиваемый артикул
• name — название товара
• code – код товара 1с
• price — цена товара
• result — массив данных для каждого результата поиска
• discountprice – цена товара со скидкой данного покупателя.
• count — количество запрошенного товара на указанном складе

Если значение count=0, то вместо него вы получите

<count>Out of stock</count>

Поиск товара не дал результатов :

1 <?xml version="1.0"?>
2 <doc>
3 <error>Products not found</error>
4 </doc>

3. Получение аналогов : analog

Данная функция принимает один обязательный параметр: "zapros" - номер 1с, а так же необязательный параметр:

• store - идентификатор интересующей торговой точки, если не указан - показать по всем доступным торговым точкам, идентификатор торговой точки можно получить при помощи запроса getstore.
• version - версия алгортима поиска. может принимать значения 1 и 2. По умолчанию используется версия 2, которая отличается от версии 1 наличием поля "Код доставки" (deliveryroute)

Пример использования:
Запрос:

/mxapi/?session=<НОМЕР_СЕССИИ>&m=analog&zapros=333-33333&version=2

Ответ сервера:

1 <?xml version="1.0"?>
2 <doc>
3 <zapros>333-33333</zapros>
4 <result>
5 <code>111-11111</code>
6 <name>Фильтр масляный С110 JP</name>
7 <price>100</price>
8 <discountprice>90</discountprice>
10 <id>81</id>
11 <count>7</count>
12 <storename>Владивосток</storename>
14 </result>
15 <result>
16 <code>111-22222</code>
17 <name>Фильтр масляный Sakura FC-1101</name>
18 <price>50</price>
19 <discountprice>40</discountprice>
20 <id>81</id>
21 <count>3</count>
22 <storename>Владивосток</storename>
23 </result>
24 <result>
25 <code>111-11111</code>
26 <name>Фильтр масляный С110 JP</name>
27 <price>100</price>
28 <discountprice>90</discountprice>
29 <id>82</id>
30 <count>10-100</count>
31 <storename>Иркутск</storename>
32 <deliveryroute>train:VVO000086-VOP</deliveryroute>
33 </result>
34 </doc>
            

Здесь:

• zapros — поисковый запрос
• name — название товара
• code – код товара 1с
• price — цена товара
• discountprice – цена товара со скидкой данного покупателя.
• result — массив данных для каждого результата поиска
• id — идентификатор точки продаж из базы ОЗ
• storename — название точки продаж
• count — количество запрошенного товара по данной точке продаж

Пример запроса с параметром store:
Запрос:

/mxapi/?session=<НОМЕР_СЕССИИ>&m=analog&zapros=c110&store=81

Ответ сервера:

1 <?xml version="1.0"?>
2 <doc>
3 <zapros>c110</zapros>
4 <result>
5 <code>111-11111</code>
6 <name>Фильтр масляный С110 JP</name>
7 <price>100</price>
8 <discountprice>90</discountprice>
9 <count>7</count>
10 </result>
11 <result>
12 <code>111-22222</code>
13 <name>Фильтр масляный Sakura FC-1101</name>
14 <price>50</price>
15 <discountprice>40</discountprice>
16 <count>3</count>
17 </result>
18 </doc>

Здесь:

• zapros — поисковый запрос
• name — название товара
• code – код товара 1с
• price — цена товара
• discountprice – цена товара со скидкой данного покупателя
• result — массив данных для каждого результата поиска
• count — количество запрошенного товара по данной точке продаж

Если же был указан несуществующий товар, то сервер вернет ошибку:
Запрос:

/mxapi/?session=<НОМЕР_СЕССИИ>&m=analog&zapros=999-99999

Ответ сервера:

1 <?xml version="1.0"?>
2 <doc>
3 <error>Product not found</error>
4 </doc>

4. Добавление товара в корзину: cart

Данная функция принимает три обязательных параметра:

• code – код товара в 1с
• count - необходимое количество товара
• id - идентификатор точки продаж

Необязательные параметры:

• deliveryroute – Код типа/маршрута доставки

Пример использования:
Запрос:

/mxapi/?session=<НОМЕР_СЕССИИ>&m=cart&code=111-00013&count=2&id=81&deliveryroute=train:VVO000086-VOP

Ответ сервера:

1 <?xml version="1.0"?>
2 <doc>
3 <error>Product not found</error>
4 </doc>

Если же был указан несуществующий товар или остатка по текущей точке продаж нет, то сервер вернет ошибку:

1 <?xml version="1.0"?>
2 <doc>
3 <status>Product added</status>
4 </doc>

При использовании кода типа/маршрута доставки ошибка возникает в случае:

• передачи невалидного на текущий момент времени маршрута доставки
• если в корзине уже находится этот товар, и для него задан другой вид доставки

5. Получение содержимого корзины: getbasket

Данная функция не принимает никаких параметров и возвращает содержимое корзины.

Пример использования:

/mxapi/?session=<НОМЕР_СЕССИИ>&m=getbasket

Ответ сервера:

1 <?xml version="1.0"?>
2 <doc>
3 <basket>
4 <code>222-00013</code>
5 <name>Втулка переднего стабилизатора LAND CRUISER100 FR</name>
6 <count>1</count>
7 <discountprice>203</discountprice>
8 </basket>
9 <basket>
10 <code>111-00013</code>
11 <name>Втулка переднего стабилизатора LAND CRUISER80 FR</name>
12 <count>1</count>
13 <discountprice>173</discountprice>
14 </basket>
15 </doc>

Здесь:

• code - код товара 1с
• name — Название товара
• count - Количество данного товара в корзине
• discountprice – цена товара со скидкой данного покупателя.

Если же корзина пуста, то возвращается следующий ответ:

1 <?xml version="1.0"?>
2 <doc>
3 <status>Basket empty</status>
4 </doc>

6. Очищение корзины: cleanbasket

Данная функция не принимает обязательных параметров и очищает корзину от товаров, есть два необязательных параметра:

• code – удаляет из корзины товар с заданным кодом 1с
• count – изменяет кол-во товара в корзине, применяется только вместе с параметром code

Пример запроса, который очищает всю корзину:

mxapi/?session=<НОМЕР_СЕССИИ>&m=cleanbasket

Ответ сервера:

1 <?xml version="1.0"?>
2 <doc>
3 <status>Basket empty</status>
4 </doc>

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

/mxapi/?session=<НОМЕР_СЕССИИ>&m=cleanbasket&code=111-00013

Ответ сервера:

1 <?xml version="1.0"?>
2 <doc>
3 <code>111-00013</status>
4 <status>Removed</status>
5 </doc>

Пример запроса для изменения кол-ва определенного товара:

/mxapi/?session=<НОМЕР_СЕССИИ>&m=cleanbasket&code=111-00013&count=3

Ответ сервера:

1 <?xml version="1.0"?>
2 <doc>
3 <code>111-00013</status>
4 <status>Changed</status>
5 </doc>

Если же на момент изменения заказа какого-то товара не хватает на остатках, то сервер вернет следующую ошибку:

1 <?xml version="1.0"?>
2 <doc>
3 <code>111-11111</code>
4 <error>Out of stock</error>
5 <count>1</count>
6 </doc>

Здесь:

• code – код товара в 1с
• count – кол-во товара по остаткам возможное к заказу

Результат запроса на удаление товара отсутствующего в корзине:

1 <?xml version="1.0"?>
2 <doc>
3 <status>Product not found</status>
4 </doc>

7. Отправление заказа: sendorder

Данная функция принимает необязательный параметр:

• version — версия метода. может принимать значения 1 и 2. По умолчанию используется версия 1. Версия 2 отличается возможностью передать параметры delivery_address_id , user_code и comment
• pickup – признак того что заказ оформляется для самовывоза. Может принимать значение 0 или 1. Если самовывоз не запрошен, заказ оформляется со способом получения - курьерская доставка на адрес по умолчанию [см. методы getaddresses, setactiveaddress]
• delivery_address_id — id адреса доставки. Является признаком того что способ получения заказа - курьерская доставка на указанный адрес. Параметр может быть использован только в версии 2, и только в случае если не запрошен самомвывоз.
• user_code — код заказа, будет распечатан на документах реализации. Не более 32 символов.
• comment — текстовый комментарий к заказу. Не более 200 символов.

Метод проверяет еще раз, используя веб сервис 1с, остатки по всем заказанным позициям и оформляет заказ на все товары из корзины и очищает корзину:

Пример использования:

/mxapi/?session=<НОМЕР_СЕССИИ>&m=sendorder&pickup=1

/mxapi/?session=<НОМЕР_СЕССИИ>&m=sendorder&delivery_address_id=8dbac551-40cc-11ea-a2dd-b42e99537bf3&version=2&user_code=XYZ123&comment=Для%20Василия

Ответ сервера (1):

1 <?xml version="1.0"?>
2 <doc>
3 <status>Odrer sended</status>
4 <ordernum>555431</ordernum>
5 <pickup_store>
6 <id>93</id>
7 <name>Иркутск</name>
8 </pickup_store>
9 </doc>
            

Здесь:

• ordernum – номер заказа в системе онлайн заказ
• pickup_store – информация о точке продаж, где необходимо осуществить самовывоз

Если же на момент заказа какого-то товара не хватает на остатках, то сервер вернет следующую ошибку:

1 <?xml version="1.0"?>
2 <doc>
3 <result>
4 <code>111-11111</code>
5 <error>Out of stok</error>
6 <count>1</count>
7 </result>
8 <result>
9 <code>222-22222</code>
10 <error>Out of stok</error>
11 <count>1</count>
12 </result>
13 </doc>

Здесь:

• code – код товара в 1с
• count – кол-во товара по остаткам возможное к заказу

Если же на момент заказа корзина была пуста, то сервер вернет следующую ошибку:

1 <?xml version="1.0"?>
2 <doc>
3 <error>Basket is empty</error>
4 </doc>

8. Получение статуса заказа: getstatus

Данная функция принимает возвращает список всех заказов, статусы заказов, суммы заказов и даты заказов, есть один необязательный параметр номер заказа ordernum:

Пример использования:

/mxapi/?session=<НОМЕР_СЕССИИ>&m=getstatus

Ответ сервера:

1 <?xml version="1.0"?>
2 <doc>
3 <result>
4 <ordernum>555431</ordernum>
5 <status>Отгружен</status>
6 <summ>4310</summ>
7 <date>12.12.12</date>
8 </result>
9 <result>
10 <ordernum>555432</ordernum>
11 <status>Отменен</status>
12 <summ>44210</summ>
13 <date>16.10.12</date>
14 </result>
15 </doc>

Здесь:

• ordernum – номер заказа в системе онлайн заказ
• status – статус заказа (Создан, Сформирован, Отгружен, Отменен)
• sum – сумма заказа
• date – дата заказа

Пример использования с параметром ordernum:

/mxapi/?session=<НОМЕР_СЕССИИ>&m=getstatus&ordernum=555431

Ответ сервера:

1 <?xml version="1.0"?>
2 <doc>
3 <ordernum>555431</ordernum>
4 <status>Отгружен</status>
5 <summ>4310</summ>
6 <date>12.12.12</date>
7 </doc>

Если номер заказа не известен, то сервер вернет следующую ошибку:

1 <?xml version="1.0"?>
2 <doc>
3 <error>Unknown ordernum</error>
4 </doc>

9. Получение баланса: balance

Данная функция не принимает никаких параметров, возвращает значения баланса, просроченной дебиторской задолженности и кредит лимита.

Пример использования:

/mxapi/?session=<НОМЕР_СЕССИИ>&m=balance

Ответ сервера:

1 <?xml version="1.0"?>
2 <doc>
3 <result>
4 <balance>3000</balance>
5 <pdz>0</pdz>
6 <contract>Безналичный расчет</contract>
7 </result>
8 <result>
9 <balance>-10000</balance>
10 <pdz>10000</pdz>

Здесь:

• balance – текущий баланс по договору
• contract – наименование договора
• pdz – просроченная дебиторская задолженность по договору
• credit – кредит-лимит контрагента

10. Получение справочника адресов доставки: getaddresses

Данная функция не принимает никаких параметров, возвращает массив адресов доставки.

/mxapi/?session=<НОМЕР_СЕССИИ>&m=getaddresses

Ответ сервера:

1 <?xml version="1.0"?>
2 <doc>
3 <result>
4 <id>9474a224-c495-11e9-812d-ac1f6b4515c9</id>
5 <region_id>5a16c343-7876-11dc-a42c-000423c3432c</region_id>
6 <address>690018, Приморский край, Владивосток г, Вострецова ул, дом № 36, корпус Б</address>
7 <gps_x>131,919513</gps_x>
8 <gps_y>43,145025</gps_y>
9 <is_active>1</is_active>
10 </result>
11 <result>
12 <id>8dbac551-40cc-11ea-a2dd-b42e99537bf3</id>
...
</result>

Здесь:

• id – идентификатор
• region_id – идентификатор региона доставки
• address – строковое представление адреса
• gps_* – GPS координаты
• is_active – признак адреса по умолчанию

11. Установка адреса доставки по умолчанию: setactiveaddress

Данная функция принимает обязательный параметр:

• id – идентификатор адреса.

/mxapi/?session=<НОМЕР_СЕССИИ>&m=setactiveaddress&id=8dbac551-40cc-11ea-a2dd-b42e99537bf3

1 <?xml version="1.0"?>
2 <doc>
3 <status>Active address changed</status>
4 </doc>

Ответ сервера в случае невалидного адреса:

1 <?xml version="1.0" encoding="UTF-8"?>
2 <doc>
3 <status>error</status>
4 <error>Address not found</error>
5 </doc>

Управление форматом ответа сервера

По умолчанию сервер отвечает в формате XML но при помощи параметра "out" можно указать другой формат ответа:

• text - Текстовый формат
• xml - XML формат (По умолчанию)
• json - JSON формат

Примеры:

text:

Запрос:

/mxapi/?session=<НОМЕР_СЕССИИ>&m=search&zapros=48815-60050&out=text

Ответ сервера:

1 article: 48815-60050
2 result
3 code: 111-00012
4 name: Втулка переднего стабилизатора LAND CRUISER80 90-92 FR
5 price: 180
6 discountprice: 173
7 id: "81"
8 count: "7"
9 name: "Владивосток"
10 result_end
11 result
12 code: 111-00013
13 name: Втулка переднего стабилизатора LAND CRUISER80 90-92 FR усиленная
14 price: 250
15 discountprice: 230
16 id: "81"
17 count: "3"
18 name: "Владивосток"
19 result_end
20 result
21 code: 111-00012
22 name: Втулка переднего стабилизатора LAND CRUISER80 90-92 FR
23 price: 180
24 discountprice: 173
25 id: "82"
26 count: "10-100"
27 name: "Иркутск"
28 result_end

xml:

Запрос:

/mxapi/?session=<НОМЕР_СЕССИИ>&m=search&zapros=48815-60050&out=xml

Ответ сервера:

1 <?xml version="1.0"?>
2 <doc>
3 <zapros>48815-60050</zapros>
4 <result>
5 <code>111-00012</code>
6 <name>Втулка переднего стабилизатора LAND CRUISER80 90-92 FR</name>
7 <price>180</price>
8 <discountprice>173</discountprice>
9 <id>81</id>
10 <count>7</count>
11 <storename>Владивосток</storename>
12 </result>
13 <result>
14 <code>111-00013</code>
15 <name>Втулка переднего стабилизатора LAND CRUISER80 90-92 FR усиленная</name>
16 <price>250</price>
17 <discountprice>230</discountprice>
18 <id>81</id>
19 <count>3</count>
20 <storename>Владивосток</storename>
21 </result>
22 <result>
23 <code>111-00012</code>
24 <name>Втулка переднего стабилизатора LAND CRUISER80 90-92 FR</name>
25 <price>180</price>
26 <discountprice>173</discountprice>
27 <id>82</id>
28 <count>10-100</count>
29 <storename>Иркутск</storename>
30 </result>
31 </doc>

json:

Запрос:

/mxapi/?session=<НОМЕР_СЕССИИ>&m=search&zapros=48815-60050&out=json

Ответ сервера:

{
"zapros":"48815-60050",
["code":"111-00012", "name":"Втулка переднего стабилизатора LAND CRUISER80 90-92 FR", "price":180, "discountprice":173, "id":81, "count":7 , "storename":"Владивосток"],
["code":"111-00013", "name":"Втулка переднего стабилизатора LAND CRUISER80 90-92 FR усиленная", price":250, "discountprice":230, "id":81, "count":3 , "storename":"Владивосток"],
["code":"111-00012", "name":"Втулка переднего стабилизатора LAND CRUISER80 90-92 FR", "price":180, "discountprice":173, "id":82, "count":"10-100", "storename":"Иркутск"]
}

Описание возвращаемых ошибок

• Bad request. Неверный запрос - вызвана неподдерживаемая функция или не указаны какие-то из обязательных параметров.
• Bad login or password. Указаны неверные логин или пароль.
• Forbidden. Для Вашего пользователя отключена возможность использования API, свяжитесь с вашим менеджером.
• Not found. Запрошенный товар не найден
• Basket is empty. Попытка отправить заказ с пустой корзиной
• Unknown error. Неизвестная ошибка. Если Вы увидели такую ошибку, то сообщите нам, пожалуйста, с максимальными подробностями, как ее можно воспроизвести