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

Підключення

WebHook

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

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

Запит даних

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

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

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)

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

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

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

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

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

Метод 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: Запит залишків на дату

Метод 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: Запит оборотів за період

Метод 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: Запит оборотів та залишків за період

Метод 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: Запит зрізу актуальних значень регістру відомостей

Метод 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: встановлення позначки видалення документа або запису довідника

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

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

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

Приклад запиту без збірки посилань (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: створення замовлення покупця

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

Параметр

Тип значення

Значення за замовчуванням

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

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

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

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