API-сервис для клиентской части сайта (V1)

С помощью API-сервиса вы можете подключать к вашему сайту другие сайты (например, другие интернет-магазины автозапчастей).

API-сервис для клиентской части предоставляет следующие возможности:

• Проценка — получение актуальной информации о наличии товара;
• Заказ — автоматический заказ;
• Статусы — отслеживание статусов заказа.

API поддерживает следующие способы аутентификации:

1. API-ключ (api_key) — постоянный ключ клиента. Клиент должен иметь флаг api_enable = true.
2. Auth-ключ (auth_key) — временный ключ клиента. Получить ключ можно через HTTP Basic аутентификацию (эндпоинт /api/v1/auth_key/init). Имеет ограниченное время действия.

Оба ключа передаются как query-параметр в каждом запросе.

Доступ к АПИ по ключу доступа​ (api_key)

Чтобы настроить доступ клиента к АПИ по ключу доступа, выполните следующие действия:

ШАГ 1. В панели администрирования перейдите в раздел Контрагенты → Клиенты и в строке нужного клиента нажмите кнопку Редактировать.

Переход к настройкам клиента

ШАГ 2. На открывшейся странице перейдите к блоку Доступ к API и активируйте опцию Включить доступ к API по логин/паролю.

Нажмите кнопку Сохранить.

Активация доступа

ШАГ 3. Вернитесь к блоку Доступ к API.

После сохранения настроек ключ доступа генерируется автоматически и отображается в поле Ключ.

Если требуется, в поле Лимит запросов в день укажите количество запросов к API, которое будет доступно клиенту в день.

Получение ключа доступа

Доступ к АПИ по коду авторизации (auth-key)

Получить код авторизации (auth_key) можно любым из способов:

1. В клиентской части сайта — в адресной строке браузера введите часть /api/v1/auth_key/init после адреса вашего сайта.

Получение auth_key в клиентской части

2. Через GET-запроc​ GET /api/v1/auth_key/init.

Пример ответа:

{
"result":"ok",
"auth_key":"124b0d5b13b61174751266e41ac5aa66", # код авторизации
"expires_in":"05.05.2020 15:54 +03:00", #срок действия кода авторизации
"customer_id":5124, #ID авторизованного клиента
"user_id":1 #ID менеджера клиента
}

По умолчанию код авторизации действителен 24 часа. 

Изменить срок действия кода можно в разделе Сайт → Общие настройки (поле Срок действия AuthKey в часах).

Изменение срока действия auth_key

Документация по запросам

Ниже представлена техническая документация по запросам, которая может потребоваться разработчикам ваших клиентов.

Для всех запросов передается параметр api_key или auth_key, который служит авторизационным ключом.

Api_key необходимо запросить у вашего менеджера.

Перечень запросов:

1. Получение списка брендов по номеру
2. Получение предложений
3. Поиск предложений по номеру и марке детали
4. Поиск предложений по названию детали
5. Получение предложений по нескольким номерам
6. Получение списка товаров в Корзине
7. Очистить корзину
8. Удалить элемент корзины
9. Отправить в заказ содержимое корзины
10. Добавить в корзину
11. Получение позиций заказов клиентов
12. Получить информацию о менеджерах
13. Детализация по балансу
14. Общая статистика по балансу и заказам
15. Получить информацию о страницах
16. Получить информацию о странице по ее ID
17. Получить список новостей
18. Получить новость по ID

Запросы:

1. Получение списка брендов по номеру

GET /backend/price_items/api/v1/search/get_brands_by_oem

Параметры:

• oem – номер запрашиваемой детали

Пример результата:

result: "ok",
data: [
{
number: "C110", #номер детали
brand: "DOLZ", #производитель
des_text: "Водяной насос" #название
}
]

---

2. Получение предложений

GET /backend/price_items/api/v1/search/get_offers_by_oem_and_make_name

Параметры:

• oem – номер детали
• make_name – производитель
• without_cross – показ кроссов. Значение по умолчанию "false". Укажите "true" для исключения кроссов из результатов выполнения запроса.
  Параметр применяется только для в запросах для поиска по номеру и марке.
• text – название детали или текстовая строка поиска

3. Поиск предложений по номеру и марке детали

http://company-shop.name/backend/price_items/api/v1/search/get_offers_by_oem_and_make_name?api_key=api_key&oem=OP572&make_name=FILTRON&without_cross=true

Здесь company-shop.name – внешний адрес вашего интернет-магазина, api_key – ключ доступа API, oem=OP572 – фильтр по номеру детали "OP572", make_name=FILTRON – фильтр по марке детали "FILTRON".

Полученный результат:

result: "ok",
data: [
{
oem: "OP572", #Номер детали
make_name: "FILTRON", #Производитель
detail_name: "Фильтр масляный OP572", #Названия в прайс листе
cost: 164, #Цена продажи
qnt: 25, #Доступное количество, может быть -1 если точное количестов не известно
min_qnt: 2, #Кратность поставки
min_delivery_day: 0, #Минимальный срок доставки
max_delivery_day: 0, #Максимальный срок доставки
sup_logo: "BERG", #Направление поставки
stat_group: 0, #Процент поставки
system_hash: "K29PTTF4akxGN2lkcFE0ajFmUWJzSGtyOUI3Vzk5MVRt1c1c6ced238fd8159a2fa" #hash для заказа через api
}
]

4. Поиск предложений по названию детали

http://company-shop.name/backend/price_items/api/v1/search/get_offers_by_oem_and_make_name?api_key=api_key&text=водяной насос

Здесь text=водяной насос – фильтр по названию "водяной насос".

Полученный результат:

{
"data": [
{
"oem": "94964", #Номер детали
"make_name": "HONDA", #Марка
"detail_name": "Насос водяной(помпа)", #Название
"cost": 925, #Цена
"qnt": -1, #Количество, здесь неизвестно
"min_qnt": 1, #Кратность поставки
"min_delivery_day": 0, #Минимальный срок доставки
"max_delivery_day": 4, #Максимальный срок доставки
"stat_group": 0, #Процент поставки
"system_hash": "PR|259649|ee8d0b9a-e789-42ff-b10f-b62c2223f218-ITEM0", #hash для заказа через api
"sup_logo": «BERG», #Направление поставки
"volume": 0
}
],
"result": "ok"
}

---

5. Получение предложений по нескольким номерам

POST /backend/price_items/api/v1/search/get_offers_by_oem_and_make_name

Параметры:

• articles – json коллекция из бренд+номер детали. Максимальная длина массива 25. Пример значение параметра^ [{"make_name": "DOLZ", "oem": "C110"},{"make_name": "DOLZ","oem": "C1101"}].
• category_id – ID категории.
  Есть веб-сервисы, которые поддерживают поиск по нескольким номерам (например, веб-сервис WebService::Power). В карточках этих веб-сервисов выбираются нужные категории. При открытии этих каталогов в поиск включаются соответствующие веб-сервисы.

---

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

GET /api/v1/baskets/

Пример результата:

{"result": "ok", "data": [
{"id" : 1409, #id позиции в корзине
"oem" : "ADB01165", #номер детали в заказе
"make_name": "ALLIED NIPPON", #производитель
"detail_name": "Тормозные колодки", #название детали
"cost": 1178.0, #цена
"qnt": 1, #количество
"min_delivery_day": 2, #минимальный срок доставки
"max_delivery_day": 2, #максимальный срок доставки
"comment": "" #комментарий
}
]}

---

7. Очистить корзину

POST /api/v1/baskets/clear

Пример результата:

{result: 'ok'}

---

8. Удалить элемент корзины

DELETE /api/v1/baskets/:id

Параметры:

• :id – id позиции в корзине

Результат при успешном удалении позиции:

{result: 'ok'}

---

9. Отправить в заказ содержимое корзины

POST /api/v1/baskets/order

Результат при успешном создании заказа:

{result: 'ok'}

---

10. Добавить в корзину

POST /api/v1/baskets

Параметры:

• oem — номер заказываемой детали
• make_name — производитель заказываемой детали
• detail_name — название заказываемой детали
• qnt — количество в заказ
• comment — комментарий к позиции
• min_delivery_day — минимальный срок доставки
• max_delivery_day — максимальный срок доставки
• api_hash — hash полученный из проценки

Результат при успешном добавлении позиции:

{result: 'ok'}

---

11. Получение позиций заказов клиентов

GET /api/v1/order_items

Параметры:

• page – номер страницы выборки. По 10 позиций на выборку
• search[id_eq] – поиск по id позиции
• search[oem_eq] – поиск по номеру
• search[make_name_eq] – поиск по производителю
• search[comment_eq] – поиск по комментарию
• search[status_code_eq] – поиск по группе статуса
• per_page – количество позиций в выборке. Значение по умолчанию 10

Пример результата:

result: "ok",
data: [
{
id: 4068, #id позиции заказа
oem: "6698", #номер детали
make_name: "KAMOKA", #производитель
detail_name: "КОМПЛЕКТ ШРУСА ВНЕШНИЙ", #название детали
cost: 2520, #цена
qnt: 1, #количество заказано
qnt_accept: null, #количество подтверждено
qnt_income: null, #количество пришло
status: "Принят к обработке", #статус - название
status_code: "processing", #код статуса
comment: "test test 2", #комментарий клиента
created_at: "2012-10-28T09:11:12+03:00" #дата создания заказа
}
]

Возможны коды статусов:

• processing - обрабатывается менеджером
• commit - подтвержден
• v-zakaze - отправлен в заказ
• supplier-commit - подтвержден поставщиком
• transit - в пути
• supplier-accept - ожидает приемки на склад
• prishlo - пришло на склад
• vydano - выдано
• otkaz - отказ поставки
• snyat - клиентом или поставщиком
• vozvrat - возврат

---

12. Получить информацию о менеджерах

GET /api/v1/customers/manager

Параметры:

• search[id_eq] – поиск по id менеджера
• search[email_eq] – поиск по email
• search[name_eq] – поиск по имени
• search[phone] – поиск по номеру телефона

Пример результата:

result: "ok",
data: [
{
"id":2466
"email":"A.Alekseev@tpas.ru",
"name":"Алексеев Андрей",
"phone":"8-921-787-18-32",
"skype":null,
"icq":"641-506-908",
"photo":null
}
]

---

13. Детализация по балансу

GET /api/v1/customers/:id/balances

Параметры:

• id – ID клиента
• page – номер страницы выборки.
• per_page – количество записи в выборке. Значение по умолчанию 10.
• search[created_at_gt] – дата создания больше, формат 06.07.2014%2011:47:45
• search[created_at_lt] – дата создания меньше, формат 10.07.2014%2011:47:45
• search[updated_at_gt] – дата обновления больше, формат 06.07.2014%2011:47:45
• search[updated_at_lt] – дата обновления меньше, формат 10.07.2014%2011:47:45

Пример результата:

result: "ok",
data: [
{
"id":8414,
"customer_id":5124,
"customer_inn":"",
"description":"Списание по заказу № 6938",
"sum":-5926.0,
"income_type":null,
"created_at":"2020-04-04T11:02:00.266+03:00",
"updated_at":"2020-04-04T11:02:00.266+03:00"
}
]

---

14. Общая статистика по балансу и заказам

GET /api/v1/customers/:id/stat

Параметры:

• id – ID клиента

Пример результата:

{
"result":"ok",
"data":{

"balance":{
"title":"Баланс",
"result":-2874079.06
},
"credit_balance":{
"title":"Баланс с кредитным лимитом",
"result":7125920.9399999995
},
"delay_balance":{
"title":"Баланс отсрочки",
"result":-2874079.06
},
"check_balance":{
"title":"На проверке",
"result":19554645.704084
},
"work_balance":{
"title":"В работе",
"result":5634057.16
},

"warehouse_balance":{
"title":"К отгрузке",
"result":600.0
},
"shipped_and_return_sum":{
"title":"Возврат + Выдано",
"result":702783.0
},
"return_order_item_sum":{
"title":"Возврат",
"result":0.0
},
"return_percent":{
"title":"Процент от суммы возврат + выдано",
"result":0.0
},
"order_count":{
"title":"Заказов за все время",
"result":632
},
"order_item_count":{
"title":"Позиций за все время",
"result":2870
},
"revenue":{
"title":"Оборот за все время",
"result":25892085.864084
},
"revenue_last_month":{
"title":"Оборот за прошлый месяц",
"result":13540.0
},
"revenue_current_month":{
"title":"Оборот за текущий месяц",
"result":24076.0
},
"average_check":{
"title":"Средний чек",
"result":42126.441462158225
},
"last_request_at":{
"title":"Последний запрос",
"result":"2020-04-04T10:58:22.650+03:00"
},
"last_order_id":{
"title":"ID последнего заказа",
"result":6938
},
"last_order_at":{
"title":"Последний заказ",
"result":"2020-04-04T11:01:55.012+03:00"
},
"profit":{
"title":"Прибыль за все время",
"result":440866.2639
},
"profit_last_month":{
"title":"Прибыль за прошлый месяц",
"result":0.0
},
"profit_current_month":{
"title":"Прибыль за текущий месяц",
"result":0.0
},
"in_work_balance":{
"title":"Баланс - заказы в работе",
"result":-2874079.06
}
}
}

---

15. Получить информацию о страницах

GET /api/v1/pages

Параметры:

• search[id_eq] – поиск по id страницы
• search[title_eq] – поиск по заголовку
• search[active_true] – поиск активных страниц
• search[active_false] – поиск не активных страниц
• search[page_category_id_eq] – поиск по ID категории страниц

Пример результата:

"result":"ok",
"data":[
{
"id":187,
"title":"Свечи зажигания",
"description":"",
"body":"",
"active":true,
"created_at":"2014-10-28T12:47:35.142+03:00",
"page_category_id":38,
"position":null,
"slug":"svechi-zazhiganiya",
"on_main_page":false,
"sub_url":null,
"on_head":false,
"in_footer":true,
"region_id":null,
"only_auth":false,
"custom_url":null,
"css_class":null,
"meta_title":null,
"meta_description":null,
"meta_keywords":null,
"seo_h1":null,
"seo_text":null
}
]

---

16. Получить информацию о странице по ее ID

GET /api/v1/pages/:id

Параметры:

• id – ID страницы

Пример успешного результата:

"result":"ok",
"data":{
"id":187,
"title":"Свечи зажигания",
"description":"",
"body":"",
"active":true,
"created_at":"2014-10-28T12:47:35.142+03:00",
"page_category_id":38,
"position":null,
"slug":"svechi-zazhiganiya",
"on_main_page":false,
"sub_url":null,
"on_head":false,
"in_footer":true,
"region_id":null,
"only_auth":false,
"custom_url":null,
"css_class":null,
"meta_title":null,
"meta_description":null,
"meta_keywords":null,
"seo_h1":null,
"seo_text":null
}

Пример ответа, когда не удается найти страницу:

"result": "error"
"error": "Page with id 187 not found"

---

17. Получить список новостей

GET /api/v1/news

Параметры:

• search[id_eq] – поиск по ID новости
• search[created_at_gt] – дата создания больше, формат 06.07.2014%2011:47:45
• search[created_at_lt] – дата создания меньше, формат 10.07.2014%2011:47:45
• search[news_type_eq] – поиск по типу новости (news, articles)

Пример результата:

"result":"ok",
"data":[
{
"id":81,
"title":"Новая новость",
"description":"вав",
"body":"Текст",
"created_at":"2019-06-17T09:53:57.099+03:00",
"region_id":null,
"position":null,
"slug":"novaya-novost",
"news_type":"news",
"icon":http://private-www.parts-soft.ru/system/preview/81/news-
ic_original.png?1580802823
}
]

Возможны типы новостей:

• adt – Анонсы
• news – Новости
• action – Акции
• articles – Статьи

---

18. Получить новость по ID

GET /api/v1/news/:id

Параметры:

• id – ID новость

Пример успешного результата:

"result":"ok",
"data":
{
"id":81,
"title":"Новая новость",
"description":"вав",
"body":"Текст",
"created_at":"2019-06-17T09:53:57.099+03:00",
"region_id":null,
"position":null,
"slug":"novaya-novost",
"news_type":"news",
"icon":http://private-www.parts-soft.ru/system/preview/81/news-
ic_original.png?1580802823
}

Пример ответа когда не удается найти новость по ID:

"result": "error"
"error": "News with id 81 not found"