Инструкция по работе с API APM.GROUP


Доступ к API осуществляется по протоколу HTTPS. Точка доступа - https://api.apm.group/


Скачать документацию.


Все запросы должны быть реализованы методом POST.

API поддерживает два формата: JSON и XML. Формат ответа соответствует формату запроса. По умолчанию JSON.
Количество попыток подбора пароля ограничено ( ip - адрес блокируется на 3 часа по их исчерпанию).
Для использования API требуется иметь подтвержденную учетную запись на сайте https://apm.group и действующий `token`.
`token` будет действителен только для ip-адреса , с которого происходила его генерация. Так же он не имеет срока годности (обновляется при повторной генерации вместе с ip-адрессом, с которого был сгенерирован). Для использования некольких аккаунтов с одного адресса необходимо предупредить администрацию сайта.

Параметры `token` и `name` обязательные для работы с API (описание генерации представлено ниже).
1. Генерация `token` ( необходим для работы с API )
url для доступа - /token
username – логин на сайте. Обязательный
password – пароль от аккаунта. Обязательный

token - ключ для работы с API.
name - логин пользователя

JSON
Запрос:
{
"username": "test",
"password": "myrealpassword"
}

Ответ:
{
"name": "test",
"token": "ZtAZABfaQ78-EXT44M_HKvxyefVj8JM7"
}

2. Поиск товарных позиций
url для доступа - /product/search
code - строка с кодом товарной позиции. ОбязательныйВозможно указать несколько позиций через `||` (не более 10). Пример "37566ere||3674555||mpu-010".
analogs - отвечает за возврата списка аналогов по искомой товарной позиции. Допустимые значение "true" или "false". Необязательный. По умолчанию "false".

JSON
Запрос:
{
"name":"test_name",
"token":"ZzcM5gWnNLizvVRxFcrTfK7PKlDbCa0W",
"code":"263202F100",
"analogs":true
}
Ответ:
{
"263202F100_code": {
"mainProducts": [
{
"id": "1714422",
"code": "263202F100",
"name": "Фильтр масляный MOBIS ",
"price": 7.05,
"currency_id": "1",
"available": "7",
"min_lot": "1",
"make": "MOBIS",
"weight": "0.114",
"delivery": null,
"priceName": "UA",
"supplier_id": "3",
"price_info": 7.05,
"currency": "USD"
},
{
"price": 10.08,
"id": "1",
"code": "263202F100",
"name": "mpu020",
"currency_id": "1",
"available": "5",
"min_lot": "1",
"make": "mpu020производитель",
"weight": "0.200",
"delivery": "15",
"supplier_id": "7",
"priceName": "DC1072",
"price_info": 10.08,
"currency": "USD"
},
],
"analogProducts": [
{
"available": "10",
"make": "ASHIKA",
"code": "10ECO096",
"price": 1.93,
"name": "Фильтр масляный",
"weight": "0",
"min_lot": "1",
"delivery": "5/0",
"priceName": "TRD",
"currency_id": "1",
"supplier_id": "8",
"id": "0",
"price_info": 1.93,
"currency": "USD"
},
. . .
{
"available": "5",
"make": "Hyundai / KIA",
"code": "263202F010",
"price": 5.97,
"name": "ФИЛЬТР ТОПЛИВНЫЙ",
"weight": "0.495",
"min_lot": "1",
"delivery": "19/45",
"priceName": "JA2",
"currency_id": "1",
"supplier_id": "1",
"id": "0",
"price_info": 5.97,
"currency": "USD"
}
]
}
}


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

“analogProducts” - перечень аналогов для детали с данными
“maineProduct” - перечень складом с данными детали
"263202F100_code": - запрашуемый код `263202F100` с приставкой `_code`
"available": 6 – максимальное количество для заказа
"make": "Timken" - производитель
"code": "367MPU" - код товара (регистрозависим)
"price": 13.59 - цена товара в валюте склада
"name": "" - название товара
"weight": 0 - вес
"min_lot": 1 – количесво, минимально допустимое для заказа
"delivery": "3/10" - время доставки (дни)
"priceName": "EMIR" - название склада
"currency_id": "1" – id валюты, в котором указана цена склада
"supplier_id": "1"
"id": 0 - id товара, может принимать нулевое значение
"price_info": 13.59, - цена в валюте пользователя
"currency_user": "USD" - текущая валюта пользователя, в которой указано значение

Расшифровка складов:
DU – наличие на складе в Дубае
DU1 - партнер Дубай
DU2 - партнер Дубай
DU3 - партнер Дубай
DU5 - партнер Дубай
US6 - партнер США
JA1 - партнер Япония
JA2 - партнер Япония
JA3 - партнер Япония
Расшифровка валют:
1 – USD
2 – EUR
3 – UAH

Полный пример ответа приведен в конце описания. П.2
3. Создание заказа
url для доступа - /order/create
delivery - вмещает данные о клиенте, времени доставки и типе доставки, при их отсутствии заполняются данными пользователя, указанными при регистрации.
Сумма заказа изымается из баланса аккаунта.

"fio" - ФИО
"city"
"address"
"phone"
"reference"
"notes"
"delivery_type" - Обязательный
Допустимые значения:
1 - самовывоз
2 - Доставка

delivery_status - вид доставки. Необязательный. По умолчанию 1.
Допустимые значения:
1 - самолетом
2 - контейнером
order - вмещает в себя все пункты заказа, Обязательный

"id":"123456 – Обязательный. ` id` товара. Может принимать пустое значение (берется из данных поиска)
"code":"TM5" - Обязательный. Код товара
"price":17.33 - Обязательный. Цена за единицу товара в валюте склада. (или же указать параметр `price_info` - цена в валюте клиента, указанная в кабинете. )
"make":"Drive+Joy" – Обязательный. Производитель.
"priceName":"UA" - Обязательный. Название склада
"supplier_id":"1" - Обязательный. Может принимать пустое значение (берется из данных поиска)
"quantity" - количество товаров, по умолчанию устанавливается значение 1.
"api_reference" - текстовая информация, позволяющая клиенту идентифицировать пункт заказа. Максимальное значение 128 символов.
"CoeffMaxAgree" – максимальный коэффициент превышения цены продажи для клиента над ценой, показанной на сайте. По умолчанию 1.015%.

Параметры ответа:
"item_id" – id пункта заказа в нашей системе. Принимает значение `0` в случае ошибки
"order_id" – id заказа в нашей системе. Принимает значение `0` в случае ошибки
"code" – код товара
"quantity" – количество товарных едениц в пункте заказа
"price" – цена товара в валюте склада
"price_info" - цена товара в валюте пользователя (валюта берется с данных личного кабинета)
"supplier_id" – значние, указываемое при создании заказа
"currency" – валюта пользователя для значения "price_info" (валюта берется с данных личного кабинета)
"delivery_status" – вид доставки. Расшифровку см. выше
"api_reference" - текстовая информация, позволяющая клиенту идентифицировать пункт заказа
"status" – статус пункта заказа. Может принимать следующие значения:
'ok' – пункт заказа создан без ошибок
'in' – привышение максимального коэффициента превышения цены продажи для клиента над ценой, показанной на сайте
'nf' – продукт не найден
'os' – продукт временно отсутствует
'ml' – количество заказанного продукта меньше количесва, минимально допустимого для заказа
'mq' - количество заказанного продукта не кратно минимально допустимого количества для заказа. Пример: минимально допустимо - 5. Заказано 7. А заказ должен быть равен 5 или 10 или 15 итд
'qc' – количество продуктов в пункте заказа изменено
'wp' - Заказ создан но не оплачен. Внимание! Если счет будет пополнен заказ отправиться в работу
"info" – текстовое описание статуса пункта заказа или внесенных в него изменений, ошибкок


JSON
Запрос:
{ "name": "test_name",
"token": "ZzcM5gWnNLizvVRxFcrTfK7PKlDbCa0W",
"test":"ок" //тестовый заказ создается с признаком TEST, заказ в работу не уходит и не проверяет наличие баланса. Автоматически удаляется через три дня. При отсутствии этого параметра заказ считается реальным
"common_reference"=>"Oбщий референс",// общий референс для всего заказа

"order": [
{
"id": "1714422",
"code": "263202F100",
"name": "Фильтр масляный MOBIS ",
"price": 7.00,
"currency_id": "3",
"make": "MOBIS",
"delivery": 2,
"priceName": "UA",
"supplier_id": "3",
"quantity": 2,
"CoeffMaxAgree" : 0.01
},
{
"id": "1714428",
"code": "252822G000",
"name": "Шкив ",
"price_info": 407.99,
"currency_id": "3",
"make": "MOBIS",
"delivery": 1,
"priceName": "UA",
"supplier_id": "3",
"quantity": 1,
"api_reference": "1000925328"
},
] ,
"delivery":{
"fio":"test","city":"test","address":"Tank st.","phone":"+38099665544","reference":"4ty","notes":"for tests","delivery_type":1,"delivery_city":"delivery_city","delivery_street":"delivery_street","delivery_house":"13","delivery_apartment":"9"
}
}

Ответ:
{
"info": "exceeding the sale price for the client over the price shown on the site: product with code `263202F100` ;product `252822G000` is temporarily out of stock; product whith code `wrong_code` not found; ",
"order": [
{
"item_id": 0,
"order_id": 0,
"code": "263202F100",
"quantity": 0,
"price": 7.05,
"price_info": 7.05,
"currency": "USD",
"supplier_id": "3",
"delivery_status": 1,
"status": "in",
"api_reference": "",
"info": "exceeding the sale price for the client over the price shown on the site: product with code `263202F100` ;"
},
{
"item_id": 0,
"order_id": 0,
"code": "252822G000",
"quantity": 0,
"price": 14.89,
"price_info": 7.05,
"currency": "USD",
"supplier_id": "3",
"delivery_status": 1,
"status": "os",
"api_reference": "1000925328",
"info": "product `252822G000` is temporarily out of stock; "
},
{
"item_id": 22086,
"order_id": 7908,
"code": "263202F100",
"quantity": 1,
"price": 5.97,
"price_info": 5.97,
"supplier_id": 1,
"currency": "USD",
"delivery_status": 1,
"api_reference": "api_ref",
"status": "ok",
"info": ""
},{
"item_id": 0,
"order_id": 0,
"code": "wrong_code",
"quantity": 0,
"price": 0,
"price_info": 0,
"supplier_id": "8",
"currency": "USD",
"delivery_status": 1,
"api_reference": "TRD",
"status": "nf",
"info": "product whith code `wrong_code` not found; "
}
]
}

В ответе в поле `info` могут описываться нюансы создания заказа, такие как недостаточное количество товара на складе (отсутствие на складе) и измененное количество заказанного товара (если запрашиваемое количество товара больше, чем есть в наличии, то количество товара в заказе изменяется автоматически, при этом выводится описание в этом поле).
При создании заказа, не факт, что все пункты заказа будут находится в одном заказе в нашей системе. Пункты заказа сортируются как по типам доставки, так и по складам, и могут принадлежать разным заказам с разными номерами в нашей системе

4. Просмотр своих заказов
url для доступа - /order/search
order_id - номер заказа, Необязательный (если пропустить, выведет 20 крайних заказов)
updated_at - время в формате unix, указывающее на момент, с которого надо возвратить заказы, информация о которых была обновлена (подходит для автоматического обновления статусов доставки и т.д). Необязательный
JSON
Запрос:
{ "name": "test_name",
"token": "ZzcM5gWnNLizvVRxFcrTfK7PKlDbCa0W",
"order_id": 7893
}
Ответ:
[
{
"id": 7893,
"user_id": 733,
"created_at": 1545658177,
"updated_at": 1545658178,
"fio": "test",
"city": "test",
"address": "test",
"phone": "+380933898555",
"notes": "From API. for tests",
"admin_notes": null,
"payment_type": 2,
"delivery_type": 1,
"delivery_city": "delivery_city",
"delivery_street": "test",
"delivery_house": "+380933898555",
"delivery_apartment": null,
"status": "WAIT_PAY",
"currency_id": 1,
"first_payment_percent": null
}
]

Значение `status` в ответе - это текущий статус всего заказа в целом. Может принимать следующие значения:

IN_PROGRESS - в работе
WAIT_PAY - ожидание оплаты
DONE - завершен
NOT_AVAILABLE - нет в наличии
EXPIRED - просроченARCHIVE - в ахиве
USER_REFUSE - отказ пользователя
READY_TO_SEND - готов к отгрузке
SENT_FROM_STOCK - отправлен со склада

5. Просмотр пунктов заказов с возможность поиска по идентификаторам, установлнным клиентом (рекомендуемый способ для получения статуса пункта заказа)
url для доступа - /order/searchitems

ВАЖНО! Пункты заказа могут разделяться в зависимости от наличия на складе, повышения цены и т.д. К примеру: был создан пункт заказа с количеством 6 шт. детали MPU020. Товар отправляется по частям. Сначало 4 шт. , затем 2 шт. (или же 2 шт. не оказалось в наличии, а лишь 4шт.). Пункт заказа может быть разделен на два пункта. Количество в старом пункте и новом измениться соответственно на 4 шт. и 2шт. Эти два пункта будут принадлежать одному заказу ("order_id") и иметь одинаковое значение параметра “api_reference”, так же будут иметь и одинаковых производитя , склад, артикул (MPU020) и т.д.

order_id - номер заказа, Необязательный (по умолчанию выводит 20 крайне заказанных товарных позиций)
api_reference - текстовая информация, позволяющая клиенту идентифицировать пункт заказа. Для отслеживания пунктов заказа. Необязательный. Для поиска нескольких пунктов заказа одним запросом с разными значениями api_reference, необходимо перечислить их в строке , разделяя значения ‘||’.
Описане возвращаемых значений.
supplier_detail_id – вспомогающий параметр, позволяющий отследить, какой именно пункт заказа был разделен (пункт заказа может делиться несколько раз , как пример пункт заказа разделился на 3 пункта, у которых будут значения !000151259553/2, !000151259553/3, !000151259553/4 ).

Значение `status` в ответе - это текущий статус пункта заказа. Может принимать следующие значения:

EMPTY - заказ не в работе
NEW - новый
BOUGHT - закуплено
IN_WORK – в работе
IN_STOCK – на складе
NOT_AVAILABLE – нет на складе
FACT_NOT_AVAILABLE фактически нет в наличии
READY_TO_SEND – готово к отгрузке

GIVEN - выдан
PRICE_INCREASE – повышение цен
DUBAI - на складе в ОАЭ
DUBAI_SENT - отправлено из ОАЭ
AMT_SENT – отправлено из США
TRD_SENT – отправлено со склада TRD
SENT_TO_STOCK – отправлен на склад
SENT_FROM_STOCK - отправлено со склада
DAMAGED - поврежден
AMT – на складе в США
USER_REFUSE – отказ клиента

order_id – номер заказа в нашей системе
id – номер пункта заказа в нашей системе
quantity – фактическое количество в пункте заказа ( original_quantity –принимает значение первоначально указанного количества в случае изменения значения )
price – цена в валюте склада
currency_price – цена в валюте пользователя (указывается в настройках аккаунта https://apm.group/profile/settings )
delivery_status – вид доставки. Описание см. выше

JSON
Запрос:
{ "name": "test_name",
"token": "ZzcM5gWnNLizvVRxFcrTfK7PKlDbCa0W",
"api_reference" : "123#321||123#322"
}
Ответ:
[
{
"id": 22088,
"order_id": 7910,
"price": "5.9100",
"quantity": 1,
"status": "EMPTY",
"currency_price": "5.9100",
"delivery_status": 1,
"original_quantity": null,
"status_date": 1545666564,
"api_reference": "123#322",
“supplier_detail_id”: null
},
{
"id": 22087,
"order_id": 7909,
"price": "10.0800",
"quantity": 1,
"status": "EMPTY",
"currency_price": "10.0800",
"delivery_status": 1,
"original_quantity": null,
"status_date": 1545666563,
"api_reference": "123#321",
“supplier_detail_id”: null
}
]

6. Просмотр пунктов заказа
url для доступа - /order/searchorderitems
order_id - номер заказа, необязательный ( если пропустить, выведет все пункты сортируя по времени с выборкой по указанному времени )
status_date - время в формате unix. Необязательный. Для выборки пунктов, которые были изменены, начиная с этого времени.
Значение `status` - это текущий статус пункта заказа. Возможные значения с описанием представлены в п.5.

JSON
Запрос:
{ "name": "test_name",
"token": "ZzcM5gWnNLizvVRxFcrTfK7PKlDbCa0W",
"order_id" : 7908
}
Ответ
[
{
"id": 22086,
"order_id": 7908,
"price": "5.9700",
"quantity": 1,
"status": "EMPTY",
"currency_price": "5.9700",
"delivery_status": 1,
"original_quantity": null,
"status_date": 1545666561,
"api_reference": "api_ref"
}
]

ПРИМЕРЫ запросов и ответов:
П.2 Ответ на запрос по поиску нескольких товарных позиций с выводом аналогов
Запрос:
{"name":"test_name","token":"ZzcM5gWnNLizvVRxFcrTfK7PKlDbCa0W","code":"263202F100||mpu020","analogs":true}


{

"263202F100_code": {
"mainProducts": [
{
"id": "1714422",
"code": "263202F100",
"name": "Фильтр масляный MOBIS ",
"price": 7.05,
"currency_id": "1",
"available": "3",
"min_lot": "1",
"make": "MOBIS",
"weight": "0.114",
"delivery": null,
"priceName": "UA",
"supplier_id": "3",
"price_info": 7.05,
"currency": "USD"
},
{
"price": 10.08,
"id": "1",
"code": "263202F100",
"name": "mpu020",
"currency_id": "1",
"available": "5",
"min_lot": "1",
"make": "mpu020производитель",
"weight": "0.200",
"delivery": "15",
"supplier_id": "7",
"priceName": "DC1072",
"price_info": 10.08,
"currency": "USD"

}{
"available": "5",
"make": "Hyundai / KIA",

"code": "263202F100",
"price": 10.05,
"name": "ФИЛЬТР МАСЛЯНЫЙ",
"weight": "0.128",
"min_lot": "1",
"delivery": "61/80",
"priceName": "KOR2",
"currency_id": "1",
"supplier_id": "1",
"id": "0",
"price_info": 10.05,
"currency": "USD"
},
{
"available": "5",
"make": "Hyundai / KIA",
"code": "263202F100",
"price": 13.18,
"name": "ФИЛЬТР МАСЛЯНЫЙ",
"weight": "0.128",
"min_lot": "1",
"delivery": "16/50",
"priceName": "US6",
"currency_id": "1",
"supplier_id": "1",
"id": "0",
"price_info": 13.18,
"currency": "USD"
}
],
"analogProducts": [
{
"available": "10",
"make": "ASHIKA",
"code": "10ECO096",
"price": 1.93,
"name": "Фильтр масляный",
"weight": "0",
"min_lot": "1",
"delivery": "5/0",
"priceName": "TRD",
"currency_id": "1",
"supplier_id": "8",
"id": "0",
"price_info": 1.93,
"currency": "USD"
},
{
"available": "11",
"make": "BLUE PRINT",
"code": "ADG02141",
"price": 2.51,
"name": "Фильтр масляный",
"weight": "0.11",
"min_lot": "1",
"delivery": "5/0",
"priceName": "TRD",
"currency_id": "1",
"supplier_id": "8",
"id": "0",
"price_info": 2.51,
"currency": "USD"
},
{
"available": "1",
"make": "UFI",
"code": "2516600",
"price": 12.35,
"name": "",
"weight": "0",
"min_lot": "1",
"delivery": "29/50",
"priceName": "EU",
"currency_id": "1",
"supplier_id": "1",
"id": "0",
"price_info": 12.35,
"currency": "USD"
}
]
},
"available": "5",
"make": "Toyota",
"code": "2322037121",
"price": 248.11,
"name": "НАСОС ТОПЛИВНЫЙ",
"weight": "0.434",
"min_lot": "1",
"delivery": "16/45",
"priceName": "JA2",
"currency_id": "1",
"supplier_id": "1",
"id": "0",
"price_info": 248.11,
"currency": "USD"
},
{
"available": "5",
"make": "Toyota",
"code": "2322028180",
"price": 258.78,
"name": "НАСОС ТОПЛИВНЫЙ",
"weight": "0.496",
"min_lot": "1",
"delivery": "44/50",
"priceName": "US6",
"currency_id": "1",
"supplier_id": "1",
"id": "0",
"price_info": 258.78,
"currency": "USD"
},
{
"available": ">1",
"make": "Lexus",
"code": "2322047011",
"price": 263.81,
"name": "PUMP ASSY FUEL W/FI",
"weight": "0",
"min_lot": "0",
"delivery": "10/20",
"priceName": "AMT",
"currency_id": "1",
"supplier_id": "6",
"id": "0",
"price_info": 263.81,
"currency": "USD"
}
]
}
}

Пример генерации `token` (JSON) на PHP
$data='{"username":"test@ok.com.ua","password":"000000000"}';
$ch = curl_init('https://api.apm.group/token');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS,$data);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
var_dump(curl_exec($ch));
curl_close($ch);
Пример генерации `token` (XML)
$data='<root>
<password>000000000</password>
<username>test@ok.com.ua</username>
</root>';
$ch = curl_init('https://api.apm.group/token');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS,$data);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/xml'));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
var_dump(curl_exec($ch));
curl_close($ch);

Пример поиска запчастей по коду
$data='{"name":"test@ok.com.ua","token":"GuqnhVObR16LvDiZb_lsoyrBGKPtaEGv","code":"252822G000","analogs":true}';
$ch = curl_init('https://api.apm.group/product/search');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS,$data);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
var_dump(curl_exec($ch));
curl_close($ch);
Используя сайт apm.group, вы соглашаетесь с использованием файлов cookie и сервисов сбора технических данных посетителей (IP-адресов, местоположения и др.) для обеспечения работоспособности и улучшения качества обслуживания. Политика конфиденциальности
Принять
x