Документация к API v.1
для проценки и заказа товаров

Эта версия отключена и больше не будет работать!
Текущая версия: v.2. Изменения в сравнении с API v1.

Введение

Программный интерфейс к сервисам компании АвтоЕвро (далее — API) дает возможность разработчикам создавать приложения для работы с данными компании. Например, с помощью этого сервиса можно совершать поиск товаров, предлагаемых компанией, оформлять заказы, делать запросы на отмену резерва, получать сведения о балансе.

Данный сервис предназначен только для клиентов компании, являющихся юридическими лицами. Для получения доступа к этому интерфейсу необходимо обратиться к Вашему менеджеру в компании АвтоЕвро. Работая с этим сервисом, Вы (и Ваша компания) автоматически присоединяетесь и выражете безусловное согласие с условиями Договора-оферты.

API построено на REST-принципах с использованием HTTP и JSON для обмена данными. Сервис работает с тремя типами запросов: GET (только получение ресурсов/данных), POST (получение и отправка ресурсов/данных).

Данный сервис связан с онлайн-магазином компании АвтоЕвро shop.autoeuro.ru. Т.е. все производимые через API действия немедленно отражаются в интерфейсе магазина и наоборот.

Общее описание формата запроса

Пример: https://api.autoeuro.ru/api / v-1.0 / shop / items / 123 / ?code=0986424797&maker=BOSCH

https://api.autoeuro.ru/api Корневой URL для всех API запросов
версия Номер версии API, например:
current — последняя текущая версия
1 — точное указание мажорного номера версии
Рекомендуется использовать последний вариант, см. раздел Версии
подраздел Группа запросов, к которой обращаетесь, например: /shop
действие Название запроса, см. документацию ниже
формат ответа Формат ответа в котором будет получен ответ. В настоящий момент — только json
ключ API ключ, указан в карточке клиента
?code=0986424797&maker=BOSCH Параметры GET-запроса, url-encoded
Для POST-запросов параметры передаются в теле POST

Для отладки запросов рекомендуется использовать Postman или Advanced REST Client.
Количество запросов лимитировано, используйте кэширование с Вашей стороны.

Внимание!
При обмене данными c API всегда используйте кодировку UTF-8!

Общее описание формата ответа

Данные возвращаются в JSON-формате. Если ресурс возвращает данные, то они возвращаются в ветке DATA виде JSON массива или записи и в заголовке ответа передается код ответа 200. В случае ошибки в заголовке возращается соответствующий 400-й или 500-й код и описание ошибки.

JSON ответ состоит из:

  1. присутствующего всего служебной записи META
  2. если запрос был выполнен, то одного или нескольких массивов с данными внутри ветки DATA,
  3. а если не выполнен, то с веткой ERROR

Перечень полей массива DATA и их описание смотрите в соответствующих разделах данной документации.

Пример ответа
{
    "META": {
        "resource":"resource_name",
        "version":"1.0",
        "section": "shop",
        "resource":"resource_name",
        "parameters":   {
            "param_1": "value-1",
            "param_2": 123,
        },
        "date": "2019-12-01 08:04:15",
        "user_id": "e335d40b-3785-4ca7-946c-89a195c1ee9e"

    },
    "DATA": [
        {
            "value1": "ABC",
            "value2": 123.456
        },
        {
            "value1": "DEF",
            "value2": 987.654
        }
    ]
}
Пример ошибки
{
    "META": {
        "resource":"resource_name",
        "version":"1.0",
        "section": "shop",
        "resource":"resource_name",
        "parameters":   {
            "param_1": "value-1",
            "param_2": 123,
        },
        "date": "2019-12-01 08:04:15",
        "user_id": "e335d40b-3785-4ca7-946c-89a195c1ee9e"

    },
    "ERROR": {
        "code": 403,
        "message": "Действие не разрешено"
    }
}

Схема работы и основной функционал

Схема работы API Авто-Евро
  1. На вход процесса подаются код/артикул и название производителя (должно быть именно таким, как указано в ресурсе brands).
  2. В ответ возвращается массив предложений, каждое из которых содержит уникальный ключ order_key.
  3. Этот ключ и количество выбранного товара передается в корзину. Корзину можно использовать с сайта shop.autoeuro.ru или собственную вашего приложения.
    • В случае использования корзины с сайта вы передаете туда товары по одному, в ответ получается или сообщение об удачном добавлении, или сообщение об ошибке с расшифровкой.
    • При запросе списка корзины возвращается список товаров с перечнем для каждого товара ключей возможных способов получения.
  4. Заказ можно оформить двумя способами: из корзины сайта shop.autoeuro.ru или корзины вашего приложения.
    1. Для корзины сайта shop.autoeuro.ru передается массив ключей товаров корзины, флаг частичное/полная отгрузка, способ получения и подразделение на которое будет выставлен счет.
    2. В случае использования вашей корзины передается массив ключей товаров из поиска, флаг частичное/полная отгрузка, способ получения и подразделение на которое будет выставлен счет.
  5. В ответ возвращается или сообщение о принятии заказа в обработку, или сообщение об ошибке с описанием. После устранения причины ошибки необходимо повторить попытку отправить заказ.

Помимо этих методов в API есть справочные методы: список брендов (как пишутся), список вариантов получения для клиента, список подразделений, баланс и финансовая информация

Описание запросов (версия 1.0)

/brands/

Бренды/производители

Получение списка производителей

При поиске по коду и названию производителя название производителя должно указываться именно так, как оно указано в этой таблице. Данные меняются редко, поэтому результат можно кэшировать в вашем приложении на длительный срок.

HTTP метод запроса: GET/POST

Входные данные:

Не требуется

Выходные данные:

В ветке DATA возвращается массив из элементов maker.
  1. maker [string] — Название бренда в системе АвтоЕвро

Примеры запросов:

Для доступа к построителю запросов и просмотра результатов необходимо авторизироваться

/deliveries/

Варианты получения

Получение возможных вариантов получения товара для клиента

HTTP метод запроса: GET/POST

Входные данные:

Не требуется

Выходные данные:

Параметр delivery_key необходимо передать при оформлении в заказ и он должен совпадать с одним из ключей delivery_keys у каждого отправляемого в заказ товара. Другими словами, все товары в заказе должны иметь одинаковый вариант получения.
  1. delivery_key [string] — Идентификатор способа получения
  2. delivery_method [string] — Название метода доставки
  3. delivery_method_id [string] — Идентификатор метода получения
  4. delivery_name [string] — Полное название способа доставки
  5. delivery_note [text] — Примечания к варианту получения
  6. from_warehouse_name [string] — Название склада с которого пойдет отгрузка
  7. from_warehouse_id [string] — Идентификатор склада с которого пойдет отгрузка

Примеры запросов:

Для доступа к построителю запросов и просмотра результатов необходимо авторизироваться

/subdivisions/

Список подразделений

Получение списка подразделений клиента

Ключ подразделения необходимо передать при оформлении заказа

HTTP метод запроса: GET/POST

Входные данные:

Не требуется

Выходные данные:

  1. subdivision_key [string] — Идентификатор подразделения
  2. subdivision_name [string] — Название подразделения

Примеры запросов:

Для доступа к построителю запросов и просмотра результатов необходимо авторизироваться

/balance/

Баланс клиента

Получение детальной информации о состоянии баланса личного счета

HTTP метод запроса: GET/POST

Входные данные:

Не требуется

Выходные данные:

  1. balance [float] — Текущий баланс
  2. credit [float] — Сумма кредита
  3. ordered_total [float] — Закуплено всего
  4. ordered [float] — Закуплено
  5. reserved [float] — Зарезервировано
  6. limit [float] — Лимит покупок
  7. pay_tomorrow [float] — Сумма к оплате завтра
  8. shipping_from [float] — Минимальная сумма для оформления доставки
  9. reclamation_new [int] — Рекламации/возвраты
  10. cash_back [float] — Накопленная сумма кэшбека

Примеры запросов:

Для доступа к построителю запросов и просмотра результатов необходимо авторизироваться

/stock_items/

Поиск товаров

Поиск товаров по коду (и бренду). Доступные для заказа товары и аналоги (кроссы)

Поиск по артикулу или по паре производитель-артикул. Возвращает массив предложений с ценами, сроками доставки и дополнительными свойствами. Есть ограничения по количеству запросов в сутки

HTTP метод запроса: GET/POST

Входные данные:

Единственное обязательное поле "code". Если указано поле "brand" и в этом поле название производителя/бренда написано с ошибкой, результат будет пустой.
  1. code [string] обязательный параметр — Артикул по каталогу производителя
  2. brand [string] — Наименование бренда/производителя
  3. with_crosses [bit] — Искать с "кроссами" или только запрошенный номер. Значение по умолчанию: 1

Выходные данные:

Если что-то было найдено, то внутри ветки DATA будет один из 3-х вариантов:
  1. ветка VARIANTS с массивом возможных брендов/производителей для искомого кода если этот код был найден более чем у одного производителя и не был указано поле brand
  2. ветка CODES с массивом предложений для искомого кода и бренда/производителя
  3. ветка CROSSES с массивом предложений для искомого кода и бренда/производителя если был указан флаг with_crosses
Если по указанным параметрам ничего не было найдено, то массив DATA возвращается пустой.
  1. order_key [string] — Ключ предложения который надо передать в корзину или заказ
  2. price [float] — Цена клиента за единицу товара в рублях
  3. name [string] — Наименование товара
  4. maker [string] — Наименование бренда/производителя
  5. code [string] — Артикул по каталогу производителя
  6. packing [int] — Кратность (или упаковка), 0 - нет кратности (т.е. можно заказывать поштучно)
  7. amount [int] — Доступное количество для заказа
  8. unit [string] — Единица измерения
  9. order_term [string] — Срок заказа (рабочих дней до прихода на склад в Москве)
  10. proposal [string] — Тип склада. Возможные варианты: «АвтоЕвро» и «Партнер»
  11. from_warehouse_id [string] — ID склада с которого пойдет поставка. При заказе должен совпадать с from_warehouse_id из выбранного способа получения
  12. order_time [string] — Диапазон времени до склада (min-max рабочих дней до прихода на центральный склад)
  13. reject_stat [float] — Вероятность отказа в заказе. 0 - на складе. 0,01 - 1% отказов и так далее до 1.
  14. dealer [bit] — Признак официального дилера. (1 — означает официальный дилер, 0 — нет или не подтвержден)

Примеры запросов:

Для доступа к построителю запросов и просмотра результатов необходимо авторизироваться

/basket_put/

Добавление в корзину

HTTP метод запроса: POST

Входные данные:

  1. order_key [string] обязательный параметр — Ключ предложения полученный из stock_items
  2. quantity [] обязательный параметр — Количество единиц товара. Должно быть кратно packing
  3. item_note [] — Комментарий к добавляемому товару

Выходные данные:

В случае удачного добавления в корзину возвращает добавленную запись
  1. maker [string] — Наименование бренда/производителя
  2. code [string] — Артикул по каталогу производителя
  3. name [string] — Наименование товара
  4. order_time [string] — Срок заказа (рабочих дней до прихода на склад в Москве), пустое значение соответствует наличию на складе АвтоЕвро
  5. packing [int] — Кратность (или упаковка), 0 - нет кратности (т.е. можно заказывать поштучно)
  6. price [float] — Цена клиента за единицу товара в рублях
  7. ordered [int] — Количество заказанных товаров
  8. unit [string] — Единица измерения
  9. comment [string] — Комментарий к товару
  10. basket_item_key [string] — Идентификатор товара в корзине
  11. deliveries [array] — Массив вариантов получения для данного товара (см. Варианты получения)

Примеры запросов:

Для доступа к построителю запросов и просмотра результатов необходимо авторизироваться

/basket_items/

Содержимое корзины

Получение списка товаров в корзине

HTTP метод запроса: GET/POST

Входные данные:

Не требуется

Выходные данные:

  1. maker [string] — Наименование бренда/производителя
  2. code [string] — Артикул по каталогу производителя
  3. name [string] — Наименование товара
  4. order_time [string] — Срок заказа (рабочих дней до прихода на склад в Москве), пустое значение соответствует наличию на складе АвтоЕвро
  5. packing [int] — Кратность (или упаковка), 0 - нет кратности (т.е. можно заказывать поштучно)
  6. price [float] — Цена клиента за единицу товара в рублях
  7. ordered [int] — Количество заказанных товаров
  8. unit [string] — Единица измерения
  9. comment [string] — Комментарий к товару
  10. basket_item_key [string] — Идентификатор товара в корзине
  11. deliveries [array] — Массив вариантов получения для данного товара (см. Варианты получения)
  12. from_warehouse_id [string] — Идентификаторы склада с которого будет отгружен товар

Примеры запросов:

Для доступа к построителю запросов и просмотра результатов необходимо авторизироваться

/basket_del/

Удаление из корзины

HTTP метод запроса: POST

Входные данные:

  1. basket_item_key [string] обязательный параметр — Идентификатор товара в корзине

Выходные данные:

  1. deleted_count [int] — Количество удаленных товаров
  2. basket_count [int] — Количество элементов в корзине после удаления

Примеры запросов:

Для доступа к построителю запросов и просмотра результатов необходимо авторизироваться

/order_basket/

Оформление заказа из корзины

Оформление заказа из выбранных товаров в корзине на сайте shop.autoeuro.ru

HTTP метод запроса: POST

Входные данные:

Идентификатор delivery_id должен присутствовать у товара в массиве deliveries
  1. delivery_key [string] обязательный параметр — Идентификатор способа доставки (см. Варианты получения)
  2. subdivision_key [string] обязательный параметр — Идентификатор подразделения на которое будет выставлен счет (см. Список подразделений)
  3. wait_all_goods [bit] — Доставить весь заказ сразу или по мере поступления на склад. По умолчанию : 1 (всё сразу)
  4. comment [text] — Комментарий к заказу
  5. basket_item_keys [array] обязательный параметр — Массив идентификаторов товара в корзине [basket_item_key]

Выходные данные:

В случае прохождения всех проверок возвращается номер заказа. Если заказ по каким-то причинам не прошел, смотрите описание ошибки
  1. order_number [int] — Номер заказа

Примеры запросов:

Для доступа к построителю запросов и просмотра результатов необходимо авторизироваться

/order_stock/

Оформление заказа из поиска

Оформление заказа по ключам из результатов поиска (с использованием корзины на вашей стороне)

HTTP метод запроса: GET/POST

Входные данные:

  1. delivery_key [string] — Идентификатор способа доставки (см. Варианты получения)
  2. subdivision_key [string] — Идентификатор подразделения на которое будет выставлен счет (см. Список подразделений)
  3. wait_all_goods [bit] — Доставить весь заказ сразу или по мере поступления на склад. По умолчанию : 1 (всё сразу)
  4. comment [text] — Комментарий к заказу
  5. stock_items [array] — Массив заказываемых товаров. В каждом товаре должны обязательно указываться идентификатор order_key с количеством quantity. Пример: [{"order_key": "…", , "quantity": "1"}, {"order_key":"…", "quantity": "1"},…]

Выходные данные:

В случае если была не пройдена базовая проверка перед обработкой, то отдается ошибка с описанием, что не так. В случае обработки заказа в массиве DATA возвращаются два массив: SUCCESS с перечнем товаров принятых к работе и ERRORS c перечнем отказов и описанием причины отказа для каждого товара. Внутри элементов массивов два значения идентификатор товара и сообщение.
  1. order_key [string] — Исходный идентификатор order_key из поиска
  2. result_message [string] — Сообщение о результатах обработки

Примеры запросов:

Для доступа к построителю запросов и просмотра результатов необходимо авторизироваться

/ordered_items/

Заказанные товары

Список заказанных товаров в процессе обработки (еще не отгруженных)

HTTP метод запроса: GET/POST

Входные данные:

Не требуется

Выходные данные:

  1. warehouse [string] — Название склада с которого должна быть отгрузка
  2. maker [string] — Наименование бренда/производителя
  3. code [string] — Артикул по каталогу производителя
  4. name [string] — Наименование товара
  5. amount [int] — Количество единиц товара
  6. price [float] — Цена за единицу товара, руб.
  7. unit [string] — Единица измерения
  8. tovar_state [string] — Статус товара
  9. order_date [datetime] — Дата заказа
  10. order_number [string] — Номер заказа
  11. comment [string] — Комментарий

Примеры запросов:

Для доступа к построителю запросов и просмотра результатов необходимо авторизироваться

/archived_items/

Доставленные товары

Получение статуса завершенных заказов

HTTP метод запроса: GET/POST

Входные данные:

  1. date_from [date:10] — дата начала периода (в формате YYYY-MM-DD)
  2. date_to [date:10] — дата окончания периода (в формате YYYY-MM-DD)

Выходные данные:

  1. warehouse [string] — Название склада с которого была отгрузка
  2. maker [string] — Наименование бренда/производителя
  3. code [string] — Артикул по каталогу производителя
  4. name [string] — Наименование товара
  5. amount [int] — Количество единиц товара
  6. unit [string] — Единица измерения
  7. price [float] — Цена за единицу товара, руб.
  8. tovar_state [string] — Статус товара
  9. order_date [datetime] — Дата заказа (в формате yyyy-mm-dd hh:ii:ss)
  10. order_number [string] — Номер заказа
  11. comment [string] — Комментарий

Примеры запросов:

Для доступа к построителю запросов и просмотра результатов необходимо авторизироваться

/canceled_items/

Отказы

Получение списка отказанных/отменных товаров

HTTP метод запроса: GET/POST

Входные данные:

  1. date_from [date:10] — дата начала периода (в формате YYYY-MM-DD)
  2. date_to [date:10] — дата окончания периода (в формате YYYY-MM-DD)

Выходные данные:

  1. warehouse [string] — Название склада с которого была отгрузка
  2. maker [string] — Наименование бренда/производителя
  3. code [string] — Артикул по каталогу производителя
  4. name [string] — Наименование товара
  5. amount [int] — Количество единиц товара
  6. unit [string] — Единица измерения
  7. price [float] — Цена за единицу товара, руб.
  8. tovar_state [string] — Статус товара
  9. order_date [datetime] — Дата заказа (в формате yyyy-mm-dd hh:ii:ss)
  10. order_number [string] — Номер заказа
  11. comment [string] — Комментарий

Примеры запросов:

Для доступа к построителю запросов и просмотра результатов необходимо авторизироваться

Версии

Версионность API формируется в соответствии с правилами семантического версионирования, т.е. по принципу МАЖОРНАЯ.МИНОРНАЯ.ПАТЧ. Минорные версии и патчи не меняют формат и логику входных и выходных данных, а только исправляют ошибки или дополняют их. С выходом новой МАЖОРНОЙ версии предыдущая версия будет поддерживаться ограниченное количество времени и спустя оговоренный промежуток времени будет отключена. Все активные пользователи API будут оповещены об этом изменении загодя.

2019.11.02
1.0.0 Первичный релиз
2019.11.24
1.0.1 ПАТЧ. Исправлены нулевые суммы в заказах на shop.autoeuro.ru для сделанных через API. Добавление запрета на оформление заказа через API со склада на Рябиновой. Заказы со склада на Рябиновой можно оформить только через сайт shop.autoeuro.ru
2020.01.09
1.0.2 ПАТЧ. Исправление ошибки с кодировкой результатов в корзине. На работу клиентов API не влияло.
2020.01.12
1.0.3 ПАТЧ. Добавлено автоудаление благополучно оформленных товаров из корзины.
2020.01.21
1.0.4 ПАТЧ. По просьбе клиента в deliveries добавлен идентификатор delivery_method_id.
2020.08.21
1.0.5 ПАТЧ. Отдается правильный ответ при превышении лимита поисковых запросов в сутки
2020.08.21
1.0.5 ПАТЧ. Отдается правильный ответ при превышении лимита поисковых запросов в сутки
2020.08.21
1.0.6 ПАТЧ. В вывод метода stock_items добавлен два параметра:
  1. order_time - диапазон дней до склада (min-max рабочих дней до прихода на центральный склад)
  2. reject_stat — вероятность отказа от 0 до 1

Лимиты и рекомендации

Количество поисковых запросов к сервису имеет ограничение. По умолчанию новым клиентам выделяется лимит в 1500 поисковых запросов в сутки. В индивидуальном порядке лимит может быть увеличен пропорционально объему закупок (для этого обращайтесь к Вашему менеджеру).

Рекомендуемое решение для web-магазинов и web-сервисов с большим количеством посетителей
  • Для проценки Вашими пользователями используйте регулярно обновляемые прайс-листы (формат настраивается в личном кабинете на shop.autoeuro.ru, а периодичность — через Вашего менеджера).
  • API используйте для уточнения и подтверждения наличия, сроков и цены уже выбранного товара и его заказа.

При большом коичестве запросов такое решение будет работать на порядки быстрее, чем API, — не нужно будет делать множество накладных операций: авторизация, поиск, создание JSON, передача по сети ответа размером до 10-20Mb, разбор и фильтрация ответа. Ваш сайт будет просто брать данные из локальной таблицы, которая периодически обновляется по расписанию в фоновом режиме. Таким образом, Вы никогда не столкнетесь с исчерпанным лимитом.

Поддержка

Если есть вопросы или пожелания пишите на api@autoeuro.ru