Aquamonkey
api docs
Basics:
Структура запитів
Get:
{home}/api/deliveryTool
{home}/api/editRequires
{home}/api/getLogs
{home}/api/getAdrActualConfig
Post:
{home}/api/getActualConfig
{home}/api/editAdrRequires
{home}/api/clearLogs
Структура json запиту
 
JSON запит обов'язково повинен мати поле token який є строкою.
Якщо додатково потрібно передати данні то додається поле body який є асоціативним масивом.



{
"token": "your_token",
"data": {
    "your_parameter": "some_data"
    }
}



Якщо token невірний або запит створений некоректно сервіс видає помилку 403.

Всі запити потрібно надсилати як application/json на api.
Важливо: під {home} розуміємо доменне ім'я(в більшості випадків "delivery.centr.today")

Приклад: http://delivery.centr.today/api/editRequires


В цьому сервісі є такі запити:

POST editRequires – зміна config файлу з доставками, має body.

POST editAdrRequires – зміна config файлу з тарифами хімії (ADR), має body.

GET getActualConfig – отримання поточного config файлу доставок.

GET getAdrActualConfig – отримання поточного config файлу тарифів хімії (ADR).

GET getLogs – отримання поточного log файлу.

POST clearLogs – очищення log файлу (використовуйте відповідально, бекапу немає)

GET deliveryTool — розрахунок доставлення, має body.
#home/api/deliveryTool
 

Це GET матод. Він приймає в body замовлення та віддає пошти, які підходять по критеріям. Body має таку структуру:


{
    "order_price": 213,		//вартість замовлення
    "opt": 0,             //наявність оптової доставки (0 або 1)
    "products":[]   		//список продуктів в замовленні
}


В products записується список продуктів, кожний продукт виглядає так:


{
        "sku": "56789",                 //номер товара
        "weight": 40,			//вага одної одиниці int|float
        "length":10,			//габарити int|float
        "width":15,		        //габарити int|float
        "height":35,			//габарити int|float
        "specdel": 123,		        //спеціальна доставка int|float|null
        "quantity": 1,			//кількість int
        "divider": null,                 //дільник для труб int|float|null
        "special_product": "pool", //спеціальний продукт string|null
        "ADR_category": "A",       //категорія хімії: "A", "B", "C" або "N" (звичайний товар)
        "sku_sum": 309.5           //сума по рядку товару (брутто для роздрібу, нетто для опту)
}


На виході маємо список:


[{"del_id":2,"price":120}, {"del_id":3,"price":400}]




Оптова доставка 
opt замовлення може бути 0 (наявний) або 1 (відсутній). Якщо вона наявна, то ціна доставки дорівнює
ціні опта в конфігу (див. EditRequires).


Спеціальна доставка
specdel продукту може бути int|float|null. Якщо спецдоставки немає ні в одного продукту,
 то виводиться вказана в config ціна доставки.
- Якщо один продукт має спецдоставку не null, то ціна доставки незалежно від пошти є ціна спецдоставки.
- Якщо в замовленні є декілька продуктів зі спецдоставкою,
то ціна доставки є найбільшою ціною спецдоставки серед продуктів.
- Якщо ціна замовлення підходить під критерій pricefreedel (див. EditRequires),
 але є продукт(и) зі спецдоставкою, то ціна доставки дорівнює ціні спецдоставки.
- Якщо ціна окремої доставки в конфігу дорівнює 0 (нулю), то на неї не впливає ціна спецдоставки. Ціна доставки залишаеться 0 (нуль).



Труби
Для труб введений параметр divider, за замовчуванням він дорівнює null або 0 (нуль).
Якщо даний товар є трубою, параметр зазначає довжину одного відрізка труби (в метрах).
Довжина труби (в метрах) має бути передана як quantity.
*Також важливо: quantity буде округлена щоб націло ділитися divider в більшу сторону, тобто якщо quantity = 7, а divider=3, quantity буде округлена і стане дорівнювати 9.


Спеціальний продукт 
special_product може бути string (наявний) або null (відсутній). Якщо він наявний, то ціна замовлення залежить від умов special_products для цього імені спец.товару. (див. EditRequires)


Приклад готового body.

"body":{
    "order_price": 213,
    "opt": 0,
    "products":[
        {
        "sku": "56789",
        "weight": 31,
        "length":100,
        "width":113,
        "height":15,
        "specdel": null,
        "quantity": 1,
        "divider": null,
        "special_product": "pool"
        },
        {
        "sku": "12312",
        "weight": 10,
        "length":100,
        "width":113,
        "height":15,
        "specdel": null,
        "quantity": 2,
        "divider": null,
        "special_product": none
        }
    ]
}




Версія для розробників
Для отримання проміжних значень розрахунку критеріїв доставки є інструмент #home/api/deliveryToolDev.
Він виводить рельзьтат розрахунку доставки таким чином:



    [[{"del_id":1,"price":123}],{"maxweight":60,"genweight":480,"maxdimweight":11.25,"maxvolume":67500,"genvolume":538650,"maxside":300,"maxsidesum":330}]


Перший елемент списку це саме результат, другий - проміжні данні.
#home/api/editRequires
 


Це POST метод, який змінює config файл. Запит до нього потрібен мати body:
В body є 2 поля:



"body":{
    "mails":{} 				//список способів доставки
    "special_products": {},  //модифікатори ціни для спец.товарів
    "pricefreedel": 500,
    "opt_price": 30,
    "opt_pricefreedel": 1000
}


pricefreedel – це параметр, що є числом(float|int), якщо вартість замовлення перевищує або дорівнює pricefreedel,
 то доставка для кожної пошти дорівнює 0 (нуль).

opt_price - число(float|int), ціна доставки для всіх пошт, якщо наявний опт.

opt_pricefreedel - це параметр, що є числом(float|int), якщо вартість замовлення перевищує або дорівнює opt_pricefreedel
і це оптове замовлення, то доставка для кожної пошти дорівнює 0 (нуль).

opt_pricefreedel - це параметр, що є числом(float|int), якщо вартість замовлення перевищує або дорівнює opt_pricefreedel
і це оптове замовлення, то доставка для кожної пошти дорівнює 0 (нуль).

Пошти в mails додаються як асоціативні масиви. Приклад однієї пошти зі списку mails:


"postmat": {						// назва потрібна тільки для вас	str
            "id" : 1,					//id доставки				int
            "message" : "",				//повідомлення				str

            "genweight":null,			        //параметри доставки
            "genvolume":null,
            "maxweight":25,
            "maxvolume": 100,
            "maxdimweight": null,
            "maxside":64,
            "maxsidesum": 145,

            "price": 80				        //вартість доствки		        float|int
}



Приклад списку модифікаторів ціни для спеціальних товарів знаходяться в special_products:


"special_products": {
    "pool" : {
        "1" : {
            "id": 1,
            "maxweight": 30,
            "price": 17
        },
        "2" : {
            "id": 2,
            "maxweight": 50,
            "price": 40
        },
        "3" : {
            "id": 3,
            "maxweight": 70,
            "price": 60
        },
        "4" : {
            "id": 4,
            "maxweight": null,
            "price": 80
        }
    }
}


Таким чином ми змінюємо ціну доставок замовлень де є спец.продукти pool для всіх пошт залежно від критерія maxweight.
Примітка: умови перевіряються з першої до останньої, якщо умова спрацьовує то умови після неї не перевіряються.


Приклад готового body:

"body":{
    "mails": {
        "postXXL": {
            "id": 1,
            "message": "message",
            "genweight": null,
            "genvolume": null,
            "gendimweight": null,
            "maxweight": null,
            "maxvolume": null,
            "maxdimweight": 100,
            "maxside": null,
            "maxsidesum": null,
            "price": 100
        },
        "pikas": {
            "id": 2,
            "message": null,
            "genweight": 100,
            "genvolume": null,
            "gendimweight": null,
            "maxweight": null,
            "maxvolume": null,
            "maxdimweight": null,
            "maxside": 180,
            "maxsidesum": 0,
            "price": 200
        },
        "inpost": {
            "id": 3,
            "message": null,
            "genweight": null,
            "genvolume": null,
            "gendimweight": null,
            "maxweight": 90,
            "maxvolume": 0.9,
            "maxdimweight": null,
            "maxside": 120,
            "maxsidesum": 220,
            "price": 140
        },
        "postmat": {
            "id": 4,
            "message": null,
            "genweight": null,
            "genvolume": null,
            "gendimweight": null,
            "maxweight": 23,
            "maxvolume": 100,
            "maxdimweight": null,
            "maxside": 64,
            "maxsidesum": 145,
            "price": 80
        },
        "pickup": {
            "id": 6,
            "message": null,
            "genweight": null,
            "genvolume": null,
            "gendimweight": null,
            "maxweight": null,
            "maxvolume": null,
            "maxdimweight": null,
            "maxside": null,
            "maxsidesum": null,
            "price": 0
        }
    },
    "special_products": {
        "pool" : {
            "1" : {
                "id": 1,
                "maxweight": 30,
                "price": 17
            },
            "2" : {
                "id": 2,
                "maxweight": 50,
                "price": 40
            },
            "3" : {
                "id": 3,
                "maxweight": 70,
                "price": 60
            },
            "4" : {
                "id": 4,
                "maxweight": null,
                "price": 80
            }
        }
    },
    "pricefreedel": 5000,
    "opt_price": 33,
    "opt_pricefreedel": 1000
}



Параметри доставки в config
Є такі параметри, як
    weight	- вага
    volume	- об’єм
    dimweight	- об’ємна вага (тільки max)
    side	- довжина найбільшої сторони	(тільки max)
    sidesum	- сума сторін				(тільки max)

Назви параметрів використовуються тільки з префіксами gen та max.
Префікс gen позначає спільний параметр для всього замовлення,
max позначає найбільшу величину параметру серед товарів в замовленні.
Самі параметри є float|int|null. Пошта є валідною для замовлення,
коли параметри замовлення не перевищують зазначених параметрів пошти.
Якщо параметр пошти дорівнює null, то у замовлення він може бути будь-яким,
він не враховується при обчисленні.
#home/api/getLogs
 

Це GET метод.
В сервісі є інструмент логування, в який вписуються те, що приходить на  deliveryTool (in) та те,
що було передано (out). Він не має body.
#home/api/getActualConfig
 

Це GET метод, який виводить усе що знаходиться в config. Він не має body.
#home/api/getAdrActualConfig
 

Це GET метод, який повертає поточний config файл з тарифами хімії (ADR). Не має body.
#home/api/editAdrRequires
 

Це POST метод, який змінює config файл з тарифами хімії (ADR). Потребує body.
Файл містить окремі таблиці тарифів для роздрібу (retail) та опту (wholesale).

Структура body:


"body": {
    "cennik_adr": {
        "retail": {
            "1": { "maxweight": 30,   "price": 15,  "del_id": "mstrate_195", "carrier": "Geodis" },
            "2": { "maxweight": 60,   "price": 30,  "del_id": "mstrate_195", "carrier": "Geodis" },
            ...
            "14": { "maxweight": null, "price": 705, "del_id": "mstrate_195", "carrier": "Geodis" }
        },
        "wholesale": {
            "1": { "maxweight": 30,  "price": 18,  "del_id": "mstrate_200", "carrier": "DPD" },
            ...
            "11": { "maxweight": 600, "price": 215, "del_id": "mstrate_195", "carrier": "Geodis" }
        }
    },
    "cennik_adr_palety": {
        "retail": {
            "1": { "maxweight": 40,   "price": 100, "del_id": "mstrate_195", "carrier": "Geodis" },
            ...
            "11": { "maxweight": null, "price": 705, "del_id": "mstrate_195", "carrier": "Geodis" }
        },
        "wholesale": {
            "1": { "maxweight": 50,  "price": 110, "del_id": "mstrate_195", "carrier": "Geodis" },
            ...
            "8": { "maxweight": 600, "price": 201, "del_id": "mstrate_195", "carrier": "Geodis" }
        }
    },
    "cennik_dlinnomery": {
        "1":  { "maxweight": 30,  "price": 30 },
        ...
        "12": { "maxweight": null, "price": 360 }
    }
}



cennik_adr — тариф для хімії групи A та звичайних товарів N (використовується обома алгоритмами).
cennik_adr_palety — тариф для хімії груп B і C (паллетні вантажі).
cennik_dlinnomery — тариф для довгомірів (N з довжиною будь-якої сторони > 150 см). Спільна для роздрібу та опту.

maxweight — верхня межа ваги для рядка тарифу (включно). null означає необмежено (для роздрібу) або що дроблення не потрібне.
del_id — ідентифікатор способу доставки.
carrier — перевізник: "DPD" або "Geodis".

Важливо для оптового тарифу: таблиці wholesale мають скінченний maxweight (наприклад 600 кг).
Якщо вага групи товарів перевищує цей максимум — сервіс автоматично дробить її на шматки
по maxweight і сумує ціни. Зразок конфігу: storage/adrDeliveryRequires.example.json
#home/api/clearLogs
 

Це POST метод, повне очищення логів.
Надвелика вага файла logs може сповільнювати роботу сервіса. Він не має body.