Статті на: Інтеграції

API Dilovod

Запитання-відповіді
Telegram-канал

Dilovod надає користувачам можливість для зовнішнього підключення до своєї бази даних (API для читання та запису даних). Цей механізм дозволяє організувати обмін даними зі своїм інтернет-магазином, сервісом, програмним продуктом.


Адрес шлюза: https://api.dilovod.ua
Метод: POST
Имя параметра POST: "packet"
Кодировка: utf-8
Значение параметра POST: пакет в формате JSON
'Content-Type': 'application/x-www-form-urlencoded'

Підключення



Для підключення до бази даних, налаштування доступу до даних необхідно Dilovod налаштувати вузол API і згенерувати Ключ доступу API (key), який передається при кожному зверненні до сервера Dilovod.

Увійдіть до програми з правами Адміністратору. Перейдіть до меню Сервіс - Підключення до API Dilovod та додайте новий вузол.



Одночасно зі створенням вузла API система автоматично створює окрему роль у довіднику "Ролі користувачів" для керування доступом до даних через цей вузол. Перед початком роботи обов'язково налаштуйте доступ у пункті меню Сервіс - Ролі користувачів.

Багатопотокове звернення до API не підтримується.

Доступ до даних обмежений правами вузла API. За замовчуванням доступ до всіх даних заборонено.

WebHook



У вузлі API передбачена можливість налаштування списку типів об'єктів при зміні яких буде надіслано Webhook (повідомлення про зміну даних на стороні Dilovod) на вказану адресу.
Для налаштування веб-хуку вкажіть URL на який будуть надсилатися повідомлення.

По вказаному URL в GET параметрі "packet" буде відправлятися повідомлення в форматі json про зміну об'єктів, які вказані у реквізиті налаштування "Імена об'єктів метаданих".



Приклад значення реквізиту "Імена об'єктів метаданих" : catalogs.goods,documents.saleInvoice

WebHook відправляються лише з адреси 88.198.50.253

Для використання веб-хука необхідно перезберегти поточний вузол API, а також завершити поточні сеанси користувачів і знову зайти.

Веб-хук формується тільки для інтерактивних дій користувачів. Зміни внесені в базу даних запитами API не формують веб-хук.

Приклад відповіді веб-хук:
{
	"action":"objectChanged",
	"params":{
		"objectName":"documents.saleOrder",
		"id":"1109100000001038"
	}
}


Створення вузла API з файлу налаштувань




json Приклад файлу для автоматичного створення вузла API

{
"nodeName":{"ru":"Интеграция с PROM.ua","uk":"Інтеграція з PROM.ua"},
"accessRules":{
	"catalogs.persons":"read",
	"catalogs.positions":"write",
	"catalogs.goods":"write"
},
"webHookUrl":"https://mystore.com/webHookUrl/",
"webHookObjects":[
	"catalogs.goods",
	"catalogs.persons"
]
}


Дивись
"Ролі користувачів" у розділі "Управління правами доступа до даних"

Структура даних



Dilovod залишає за собою право самостійно змінювати структуру даних без індивідуального узгодження з користувачами. Ми розуміємо можливі проблеми, пов'язані з внесенням нами змін до структури даних і намагаємося не змінювати (не видаляти, не перейменовувати) існуючі поля об'єктів бази даних. Для баз даних, що використовують API, оновлення, що змінюють структуру даних, виконуються за індивідуальним узгодженням із власником бази даних.

Для перегляду структури даних об'єктів використовуйте інструмент розробника. Для цього необхідно відкрити у базі данних цікавого для вас об’єкту, та вибрати пункт меню Більше -> Розробнику

Для отримання списку об'єктів метаданих та детального опису використовуйте методи listMetadata, getMetadata




Інструмент розробника


Приклад структури даних

Усі бази даних мають однакову структуру даних.

Запит даних



Методи для формування запитів до бази даних бувають двох типів:

Універсальні
getObject, saveObject - отримання та запис даних окремого об’єкту
setDelMark - позначка на видалення окремого об’єкту
request - формування різноманітних запитів до списку об’єктів певного типу, табличним частинам об’єктів та агрегованим даним (залишкам на дату, оборотам за період, актуальним відомостям інформаційних регістрів)

Спеціалізовані
call - різноманітні спеціалізовані методи.

Універсальні методи


Загальна структура універсального запиту

ПараметрОписПриклад значення
versionВерсія API0.25
keyКлюч доступу до API Dilovodkey
clientID NEWID клієнтського додатку для збору статистки використання партнерської інтеграції. Необов'язковий. Формуєтся розробником самостійно.
actionІм'я методу, що викликаєтьсяgetObject, saveObject, setDelMark, request
paramsПараметри методу, що викликається


Приклади

Приклад вибірки усіх даних довіднику клієнтів

var packet = 
{  
   "version":"0.25",
   "key":"xxxxxxxxxxxxxxxx",
   "action":"request",
   "params":{  
      "from":"catalogs.persons",
      "fields":{  
         "id":"person_id",
         "name":"person_name"
      }
   }
}


Приклад виклику на PHP

$packet['key']="xxxxxxxxxxxxxxxx";
$packet['version']="0.25";
$packet['action']="request";
$packet['params']['from']="catalogs.persons";
$packet['params']['fields']=["id"=>"person_id","name"=>"person_name"];

$url = 'https://api.dilovod.ua';

$curl= curl_init($url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($packet));
curl_setopt($curl, CURLOPT_HTTPHEADER, array(
    'Content-Type: application/json',
    'Content-Length: ' . strlen(json_encode($packet))
));



Приклад виклику на Python 3

import requests, logging, json

logging.basicConfig(format = u'%(filename)s[LINE:%(lineno)d]# %(levelname)-8s [%(asctime)s]  %(message)s', level = logging.DEBUG)

url = 'https://api.dilovod.ua'
key = 'xxxxxxxxxxxxxxxx'
version = '0.25'
headers = {'Content-type': 'application/x-www-form-urlencoded'}

packet = {
    'version': version,
    'key': key,
    'action': 'request',
    'params': {
        'from': 'catalogs.persons',
        'fields': {
            'id': 'person_id',
            'name': 'person_name'
        }
    }
}

data = "packet=" + str(json.dumps(packet))
logging.debug(data)

response = requests.post(url, data=data, headers=headers)
received_json_data = json.loads(response.text)
logging.debug(received_json_data)


Формати даних



Тип данихПриклад значення
Дата (Date)2022-09-07 12:09:29
Рядок (varchar)"Рядок"
Мультимовний рядок (multiLangVarchar){"uk": "Рядок", "ru": "Строка"}
Число (varchar)10.25
Булево (boolean)1 або 0
Посилання на інший об’єкт бази даних (link)1103600000000001


Посилання на об’єкт бази даних являє собою число, перші 5 розрядів якого є однаковими для усіх об’єктів одного типу.
Останні 11 розрядів унікальні для кожного об’єкту одного типу.

getObject: приклад отримання даних окремого об’єкту



Повертає дані документу або запису довідника, що містять значення всіх його реквізитів та табличних частин.
Також можливо отримання окремого запису регістру,

Опис параметрів
id - унікальний ідентифікатор запису довідника, документа чи запису регістру.

Метод getObject: приклад отримання даних об’экту

var packet = {  
   "version":"0.25",
   "key":"xxxxxxxxxxxxxxxx",
   "action":"getObject",
   "params":{  
      "id":"1110800000001029",
   }
}


saveObject: збереження даних окремого об’єкту



Зберігає документ, запис довідника чи регістру відомостей із структури даних, що містить значення всіх його реквізитів та табличних частин.

ПараметрОпис
saveTypeРежим збереження документа. Використовується лише для документів. Необов'язковий. 0 - SAVE (збереження без проведення, лише для непроведених документів); 1 - REGISTER (збереження з проведенням/c переведенням); 2 - UNREGISTER (збереження зі скасуванням проведення). Значення за замовчанням 0
headerСтруктура даних містить значення реквізитів шапки об'єкта з ключами за іменами реквізитів об'єкта, що зберігається. Обов'язково має містити ключ "id". У значенні цього ключа при збереженні нового запису довідника або документа потрібно вказати ім'я метаданих, а при повторному збереженні існуючого об'єкта - унікальний ідентифікатор запису довідника або документа.
tablePartsСтруктура даних що містить дані табличних частин об'єкта з ключами за іменами табличних частин.



У разі створення нового об’єкту у поле "header": {"id":"catalogs.goods"} передається його тип
У разі перезапису існуючого об’єкту у поле "header": {"id":1100100000001008} передається його ID

При створенні нового об'єкту значення реквізитів, що не вказані в запиті залишаються пустими, або встановлюються з значень за замовчуванням, що залежать від налаштувань конкретної бази даних.
При перезапису об'єкту значення реквізитів, що не вказані в запиті не змінюються.

Значення, що повертається

ID об'єкту - у разі вдалого виконання, інакше - зміст помилки
(В API версії 0.1: ok - у разі успішного виконання, інакше - зміст помилки)

Приклади

Метод saveObject: приклад збереження нової одиниці виміру
{  
   "version":"0.25",
   "key":"xxxxxxxxxxxxxxxx",
   "action":"saveObject",
   "params":{  
      "header":{  
         "id":"catalogs.units",
         "code":"psi",
         "name":{  
            "ru":"\u041f\u041d\u0414",
            "uk":"\u041f\u041d\u0414"
         }
      }
   }
}





Метод saveObject: приклад збереження нового клієнту
* Контакні дані контрагента встановлюються в поле `details` а вже з нього автоматично переносяться у реквізити контрагента phone, emeil.
Структуру реквізиту details можна подивитися в інструменті розробника, що інтерактивно доступний у карточці контрагента.

{
"version":"0.25",
"key":"xxxxxxxxxxxxxxxx",
"action":"saveObject",
"params":
   {"header":
      {
         "id":"catalogs.persons",
         "name":{"ru":"Карпенко М.П."},
         "parent":1100100000001008,
         "personType":1004000000000035,
         "details":(JSON-строка *)]
      }
   }
}


Метод saveObject: приклад збереження нового запису регістру відомостей

{  
   "version":"0.25",
   "key":"xxxxxxxxxxxxxxxx",
   "action":"saveObject",
   "params":{  
      "header":{  
         "id":"informationRegisters.currencyRates",
         "date":"2013-03-13 00:00:00",
         "currencyFrom":"1101200000001001",
         "currencyTo":"1101200000001002",
         "rateType":"1114800000000001",
         "rate":25
      }
   }
}


Метод saveObject: приклад збереження існуючого документа

{  
   "version":"0.25",
   "key":"xxxxxxxxxxxxxxxx",
   "action":"saveObject",
   "params":{  
      "saveType":0, 
      "header":{  
         "id":1110800000001029,
         "date":"2013-03-13 16:05:31",
         "number":"NN00001",
         "firm":1100400000001002,
         "storage":1100700000001001,
         "amountCost":13.48,
         "department":1101900000001001,
         "operationType":1004000000000044
      },
      "tableParts":{  
         "tpGoods":[  
            {  
               "rowNum":1,
               "good":1100300000022632,
               "qty":1,
               "unit":1103600000001025,
               "amountCost":3.48
            },
            {  
               "rowNum":2,
               "good":1100300000022633,
               "qty":3,
               "unit":1103600000001025,
               "amountCost":10
            }
         ]
      }
   }
}


Метод request: Вибірка та агрегація даних



Формує різноманітні запити до списку об’єктів певного типу, табличним частинам об’єктів та агрегованим даним (залишкам на дату, оборотам за період, актуальним відомостям інформаційних регістрів).

Типи об’єктів бази даних \ Тип вибіркипрямий запитsliceLast (зріз актуальних відомостей)balance (залишки на дату)turnover (обороти за період)balanceAndTurnover (початкові та кінцеві залишки + обороти за період)
catalogs.*Х
documents.*Х
informationRegisters.*ХХ
accumulationRegisters.*Х(Х)ХХ
balanceRegisters.*ХХХХ


Структура вибірки будується виходячи з поточної структури даних.

Як переглянути структуру даних описано у розділі Структура даних.

Параметри вибіркиОпис
fromІм'я об'єкта даних або його табличній частині
fieldsПоля джерела даних. Структура, що містить перелік найменувань полів (alias) джерела даних та шляхів до них (dataPath). dataPath може містити як найменування полів джерела даних, так і шлях до їх підлеглих реквізитів (зазначених через крапку).
dimensionsПерелік вимірів для згортання (агрегації) підсумків по ресурсам регістру (аналог SQL.GROUP BY). Масив містить назви вимірів. Не обов’язковий.
filtersУмови відбору даних (аналог SQL.WHERE). Масив містить умови відбору даних, що об'єднані операцією логічним AND. Не обов’язковий. Усі поля, що використовуються в умовах відбору повинні бути присутніми у складі fields.
limitКількість записів, що повертаються (аналог SQL.LIMIT). Не обов’язковий. Можливий варіант виклику у форматі ['offset'=>100,'count'=>100]
multilangЗапит текстових полів для всіх мовних версій. Якщо значення параметра дорівнює true в результаті до імен текстових мультимовних полів буде додано суфікс “__[Код мови]”. Не обов’язковий.


Приклад параметру fields

"fields":
      {  
         "parent.name":"father",
         "parent.parent.name":"grandfather",
         . . . . . .
         "dataPath":"alias"
      }



Приклад параметру filters
Відбір рядків де firm = 1100900000000001 та storage один із списку [ 1100700000000001, 1100700000001002]

"filters":
      [
          {
                  "alias": "firm",
                  "operator": "=",
                  "value":  1100900000000001
           },           
           {
                  "alias": "storage",
                  "operator": "IL",
                  "value": [ 1100700000000001, 1100700000001002]
           },
           . . . . . .
           {
                  "alias":  alias поля по якому выдбувається фільтрація,
                  "operator": Операція порівняння,
                  "value": Значення порівняння
           }      
      ]


Операції порівнянняКоментар
=дорівнює
!=не дорівнює
>більше
>=більше або дорівнює
<менше
<=менше або дорівнює
%містить рядок
!%не містить рядок
ILу списку значень


Додаткові операції порівняння для довідниківКоментар
IHв ієрархії (всередині папки, з урахуванням її підпапок)
!IHне в ієрархії
ILHв ієрархії списку груп (всередині однієї з папок, з урахуванням їх підпапок)
!ILHне в ієрархії списку груп
IPLу списку батьківських груп (для вибору батьківських груп елемента довідника)



request: прямий запит даних



Прямий запит дозволяє отримати дані однієї таблиці бази даних.
Ім'я таблиці відповідає імені об'єкта бази даних або його табличній частині.


Метод request: прямий запит до довідника товарів на PHP

{  
   "version":"0.25",

   "key":"xxxxxxxxxxxxxxxx",
   "action":"request",
   "params":{  
      "from":"catalogs.goods",
      "fields":{  
         "id":"good",
         "code":"code",
         "parent.code":"parentCode"
      },
      "filters":[  
         {  
            "alias":"parentCode",
            "operator":"=",
            "value":101010
         }
      ]
   }
}


Метод request: Прямий запит до довідника товарів на Python 3

import requests, logging, json

logging.basicConfig(format = u'%(filename)s[LINE:%(lineno)d]# %(levelname)-8s [%(asctime)s]  %(message)s', level = logging.DEBUG)


headers = {'Content-type': 'application/x-www-form-urlencoded'}

packet = {
    'version':  '0.25',
    'key': "xxxxxxxxxxxxxxxx"
    'action': 'request',
    'params': {
        'from': 'catalogs.goods',
        'fields': {
            'id': 'id',
            'code': 'code',
            'parent.code': 'parentCode',
            'name': 'name'
        }
    }
}

data = "packet=" + str(json.dumps(packet))
logging.debug(data)

response = requests.post([Адреса шлюзу], data=data, headers=headers)
received_json_data = json.loads(response.text)
logging.debug(received_json_data)




Метод request: прямий запит до табличної частини довідника товарів (до специфікації) на PHP
{  
   "version":"0.25",

   "key":"xxxxxxxxxxxxxxxx",
   "action":"request",
   "params":{  
      "from":"catalogs.goods.tpGoods",
      "fields":{  
         "good:"detail",
         "owner:"product",
         "qty":"qty"
      },
      "filters":[  
         {  
            "alias":"owner",
            "operator":"=",
            "value":1100300000022619
         }
      ]
   }
}



request.balance: Запит залишків на дату



Дозволяє отримати поточний залишок ресурсу по накопичувальному (accumulationRegisters) або балансовому (balanceRegisters) регістру у розрізі його вимірів.
Наприклад - залишок товару, поточну заборгованість, залишок коштів.

При запиті залишків з регістру залишків параметр fields може містити тільки виміри, реквізити вимірів та ресурси регістру. Використання реквізитів регістру не підтримується. У випадку необхідності отримання даних реквізитів регістру використувуйте "прямий запит даних".

Метод request.balance: Запит товарних залишків з відбором товару та згортанням по товару
{  
   "version":"0.25",
   "key":"xxxxxxxxxxxxxxxxxxxxxxxxxxx",
   "action":"request",
   "params":{  
      "from":{  
         "type":"balance",
         "register":"goods",
         "date":"2015-01-01 00:00:00",
         "dimensions":["good","firm","storage"]
      },
      "fields":{  
         "good":"good",
         "good.code":"code",
         "storage":"storage",
         "qty":"qty"
      },

      "filters":[  
      {  
         "alias":"good",
         "operator":"=",
         "value":1100300000022619
      },
      {  
         "alias":"storage",
         "operator":"=",
         "value":1100700000022619
      },
      ]  
}


request.turnover: Запит оборотів за період



Дозволяє отримати обороти ресурсу по накопичувальному (accumulationRegisters) або балансовому (balanceRegisters) регістру у розрізі його вимірів.
Наприклад – суму продажу, надходження грошей, витрати за період.

При запиті оборотів з регістру оборотів або регістру залишків параметр fields може містити тільки виміри, реквізити вимірів та ресурси регістру. Використання реквізитів регістру не підтримується. У випадку необхідності отримання даних реквізитів регістру використувуйте "прямий запит даних".

При запиті оборотів та залишків за регістром оборотів фізичні ресурси регістру замінюються на віртуальні, імена яких складаються з імені фізичного ресурсу та суфіксів Expense, Receipt.

Метод request.turnover: Запит продажів по регістру saleIncomes відбором по товару з ID=1100300000022619, в розрізі товарів, 
з отриманням коду товарів, валюти, суми та кількості продажів, та згортанням по товару та фірмі.
{  
   "version":"0.25",
   "key":"xxxxxxxxxxxxxxxxxxxxxxxxxxx",
   "action":"request",
   "params":{  
      "from":{  
         "type":"turnover",
         "register":"saleIncomes",
         "startDate":"2015-01-01 00:00:00",
         "endDate":"2015-06-30 23:59:59",
         "dimensions":["good","firm"]
      },
      "fields":{
         "firm":"firm",  
         "good":"good",
         "good.code":"code",
         "amountReciept":"amountReciept",
         "amountExpence":"amountExpence"
      },

      "filters":[  
            {  
               "alias":"good",
               "operator":"=",
               "value":1100300000022619
            }
      ] 
   }
}




request.balanceAndTurnover: Запит оборотів та залишків за період



Дозволяє отримати початковий і кінцевий залишок, а також обороти ресурсу по накопичувальному (accumulationRegisters) або балансового (balanceRegisters) регістру у розрізі його вимірів. Наприклад - залишки та обороти товару, коштів.

При запиті оборотів та залишків з регістру залишків параметр fields може містити тільки виміри, реквізити вимірів та ресурси регістру. Використання реквізитів регістру не підтримується. У випадку необхідності отримання даних реквізитів регістру використувуйте "прямий запит даних".

При запиті оборотів та залишків за регістром залишків фізичні ресурси регістру замінюються на віртуальні, імена яких складаються з імені фізичного ресурсу та суфіксів Start, Expense, Receipt, Final.

Так, у прикладі, наведеному нижче, фізичному ресурсу qty відповідають віртуальні ресурси

qtyStart - початковий залишок
qtyReceipt - надходження
qtyExpense - витрата
qtyFinal - кінцевий залишок


Метод request.balanceAndTurnover: Запит товарних залишків, та кількості що надійшла та вибула з відбором товару
{  
   "version":"0.25",
   "key":"xxxxxxxxxxxxxxxxxxxxxxxxxxx",
   "action":"request",
   "params":{  
      "from":{  
         "type":"balanceAndTurnover",
         "register":"goods",
         "startDate":"2015-01-01 00:00:00",
         "endDate":"2015-06-30 23:59:59"
      },
      "fields":{  
         "good":"good",
         "good.code":"code",
         "qtyStart":"qtyStart",
         "qtyReceipt":"qtyReceipt",
         "qtyExpense":"qtyExpense",
         "qtyFinal":"qtyFinal"
      },

      "filters":[  
         {  
            "alias":"good",
            "operator":"=",
            "value":1100300000022619
         }
      ]   
   }
}



Метод request.balanceAndTurnover: Запит оплати, відвантаження та боргу з відбором на замовлення у валюті продажу
{  
   "version":"0.25",
   "key":"xxxxxxxxxxxxxxxxxxxxxxxxxxx",
   "action":"request",
   "params":{  
      "from":{  
         "type":"balanceAndTurnover",
         "register":"buyers",
         "startDate":"2017-01-01 00:00:00",
         "endDate":"2017-01-31 23:59:59"
      },
      "fields":{  
         "person":"person",
         "contract":"contract",
         "amountCurStart":"amountCurStart",
         "amountCurReceipt":"shipment",
         "amountCurExpense":"payment",
         "amountCurFinal":"amountCurFinal"
      },

      "filters":[  
         {  
            "alias":"contract",
            "operator":"=",
            "value":1179200000022629
         }
      ]
   }
}



Метод request.sliceLast: Запит зрізу актуальних значень регістру відомостей



Дозволяє отримати актуальні значення періодичних регістрів відомостей (informationRegisters) на певну дату.
Періодичні регістри використовуються для зберігання інформації в розрізі вимірювань регістру та прив'язки до моменту часу.
Наприклад – ціни, курси валют, ставки податків.



Метод request.sliceLast: Отримання цін продажу на певну дату з відбором по категорії цін
{  
   "version":"0.25",
   "key":"xxxxxxxxxxxxxxxxxxxxxxxxxxx",
   "action":"request",
   "params":{  
      "from":{  
         "type":"sliceLast",
         "register":"goodsPrices",
         "date":"2015-07-28 11:38:33"
      },
      "fields":{  
         "good":"good",
         "good.code":"code",
         "priceType":"priceType",
         "price":"price",
         "markup":"markup",
         "currency":"currency"
      },
      "filters":[
            {  
               "alias":"priceType",
               "operator":"=",
               "value":1101300000001002
            } 
       ]
   }
}




setDelMark: встановлення позначки видалення документа або запису довідника



При помітці видалення проведеного документа проводиться автоматична скасування його проводок.

При позначці видалення групи довідника проводиться автоматична позначка видалення всіх підлеглих елементів.

Параметр id - унікальний ідентифікатор запису довідника або документа.


Метод setDelMark: приклад встановлення позначки на видалення об'єкта

{  
   "version":"0.25",
   "key":"xxxxxxxxxxxxxxxx",
   "action":"setDelMark",
   "params": {
       "header": {"id":"1110800000001029"}
    }
}


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


Для прискорення виконання запитів в деяких випадках можливо отримувати відповідь без збірки посилань.
Тобто будуть повертатися тільки ID об'єктів, що не містять їх представлень (назв).
Для цього треба в структуру параметру params додати значення assembleLinks = false
В цьому випадку структура відповіді також змінюється.


Приклад запиту без збірки посилань (assembleLinks = false)

{
  "version": "0.15",
  "key": ""xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "action"": "request",
  "params": {
    "assembleLinks": false,
    "from": {
      "type": "balance",
      "register": "goods",
    },
    "fields": {
        "firm": "firm",
        "good": "good",
        "qty": "qty",
        "amount":"amount"
    }
  }
}

Приклад відповіді:
{
    "columns": [
        "firm",
        "good",
        "qty",
        "amount"
    ],
    "data": [
        [
            "1100400000001001",
            "1100300000001001",
            "9968.000",
            "199360.00"
        ],
        [
            "1100400000001001",
            "1100300000001002",
            "963.000",
            "28890.00"
        ]
    ]
}


Спеціалізовані методи



Спеціалізовані методи альтернативні до універсальних методів.
Вони менш універсальні, але натомість більш прості. Типові варіанти інтеграції з використанням цих методів будуть виконуватися швидше.

Загальна структура спеціалізованого запиту


ПараметрОписПриклад значення
versionВерсія API0.25
keyКлюч доступуkey
actionІм'я методу, що викликаєтьсяcall
paramsПараметри методу, що викликається{ "method": method name, "arguments": { }}



saleOrderCreate: створення замовлення покупця



Параметри шапки замовлення

ПараметрТипЗначення за замовчуваннямНазва поля
datedatetimeПоточна датаДата замовлення
numbervarchar (10)АвтоНомер документа
presentationmultiLangVarchar (80) (ru,uk)АвтоНайменування замовлення
userPresentationbooleanПустеОзнака зміни назви замовлення
postedbooleanfalseПроведено
firmcatalogs.firmsАвтоПідприємець (організація)
businesscatalogs.businessesАвтоВид бізнесу
storagecatalogs.employees, catalogs.persons, catalogs.storagesАвтоМісце зберігання
personcatalogs.personsКінцевий споживачПокупець
managercatalogs.employeesПустеМенеджер
departmentcatalogs.departmentsАвтоПідрозділ
detailsvarchar (100)ПустеКонтактні дані покупця. Видно у замовленні у разі якщо покупець "Кінцевий споживач"
currencycatalogs.currencyАвтоВалюта замовлення
paymentFormcatalogs.paymentFormsАвтоФорма оплати
priceTypecatalogs.priceTypesАвтоКатегорія цін
statecatalogs.statesНовийСтатус замовлення
deliveryPointcatalogs.deliveryPointsПустеТочка доставки
cashAccountcatalogs.cashAccountsАвтоБанківський рахунок
tradeChanelcatalogs.tradeChanelsПустеКанал продажів
remarkvarchar (150)ПустеПримітка внутрішня
remarkFromPersonvarchar (100)ПустеПримітка від покупця
remarkForPersonvarchar (100)ПустеПримітка покупцю
deliveryMethodcatalogs.deliveryMethodsСаомовивізПереважний спосіб доставки. При створенні ТТН наявність значення обов'язкова
deliveryRemarkvarchar (100)ПустеПримітка щодо доставки
taxAccountbooleanАвтоВключений в податковий облік
taxIncludedbooleantrueПодатки включені у ціну
contractcatalogs.contractsПустеУгода
contactcatalogs.contactsПустеКонтактна особа
ratedecimal (9:4)АвтоВалютний курс
discountPercentcatalogs.contacts0Додаткова знижка
supplyDatedatetimeПустеТермін поставки
reserveDatedatetimeПустеЗарезервовано до
payBeforedatetimeПустеСплатити до




Параметри табличної частини Товари (goods)

ПараметрТипЗначення за замовчуваннямНазва поля
goodcatalogs.goodsОбов'язкове, якщо не зазначений productNumТовар / услуга
productNumvarchar (30)Обов'язкове, якщо не зазначений goodАртикул
pricedecimal (14:5)0Цена
qtydecimal (12:3)Обов'язковеКоличество
unitcatalogs.unitsАвтоЕдиница измерения
discountdecimal (11:2)0Сумма скидки
remarkvarchar (150)ПустеПримечание
vatTaxcatalogs.taxesАвтоСтавка НДС
vatAmountdecimal (11:2)АвтоСумма НДС


Створення ТТН


Для створення ТТН в метод saleOrderCreate необхідно додатково передати параметр deliveryData. Структура цього параметру залежить від типу службу доставки. Тип служби доставки вказується при налаштуванні методу доставки у додатку Dilovod.
Частина значень параметрів мають значення за замовчуванням, що налаштовуються у методі доставки. Для створення ТТН метод доставки обов'язково повинен бути вказаний в параметрах saleOrderCreate.

Структура параметру deliveryData у випадку коли ТТН вже створено в кабінеті Нової Пошти
ТТН буде автоматично створена у Dilovod. Її дані будуть автоматично синхронизовані при першому відкритті у Dilovod. Потребує налаштування інтеграції з Нова Пошта на стороні Dilovod.

ПараметрТипЗначення за замовчуваннямНазва поля
Refvarchar(36)Ідентификатор експрес-накладної
IntDocNumbervarchar(36)Номер експрес-накладної


Структура параметру deliveryData у випадку коли при завантаженні замовлення необхідно створити ТТН в кабінеті Нової Пошти
Параметр
Тип значення
Значення за замовчуванням
Назва поля
PayerTypevarchar(36)З налаштуваньТип платника (Sender, Recipient, ThirdPerson)
PaymentMethodvarchar(36)З налаштуваньФорма розрахунку (Cash, NonCash)
CargoTypevarchar(36)З налаштуваньТип вантажу (Cargo, Documents)
VolumeGeneralvarchar(36)З налаштуваньЗагальний об'єм, м.куб (min - 0.0004), обов'язково зазначати, якщо не передається параметр OptionsSeat
Weightvarchar(36)З налаштуваньФактична вага, в кг min - 0,1
ServiceTypevarchar(36)З налаштуваньТехнологія доставки DoorsDoors, DoorsWarehouse, WarehouseWarehouse, WarehouseDoors
SeatsAmountvarchar(36)З налаштуваньКількість місць відправлення, ціле число
Descriptionvarchar(36)З налаштуваньТекстове поле, вводиться для додаткогвого опису відправлення
Costvarchar(36)З налаштуваньОціночна вартість, ціле число (якщо не зазначити вартість то АРІ автоматично проставить мінімальну оціночну вартість =300.01)
CitySendervarchar(36)З налаштуваньІдентифікатор міста відправника (з кабінету Нової пошти)
Sendervarchar(36)З налаштуваньІдентифікатор відправника (з кабінету Нової пошти)
SenderAddressvarchar(36)З налаштуваньІдентифікатор адреси відправника (з кабінету Нової пошти)
ContactSendervarchar(36)З налаштуваньІдентифікатор контактної особи відправника (з кабінету Нової пошти)
SendersPhonevarchar(36)З налаштуваньТелефон відправника у форматі: +380660000000, 380660000000, 0660000001
CityRecipientvarchar(36)Ідентифікатор міста отримувача (з кабінету Нової пошти)
Recipientvarchar(36)Ідентифікатор отримувача (з кабінету Нової пошти)
RecipientAddressvarchar(36)Ідетнифікатор адреси отримувача/Ідентифікатор поштомату (з кабінету Нової пошти)
ContactRecipientvarchar(36)Ідентифікатор контактної особи отримувача (з кабінету Нової пошти)
RecipientsPhonevarchar(36)Телефон отримувача у форматі: +380660000000, 380660000000, 0660000001
AdditionalInformationvarchar(36)Додаткова інформація про відправлення
BackwardDeliveryDataArray<Object>Масив об'єктів структура яких описана в документації Нової Пошти. Dilovod підтримує поки що 2 cargoType: Money та Documents Приклад значення: "[{""PayerType"":""Sender або Recipient"",""CargoType"": ""Money"",""RedeliveryString"": ""4552"" }]"
OptionsSeatArray<Object>Параметр вантажу для кожного місця відправлення. Вага (кг), Довжина (см), Ширина (см), Висота (см), Об'єм, м³. Об'ємна вага розраховується за формулою (Довжина х Ширина х Висота) / 4000 та порівнюється з фактичною вагою. Більший показник використовується в розрахунках вартості перевезення. Приклад значення: "[{""volumetricVolume"":""10"",""volumetricWidth"":""30"",""volumetricLength"":""30"",""volumetricHeight"":""30"",""weight"":""20""}]"


Метод saleOrderCreate: приклад створення замовлення

{  
   "version":"0.25",
   "key":"xxxxxxxxxxxxxxxx",
   "action":"call",
   "params":{
      "method": "saleOrderCreate",
      "arguments": { 
         "header":{
            "firm ": 1100400000001001,
            "person": 1100100000001001,
            "remarkFromPerson":"call me please",        
         },
         "goods": [
            {"good":1100300000022632, "qty":1},
            {"good":1100300000022876, "qty":2}
         ]
      }
   }
}



listMetadata: Отримання переліку метеданих об'єктів


Для отримання списку всих довідників, документів, регістрів сисстеми.
{  
   "version":"0.25",
   "key":"xxxxxxxxxxxxxxxx",
   "action":"listMetadata",
   "params": {
        "lang": "uk"
    }
}


Приклад відповіді
{
  "catalogs.persons": {
      "id": "1000000000001249",
      "idPrefix": "11001",
      "presentation": "Організації та фізичні особи"
  },
  "catalogs.goods": {
      "id": "1000000000001258",
      "idPrefix": "11003",
      "presentation": "Товари та послуги"
  },
  "catalogs.roles": {
      "id": "1000000000001267",
      "idPrefix": "10007",
      "presentation": "Ролі"
  },
  ...
}



getMetadata: Отримання інформації про об'єкт метаданих


Для отримання опису реквізитів довідників, документів, регістрів сисстеми.

Отримання інформації про об'єкт метаданих за назвою
{
    "version": "0.25",
    "key": "xxxxxxxxxxxxxxxx",
    "action": "getMetadata",
    "params": {
        "objectName": "catalogs.units",
         "lang": "uk" // необов'язковий параметр. За замовчуванням "uk"
    }
}


Отримання інформації пр об'єкт метаданих за його ID
{
    "version": "0.25",
    "key": "xxxxxxxxxxxxxxxx",
    "action": "getMetadata",
    "params": {
        "objectId": "1000000000001249"  //objectId можно отримати методом listMetadata     
    }
}


Приклад відповіді
{
    "name": "catalogs.persons",
    "presentation": "Контрагент",
    "listPresentation": "Контрагенти",
    "idPrefix": "11001",
    "hierarchyType": "groups",
    "autoNumeration": 1,
    // перелік реквізитів
    "reqs": {...},
    // елементи створені в БД за замовчуванням 
    "predefined": {
        "endUser": 1100100000000001,
        "purchaseWithoutDoc": 1100100000000002,
        "staff": 1100100000000003
    }
}


getStatistic: Отримання статистики партнерської інтеграції



ПараметрТипЗначення за замовчуваннямНазва поля
typevarcharpartnersIntegrationsТип запиту
dateFromdatetimeАвтоДата початку
dateTodatetimeАвтоДата завершення
partnerAPIkeyvarchar (36)АвтоКлюч доступу до даних партнерскього кабінету (Надається Dilovod)



Метод getStatistic: Отримання статистики партнерської інтеграції
{  
   "version":"0.25",
   "key":"xxxxxxxxxxxxxxxx",
   "action":"getStatistic",
   "params": {
       "type": "partnersIntegrations",
       "dateFrom": "2023-06-07 00:00:00",
       "dateTo ": "2023-06-08 00:00:00",
       "partnerAPIkey": "іhgrt4425fd5_sfF",
    }
}


Формат відповіді
ПолеОпис
dateДата, за яку зібрана статистика
methodМетод запиту API
clientIDID клієнтського додатку, що був переданий у запиті API
partnerIntegrationCodeКод партнерської інтеграції (налаштовується у вузлі API)
counterКількість запитів
errorCounterКількість помилок
apiVersionВерсія API
dbObjectТип об'єкту бази даних



Рекомендації щодо обробки на випадки відмови


Ми робимо все можливе для того, щоб забезпечити стабільну роботу нашого API, але рекомендуємо реалізувати чергу для передачі запитів у Dilovod на випадки відмови у процесі обміну.

Оновлено: 26/09/2024

Чи була ця стаття корисною?

Поділіться своїм відгуком

Скасувати

Дякуємо!