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

Введение

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

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

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

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

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

Схема работы API Авто-Евро
  1. Для поиска необходимо указать три обязательных параметра:
    • Код/артикул.
    • Название бренда (должно быть именно таким, как указано в ресурсе get_brands). Написание бренда можно уточнить через процедуру search_brand.
    • ключ получения (см. процедуру get_deliveries).
    Так же есть два необязательных уточняющих поиск параметра:
    • С аналогами или строго искомый артикул.
    • Складское наличие или с партнерскими предложениями.
  2. В ответ возвращается массив предложений, каждое из которых содержит уникальный ключ offer_key.
  3. Этот ключ и количество Вы сохраняете со своей стороны (в "корзину" вашего предложения) вместе с другими нужными Вам параметрами. В APIv2.0 мы отказались от интеграции с корзиной сайта shop.autoeuro.ru по ряду причин.
  4. Далее оформляется заказ. Для этого Вам необходимо передать в процедуру create_order
    • массив ключей товаров (offer_key) из поиска с указанием количества
    • способ получения
    • плательщик/подразделение
    • флаг частичная/полная отгрузка
  5. В ответ возвращается или сообщение о принятии заказа в обработку c номером заказа (order_id), или сообщение об ошибке с описанием. После устранения причины ошибки необходимо повторить попытку отправить заказ.
  6. Текущее состояние заказов в работе или избранных заказов можно получить с использованием процедуры get_orders. Эта процедура работает в двух режимах — быстрая проверка статуса и по списку order_id или поиск по параметрам.

Авторизация

Для работы с этим сервисом клиентам компании необходимо получить т.н. API-ключ клиента в разделе настройки в личном кабинете на сайте shop.autoeuro.ru. Анонимного доступа к сервису нет. Авторизироваться на сервисе можно тремя способами:

  1. Через указание поля "key" с ключом в HEADER запроса.
  2. Через путь в URL последним фрагментом.
    Например: https://api.autoeuro.ru/api/v2/json/search/API_KEY/?brand=DENSO&code=ik16
  3. Через дополнительный параметр запроса.
    Например: https://api.autoeuro.ru/api/v2/json/search/?key=API_KEY&brand=DENSO&code=ik16

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

Сервис работает с двумя методами — GET и POST.
Параметры запроса передаются двумя способами:

  1. для GET или POST — через параметры URL
    Например: https://api.autoeuro.ru/api/v2/json/search/API_KEY/? brand=DENSO & code=ik16
  2. только для POST — в теле POST-запроса (внутри BODY или в виде FORM-DATA)
    Например: https://api.autoeuro.ru/api/v2/json/search + авторизация в HEADER и параметры в BODY

Формат данных с которыми Вы хотите работать (json, xml или serial) указывается в третьем фрагменте URL запроса.

Пример:

https://api.autoeuro.ru/api / v2 / json / search / 123 / ?code=0986424797&brand=BOSCH

Где:

https://api.autoeuro.ru/api Корневой URL для всех API запросов
версия v2 — для использования текущей версии
формат данных Формат данных в котором будет получен ответ.
Доступные варианты json, xml и ser - для сериализованных массивов PHP
Если используется POST запрос, то входные параметры внутри BODY ожидаются в этом же формате.
действие Название запроса, см. документацию ниже
ключ Необязательный API ключ (можно авторизоваться другими способами, см. раздел Авторизация)
?code=0986424797&brand=BOSCH Параметры GET-запроса, url-encoded
В случае POST-запросов параметры запроса можно передавать в BODY в формате json/xml/ser

Вы всегда можете посмотреть лог Ваших запросов на странице «Информация» https://api.autoeuro.ru/client/log (справа в шапке). Для этого Вам надо авторизоваться. История запросов хранится неделю.

Обработка запроса

Работа сервиса происходит по следующему алгоритму:

  1. Базовые проверки корректности запроса
  2. Авторизация
  3. Разбор и валидация параметров запроса
  4. Создание и передача запросов в ERP
  5. Получение и форматирование ответа от ERP
  6. Возврат ответа

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

Данные возвращаются в том формате, который вы указали в запросе. В случае ошибки ответ приходит с соответствующим кодом HTTP, описанием ошибки и указанием что нужно сделать для ее устранения. В случае благополучной обработки ответ приходит с кодом 200.

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

Массив ответа состоит из:

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

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

Пример ответа (в JSON)
{
    "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
        }
    ]
}
Пример ошибки (в JSON)
{
    "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 v1

  1. Переработана процедура получения статусов/деталей заказа — добавлена возможность получения статусов/деталей заказа. Теперь можно как получить статус по конкретному заказу, так и осуществить поиск по истории заказов
  2. Введен обязательный параметр delivery_key для поиска
  3. Поисковая выдача показывает расчетное время получения товара — так, как сейчас сделано на shop.autoeuro.ru
  4. К типам форматов на входе и выходе добавлены XML и SERIAL (сериализованный массив PHP)
  5. Передача данных методом POST возможна не только в виде FORM-DATA, но и внутри BODY
  6. Авторизация может производится несколькими способами
  7. Внедрена сериализация c кэшированием запросов. Повторные запросы становятся в очередь (квантование 0.01с) и результаты повторных отдаются из кэша (TTL — 1мин.)
  8. Унифицированы названия процедур

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

Если Вы авторизовались на этом сайте с данными присланными Вам при подключении, то помимо документации Вам будет доступна "песочница" с примерами к каждому вызову.

GET/POST: /get_balance/

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

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

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

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

Не требуется

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

balance [float] Текущий баланс клиента (для всех плательщиков).
Если меньше 0 — есть долг и задействован кредит.
Если больше 0 — у клиента есть аванс.
credit [float] Сумма предоставленного кредита
ordered [float] Сумма заказанного товара не готового к отгрузке ("в работе")
reserved [float] Сумма заказанного товара готового к отгрузке
limit [float] Сумма доступная для заказов.
limit=balance credit
pay_tomorrow [float] Сумма к оплате завтра.
Если не будет оплачена, то произойдет блокировка работы клиента за долги.
shipping_from [float] Минимальная сумма для оформления доставки
active [bit] Статус клиента:
1 — клиент активен
0 — клиент заблокирован

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

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

GET/POST: /get_deliveries/

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

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

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

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

Не требуется

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

Хотя варианты получения для клиента не статичны, их можно кэшировать (рекомендуем на сутки). Рекомендуем добавить возможность принудительно обновить кэш на случай, если клиенту добавили/изменили новый адрес доставки и он хочет увидеть изменения прямо сейчас.
delivery_key [string] Ключ варианта получения.
Необходим при поиске и заказе
name [string] Человекопонятное название варианта получения.
time_shift_msk [float] Сдвиг времени от московского.

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

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

GET/POST: /get_warehouses/

Список складов

Список складов, доступных клиенту для способа доставки

ВНИМАНИЕ! Эта процедура оставлена для облегчения перехода с предыдущего API. Мы рекомендуем отойти от использования в логике вашего приложения понятия «склад» и опираться на «время получения».

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

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

Если передан ключ delivery_key, то возвращаются склады только для указанного метода получения, иначе выводятся все доступные клиенту склады
delivery_key [string] Ключ способа доставки

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

warehouse_id [string] id склада (для совместимости с существующими интеграциями). В будущих версиях API это поле будет удалёно
warehouse_key [string] Ключ склада
warehouse_name [string] Название склада

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

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

GET/POST: /get_payers/

Список плательщиков

Получение списка плательщиков (подразделений) для клиента

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

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

Не требуется

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

payer_name [string] Название плательщика
payer_key [string] Ключ плательщика.
Необходим при вызове /order

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

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

GET/POST: /get_brands/

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

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

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

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

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

Не требуется

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

В ветке DATA возвращается массив названий брендов.

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

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

GET/POST: /search_brands/

Поиск бренда по коду

Получение списка брендов у которых есть искомый артикул

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

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

code [string:200] Искомый артикул/код товара

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

Нужную пару brand/code необходимо передать в процедуру search
brand [string] Название бренда/производителя
code [string] Нормализованный артикул
name [string] Название/описание товара

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

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

GET/POST: /search_items/

Поиск товара

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

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

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

У процедуры три обязательных поля: "brand" и "code" (указатели на искомый товар) и "delivery_key" (без него невозможно рассчитать время получения). Обратите внимание, что если указано поле "brand" и в этом поле название производителя/бренда написано с ошибкой, результат будет пустой. Сверяйте название бренда с /get_brands.
brand [varchar:255] Наименование бренда/производителя (см. /specify)
Внимание, т.к. это поле может содержать специальные параметры при передача методом GET используйте URL-кодирование!
code [varchar:255] Артикул по каталогу производителя.
Внимание, т.к. это поле может содержать специальные параметры при передача методом GET используйте URL-кодирование!
delivery_key [text] Ключ желаемого способа получения (см. /deliveries)
with_crosses [bit] 1 — включить в результаты аналоги/кроссы.
0 — только искомый товар.
with_offers [bit] 1 — включить в результаты партнерские предложения.
0 — будет отображено только складское наличие.

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

offer_key [string] Ключ предложения товара, который необходимо передать в заказ.
stock [bit] Признак складского или партнерского товара.
1 — наличие, с собственного складе AE.
0 — товар партнера (заказной).
cross [int] Тип предложения:
NULL — Искомый товар
0 — Кросс (аналог)
1 — Замена номера
2 — Синоним бренда
3 — Проверенный кросс
10 — Комлект
11 — Часть
12 — Тюнинг
brand [string] Наименование бренда/производителя
code [string] Артикул по каталогу производителя
name [string] Наименование товара
packing [int] Кратность (или упаковка), 0 - нет кратности (т.е. можно заказывать поштучно)
price [float] Цена клиента за единицу товара в рублях
currency [string] Валюта
amount [int] Доступное количество для заказа
unit [string] Единица измерения
return [bit] Гарантированный возврат.
1 - есть, 0 - нет
order_before [datetime] Крайнее время заказа, до которого действителен delivery_time.
В формате ГГГГ-ММ-ДД ЧЧ:ММ (время локальное для выбранного способа получения)
В случае самовывоза с ПВЗ, когда товар находится на этом же складе, в этом поле вернется NULL (товар уже в ПВЗ и может быть заказан в любое время)
delivery_time [datetime] Расчетное время доставки.
В формате ГГГГ-ММ-ДД ЧЧ:ММ (время локальное для выбранного способа получения)
В случае самовывоза с ПВЗ, когда товар находится на этом же складе, в этом поле вернется NULL (товар уже в ПВЗ и может быть получен в любое время)
delivery_time_max [datetime] Максимальное время доставки.
В формате ГГГГ-ММ-ДД ЧЧ:ММ (время локальное для выбранного способа получения)
В случае самовывоза с ПВЗ, когда товар находится на этом же складе, в этом поле вернется NULL (товар уже в ПВЗ и может быть получен в любое время)
rejects [float] Вероятность отказа в процентах.
0% - на складе.
dealer [bit] Признак предложения от официального дилера
warehouse_name [string] Текстовое название склада на котором лежит товар.
В случае заказного товара: NULL
warehouse_key [string] Ключ склада, с которого будет отгружен товар. Список складов для каждого варианта получения можно получить /deliveries

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

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

GET/POST: /create_order/

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

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

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

delivery_key [text] Идентификатор способа доставки (см. Варианты получения)
payer_key [text] Идентификатор плательщика/подразделения на которое будет выставлен счет (см. Список плательщиков/подразделений)
stock_items [array] Массив заказываемых товаров
   offer_key [string] Идентификатор строки предложения поиска (см. /search_items)
   quantity [int] Количество заказываемого товара
   price [float] Желаемая/максимальная цена.
Если параметр указан, то делается сверка с актуальной ценой предложения и в случае превышения последней заказ не будет оформлен.
Если 0, то проверка производиться не будет.
   comment [string] Комментарий к строке
wait_all_goods [bit] Доставить весь заказ сразу или по мере поступления на склад. По умолчанию : 1 (всё сразу)
comment [string:255] Комментарий к заказу
delivery_date [string] Желаемая дата получения (не раньше чем).
В формате ГГГГ-ММ-ДД
Обратите внимание, что комментарий обрабатывается в контексте заказа, а не позиции. Т.е. при отправке заказа окончательный комментарий к нему сложится из комментария к заказу и всех комментариев к строкам. Разделитель — точка с запятой

Параметр price нужно использовать если вы хотите жестко зафиксировать цену по которой нашли предложение.

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

order_id [int] Номер заказа для дальнейшего отслеживания через /get_orders.
Если заказ не принят в это поле возвращается NULL
result [bool] Результат обработки.
TRUE — заказ принят
FALSE — заказ не принят.
result_description [string] Описание результата. Рекомендуется транслировать пользователю.

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

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

GET/POST: /get_orders/

Список заказов

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

• Список всех товаров во всех текущих заказах: вызов процедуры без параметров
• Проверка статуса по номерам заказов: передать только orders. При этом filters передавать не надо, он не будет обрабатываться.
• Поиск заказов (параметр filters): нужно обязательно указать даты. Плательщик и получение - опционально.

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

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

Внимание: фильтры работают в конъюнкции (логическое"AND")
orders [array] Простой массив номеров заказов
filters [array] Массив фильтров
   from [string:10] Начало диапазона дат заказов (ГГГГ-ММ-ДД)
   to [string:10] Конец диапазона дат заказов (ГГГГ-ММ-ДД)
   delivery_key [string] ключ варианта получения
   payer_key [string] ключ плетельщика
Пример посылаемых данных в JSON (аналогично можно передать в XML или serialized array):

[
1234567890,
9876543210
]

или
{
"dates":
{
"from":"2021-01-01",
"to":"2021-12-31"
},
"delivery_key":"1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz",
"payer_key":"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890"
}

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

brand [string] Наименование бренда/производителя
code [string] Артикул по каталогу производителя
name [string] Наименование товара
price [float] Цена за единицу товара в рублях
amount [int] Заказанное количество
unit [string] Единица измерения
dealer [bit] Товар от оф. дилера.
cancelable [bit] Возможность отмены на текущей стадии (см. поле статус)
0 — отмена невозможна
1 — отмена возможна
returnable [bit] Возможность возврата
0 — возврат невозможен
1 — возврат возможен
status_id [int] Текущий ID статуса позиции заказа. Возможные можно получить в процедуре /get_statuses
status [string] Текущий статус позиции заказа. Возможные варианты можно получить в процедуре /get_statuses
document [string] Название документа
order_id [int] Идентификатор заказа
(полученный при оформлении /create_order)
comment [string] Коментарий к заказу
united [bit] Доставка/получение всех товаров в заказе вместе или по мере поступления
0 — отдельно
1 — вместе
order_date [date] Дата/время оформления заказа
order_number [string] Номер заказа в документообороте AE
delivery [string] Способ и место получения заказа
delivery_date [date] Ожидаемая/фактическая дата получения заказа
order_key [date] Ключ заказа (см. cancel_order)

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

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

GET/POST: /get_statuses/

Список статусов

Список возможных статусов для списка заказов

Используйте эту процедуру если необходимо связать наши статусы с принятыми в вашей системе. Для маппинга используйте поле status_id.

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

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

Не требуется

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

При сортировке данных по status_id, статусы выстроятся по порядку их изменения у товара в процессе выполнения заказа.
group [string] Название группы статусов
status_id [int]
name [string]
description [text]

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

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

Версии

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

2021.07.07 2.0.0 Первичный релиз. Основные изменения по сравнению с v.1
2021.09.17 2.0.1 Публичный релиз. Мелкие доработки по результатам тестирования и отзывам интеграторов
2021.09.28 2.0.2 Добавлен параметр price в процедуру /create_order
2021.10.12 2.0.3 Добавлен параметр status_id в процедуру /get_orders и добавлен справочник /get_statuses
2022.01.27 2.0.4 Добавлен параметр delivery_time_max в процедуру /search_items
2022.10.10 2.0.5 При блокировке клиента (как правило, за просрочку оплаты) при поиске теперь отдается пустая выдача.
В процедуру /get_balance/ добавлен статус клиента для отслеживания блокировки.
2023.07.17 2.0.6 В процедуру /get_orders/ добавлен штрихкод товара
2023.07.21 2.0.7 В процедуру /search_items/ добавлен идентификатор валюты
2023.10.31 2.0.8 Добавлена процедура отмены позиции в заказе cancel_order

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

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

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

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

Примеры и интеграции

Мы подготовили для Вас два файла с примерами - для 1С-8 и POSTMAN.

POSTMAN

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

1С предприятие

Примеры запросов GET и POST.

Если Вы являетесь разработчиком и хотите поделиться своей интеграцией - пишите на api@autoeuro.ru, мы с удовольствием опубликуем Ваше решение.

Поддержка и обратная связь

Мы внимательно отслеживаем все пожелания наших клиентов и стараемся сделать сервис как можно более удобным для них. Пишите нам на адрес api@autoeuro.ru. Мы постараемся помочь Вам и ответить на Ваши вопросы

Если у Вас есть конкретные вопросы или проблемы, пожалуйста, укажите в письме ваш клиентский номер или логин, это сэкономит нам и Вам время.

Подписка на уведомления

Если Вы являетесь разработчиком или интегратором и заинтересованы в получении уведомлений об изменениях в первую очередь — подпишитесь на наши уведомления. Для этого отправьте письмо на адрес info_api@autoeuro.ru с краткими деталями о Вас: указанием названия компании и контактных данных.

Спама не будет, мы пишем кратко и по делу :)