Документація

Telegram-канал з новинами нашого API

Головне

API Dilovod має невелику кількість методів, що подібні роботі з SQL-запитами.

Наше API дозволяе читати/писати майже всі об'єкти бази данних.

Всі бази користувачів однакової структури.

Основні типи об'єктів:

Дані регістрів зазвичай пишуться атоматично системою при проведенні документів.

Актуальні ціни, курси валют, штрихкоди - це все інформаційні регістри.

Залишки товару, заборгованості, обсяги продажів - це все балансові регістри.

Зарезервоані товари, плани закупівель - це акумуляційні регістри.

Опис структури даних можна подивитися за допомогою так званого інструменту розробника

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

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

Замовлення покупця, я к і будь який об'єкт бази даних можна створити методом saveObject

Але є додатковий метод saleOrderCreate більш простий у використанні. Більшість реквізитів замовлення цей метод заповнює автоматично з налаштувань обліку а також може одночасно створювати ТТН.

Приклади використання обох методів наведені в документації.

Яка різниця між додатковими реквізитами та додатковими властивостями об'єктів

Більшість об'єктів системи дозволяє додати користувацькі поля.

Користувацькі поля у Dilovod бувають двох типів - додаткові реквізити і додаткові властивості.

Додаткові властивості

Значення властивостей зберігаються в окремій таблиці і робота з ними дещо складніше ніж з додатковими реквізитами, але за їх допомогою можна організувати зберігання будь якої кількості типів та значень властивостей. Довідники товарів та контрагентів крім загальних властивостей для всих записів можуть мати окремі набори властивостей, що задаються в залежності від категорій товару/контрагенту.

Додаткові реквізити

В довідники товарів та контрагентів можливо додати 3 додаткових реквізити. Ці реквізити будуть доступні для всих записів довіднику. На відміну від додаткових властивостей додаткові реквізити можна вивести у списку довідника та використовувати для відбору та групування даних у більшості звітів. Фактично додаткові реквізити є звичайними реквізитами і їх значення обираються з окремих довідників.

Як створювати документи проведеними (такими що враховуються в обліку)

У методі saveObject є параметр saveType, дивіться детальніше у документації.

Створюю контрагента, але основний телефон, email не встановлюється

Контакні дані контрагента встановлюються в поле details а вже з нього автоматично переносяться у реквізити контрагента phone, email.

Структуру реквізиту details можна подивитися в інструменті розробника, що інтерактивно доступний у карточці контрагента (в документації описано як їм користуватися).

Створюю платіж, але сума платежу не встановлюється

У документах cashIn, cashOut крім реквізитів ще є таблична частина tpAnalytics. Сумма береться автоматично з тоталу по табличній частині. Зверніть увагу, що дані у табличні частини передаются у вигляді масиву з ключами по номерам рядків 0,1,2...

Як отримати залишки товару

Залишки товару бувають складські та вільні.

Складські залишки - всі, що наявні на складі, без урахуванню зарезервованого товару.

Їх можна отримати сформувавши запит типу balance до регістру balanceRegisters.goods (приклад є у документації).

Вільні залишки - залишки з урахуванням зарезервованого товару. Для їх отримання треба самостійно з складскьих залишків відняти зарезервовану кількість товару, яку можна отримати сформувавши запит типу balance до регістру accumulationRegisters.saleOrderControl.

Для того щоб врахувати строк резервування товару у регістрі saleOrderControl можна запитати поле baseDoc.reserveDate

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

Як отримати додаткові категорії товарів (контрагентів)

У кожного товару є поле categories (тип bigint, 64-бітове число).

Кожен біт цього числа відповідає одній додатковій категорії товару. Якщо відповідний біт встановлений у 1, це означає, що товар належить до цієї категорії.

У довіднику категорій товарів існує поле addCatNumber.

У ньому зберігається номер біта (від 1 до 64), який відповідає даній категорії.

ільки категорії, у яких заповнене поле addCatNumber, можуть використовуватися як додаткові.

Кожна така категорія прив’язана до унікального біта у полі товару (послуги) categories.

Кроки алгоритму:

1. Отримати значення categories для товару.
2. Отримати список додаткових категорій, у яких заповнене поле addCatNumber.
3. Для кожної такої категорії:

• обчислити бітову маску: mask = 1 << (addCatNumber - 1)
• виконати бітову перевірку: якщо (categories & mask) != 0, товар належить до цієї категорії.

4. Зібрати та повернути список таких категорій

Приклад

У товару значення поля categories = 18 (двійковий вигляд: 10010)

Є додаткові категорії товарів з addCatNumber = 2 і addCatNumber = 5.

Перевірка:

Товар входить до обох категорій.

Приклад запиту для отримання значення

{  
   "version":"0.25",
   "key":"xxxxxxxxxxxxxxxx",
   "action":"request",
   "params":{  
      "from":"catalogs.goods",
      "fields":{  
         "id":"good",
         "code":"code",
         "category":"mainCategory"
         "categories":"categories"
      }
   }
}

Приклад запиту для отримання кодів додаткових категорій товарів

//Для отримання всих категорій приберіть filters
{
   "version":"0.25",
   "key":"xxxxxxxxxxxxxxxx",
   "action":"request",
   "params":{
      "from":"catalogs.goodsCategories",
      "fields":{
         "id":"categoryId",
         "name":"name",
         "addCatNumber":"addCatNumber"
      },
      "filters":[
         {
            "alias":"addCatNumber",
            "operator":">",
            "value":"0",
         }
      ]
   }
}

Які документи впливають на складські залишки

Щоб зрозуміти які документи вплаивють на той чи інший розділ обліку (регістр) треба:

1. У будь якому документі обрати команду Більше - Розробнику
2. Обрати розділ Усі об'єкти
3. Знайти розділ Регістри балансові
4. Обрати потрібний регістр (наприклад balanceRegisters.goods)
5. У полі registrator буде вказаний перелік всих документів, що впливають на дані обліку

Для цих об'єктів можна налаштувати webhook і відстежувати зміни.

Чи можна через API виконати фіскалізацію чеків

На жаль поки що ні.

Як прискорити виконання запитів

Ось деякі поради:

• де можливо, відключайте збірку посилань у результатах запиту за допомогою параметру assembleLinks. Детальніше
• якщо у запитах типу balance не вказувати дату, то будуть повернуті актуальні залишки, розрахунок яких швидше.
• не використовуйте метод getObject у циклі, якщо потрібне лише читання реквізитів. Замість цього використовуйте прямий запит типу request.
• звернення в декілька потоків заборонене
• замість запиту окремих даних у циклі, користуйтеся різноманітними умовами для відбору ( filters) записів у запитах, щоб отримати дані одним запитом.

Оновлено: 04/12/2025