Описание API
Введение
Доступ к API
Получение прайс-листа
Добавление заказа
Получение информации о заказе, его статусах
Введение
Наш портал предоставляет доступ к своим веб-сервисам посредством HTTP-запросов REST API.
Таким образом, доступ обеспечивается простым интерфейсом управления при отсутствии каких-либо дополнительных прослоек. Вы можете использовать любой подходящий клиент для осуществления запросов к сервисам. В примерах ниже, в качестве демонстрации, используется утилита командной строки cURL.
В процессе работы с API рекомендуется проверять ответы от сервиса, а не полученное содержимое, так как содержимое со времением может меняться и дополняться.
Текущая актуальная версия сервиса - v1.0 от 24.01.2019.
Доступ к API
Для работы с API нашего портала необходимо получить у Вашего менеджера доступ к сервису. Сервис позволяет с помощью простых GET-запросов получить список прайс-листов по артикулу и, если необходимо, бренду. Так же можно сделать заказ на основе полученных данных и проверить состояние заказов, получить его статусы.
Выполнять запросы к API могут только зарегистрированные на сайте пользователи, у которых включена эта возможность. Для любого успешного выполнения необходимы:
- URL, составленный согласно требованиям к нужному запросу;
- имя пользователя;
- пароль;
- дополнительные параметры, если требуется.
Пример:
curl -X GET "https://rvs-avto.ru/api/v1.0/function?login=имя_пользователя&password=пароль"
Список доступных на 24.01.2019 функций:
- getPrice - запрос прайс-листа по артикулу и, если необходимо, производителю
- setOrder - создание заказа
- getOrders - получение списка заказов
Ответ сервера всегда имеет вид:
<Данные> <Результат>OK</Результат> <КоличествоПозиций>N</КоличествоПозиций> <СписокПозиций> <Позиция> ..... </Позиция> </СписокПозиций> </Данные>
Поле «Результат» возвращает два значения: OK - при удачном выполнении и Error - при ошибке. Dj втором случае также идёт расшифровка ошибки. В поле <СписокПозиций> будет содержаться запрашиваемых набор данных. Количество получаемых позиций будет указано в поле <КоличествоПозиций>.
Ответ сервиса всегда ограничен не более 100 записями.
Получение прайс-листа
Пример запроса:
поиск только по артикулу
curl -X GET "https://rvs-avto.ru/api/v1.0/getPrice?login=имя_пользователя&password=пароль&code=2526"
поиск по артикулу и производителю
curl -X GET "https://rvs-avto.ru/api/v1.0/getPrice?login=имя_пользователя&password=пароль&code=2526&brand=ngk"
Дополнительные параметры (обязательные и не обязательные), кроме стандартных, служащих для авторизации на сервисе:
- code - артикул (код) детали
- brand - производитель (бренд)
Регистр написание артикула, производителя и порядок следования параметров не имеет значения
Ответ сервера будет таким:
... <Позиция> <Артикул>2526</Артикул> <Производитель>NGK</Производитель> <Наименование>Свеча зажигания</Наименование> <Наличие>250</Наличие> <Кратность>4</Кратность> <Цена>199.00</Цена> <СрокДоставки>0</СрокДоставки> <ПрайсЛист>1</ПрайсЛист> <Отказы>1</Отказы> </Позиция> ...
Срок доставки определяется максимальным количеством дней, за которые товар должен быть доставлен на наш склад, или клиенту. Количество записей ограничено - 20.
Добавление заказа
Пример запроса:
curl -X GET "https://rvs-avto.ru/api/v1.0/getPrice?login=имя_пользователя&password=пароль&code=2526&brand=NGK&price=199.00&qty=8&pricelist=1"
В этом запросе все параметры, помимо данных для авторизации, обязательные:
- code - артикул (код) детали
- brand - производитель (бренд)
- price - цена в формате 0.00
- qty - количество (должно быть не больше того, что есть в наличии и кратно указанной кратности)
- pricelist - номер прайс-листа
Регистр написание артикула, производителя и порядок следования параметров не имеет значения
Ответ сервера будет стандартным: при успешном добавлении заказа будет ответ в поле <Результат> OK и количество добавленных позиций, или ошибка Error с описанием ошибки. Цена в запросе необходима для подтверждения факта согласия покупки и во избежании её изменения на момент покупки. Наименование производителя на кириллице необходимо передавать согласно правилам формирования URL, т.е. в кодированном виде с заменой знаком процента (%), за которым следует два шестнадцатеричных числа, а пробелы закодированы как знак сложения (+), согласно стандарту RFC 3986.
Получение информации о заказе, его статусах
Для получения информации о заказах необзходимо выполнить запрос:
curl -X GET "https://rvs-avto.ru/api/v1.0/getOrders?login=имя_пользователя&password=пароль&order=123456&date=31.12.2018&datefrom=31.12.2018&dateto=01.01.2019"
В этом запросе все параметры, помимо данных для авторизации, необязательные:
- order - номер заказа
- date - дата заказа
- datefrom - начальная дата для выборки заказов
- dateto - конечная дата для выборки заказов
Логично, что при указании номера заказа не имеет смысла указывать даты. Так же не имеет смысла указывать диапазон дат, при указании даты заказа. При задании начальной даты можно не указывать конечную дату, подразумевая диапазон дат по текущую дату. Формат дат необходимо указывать в виде ДД.ММ.ГГГГ.
Ответ сервера будет таким:
... <Позиция> <Заказ>123456</Заказ> <Дата>31.12.2018 11:01:59</Дата> <Артикул>2526</Артикул> <Производитель>NGK</Производитель> <Наименование>Свеча зажигания</Наименование> <Цена>199.00</Цена> <Количество>8</Количество> <КоличествоФактически>4</КоличествоФактически> <ПрайсЛист>1</ПрайсЛист> <СрокДоставки>09.01.2019</СрокДоставки> <Статус>на складе</Статус> </Позиция> ...
Если статус в поле <Статус> будет «подтвержден поставщиком» и значение поля <КоличествоФактически> меньше значения поля <Количество> - это означает, что в наличии осталось товара меньше, чем было заказано. Если товар продан, то значение поля <КоличествоФактически> будет равно 0 и статус в поле <Статус> будет «отказ».
Список стаусов заказов:
- принят
- обрабатывается
- отправлен поставщику
- подтвержден поставщиком
- удален администратором
- удален менеджером
- ожидается поставка
- на складе
- в резерве
- отгружен
- готов к выдаче
- выдан/закрыт
- отказ
