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 та додайте новий вузол.

WebHook

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

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

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

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

Приклад відповіді веб-хук:

{
	"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"
]
}

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

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

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

Запит даних

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

Універсальні

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

Спеціалізовані

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

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

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

Приклади

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

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)

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

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

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

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

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

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

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

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

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

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

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

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: Вибірка та агрегація даних

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

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

Приклад параметру 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": Значення порівняння
           }      
      ]

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) регістру у розрізі його вимірів.
Наприклад - залишок товару, поточну заборгованість, залишок коштів.

Метод 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) регістру у розрізі його вимірів.
Наприклад – суму продажу, надходження грошей, витрати за період.

Метод 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) регістру у розрізі його вимірів. Наприклад - залишки та обороти товару, коштів.

Так, у прикладі, наведеному нижче, фізичному ресурсу 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"
        ]
    ]
}

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

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

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

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

Параметри шапки замовлення (params -> arguments-> header)

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

Створення ТТН (params -> arguments-> placement)

Автоматичне розміщення замовлення. Система розраховує залишки товарів і формує документ saleOrderPlacement, який резервує товар під замовлення, або планує закупівлю потрібної кількості товару.

Створення ТТН (params -> arguments-> deliveryData)

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

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

Структура параметру deliveryData у випадку коли при завантаженні замовлення необхідно створити ТТН в кабінеті Нової Пошти

Метод 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}
         ],
         "placement": [
            {"autoPlacement": true}
         ]
      }
   }
}

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: Отримання статистики партнерської інтеграції

Метод 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",
    }
}

Формат відповіді

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

Оновлено: 03/07/2025