Додавання структури в структурований документ

Для роботи з цим методом користувач повинен бути авторизованим .

Метод запиту

HTTPS POST

Content-Type

application/json (тіло запиту/відповіді в json форматі в тілі HTTPS запиту)

URL запиту

https://doc.edin.ua/bdoc/document_type/structure

Параметри, що передаються в URL (разом з адресою методу)

В рядку заголовка (Header) «Set-Cookie» обов’язково передається SID - токен, отриманий при авторизації

Обов’язкові параметри, що передаються в тілі запиту (json)

encoding, id, structure (будь-яка кількість регламентованих полей)

JSON-параметри в тілі HTTPS запиту/відповіді

REQUEST / RESPONSE

Опис json-параметрів запиту та відповіді метода API (об’єкт DocumentStructure)

Таблиця 1 - Опис параметрів об’єкта DocumentStructure

Параметр

Формат

Опис

Об’єкт DocumentStructure

id

long

id структурованого документу

structure

List<DocStructField>

структура документу

version

long

версія структури

status

int

статус документа; «0 - чернетка; 1 - активний; 2 - архівний»

dateUpdate

long

дата оновлення

encodingPattern

Pattern_

шаблон кодування (utf-8|windows-1251)

encoding

String

кодування (за замовчуванням «utf-8»)

Таблиця 2 - Опис параметрів об’єкта DocStructField

Параметр

Формат

Опис

Об’єкт DocStructField

id

String

ідентифікатор елемента, тобто як елемент буде називатися безпосередньо в документі (в XML)

title

String

назва елемента на WEB-формі при заповненні документа

optional

Boolean

визначає необов’язковість заповнення поля

readonly

Boolean

визначає можливість редагування відповідного елемента структури (при встановленому параметрі обов’язкове заповнення параметра default)

attribute

Boolean

при встановленому параметрі відповідний елемент є атрибутом в xml-файлі, при невстановленому - тегом

function

String

задана функція виконання вибірки з довідника або математичних операцій по вже введеним іншим полях документа (updateDictLink і arithmeticOperate)

data

List<DocStructData>

масив об’єктів; правила і можливості щодо заповнення елемента

type

DocStructType

об’єкт; тип структури документа

fields

List<DocStructField>

масив об’єктів; поля для типів елементів «object» і «array»

errors

List<String>

масив; помилки

Таблиця 3 - Опис параметрів об’єкта DocStructData

Параметр

Формат

Опис

Об’єкт DocStructData

index

int

в даному параметрі вказується індекс (id) рядка для масиву значень, нумерація починається з 0

Default

String

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

template

String

в параметрі задається шаблон даних для відповідного елемента документа. У шаблоні поряд з текстом реалізовані можливості: - вказати посилання на системну функцію; - вказати посилання на поле з комплекта або документа; - вказати посилання на довідник, який прив’язаний до комплекту; - вказати посилання на вищестоящий (описаний раніше) елемент документа; - використовувати функції-модифікатори (наприклад, формат дати); Для визначення посилань необхідно укласти посилання в ##. Формат опису посилань - див. параметр ref. Для використання модифікатора в описі посилання використовується | (Вертикальний слеш). За ним йде опис функції-модифікатора з атрибутами. Якщо даний параметр заповнений, елемент документа не редагується користувачем і завжди буде з типом «рядок» незалежно від того, що зазначено в секції type.

ref

String

в параметрі вказується посилання, по якому буде встановлено значення за замовчуванням для елемента документа. На відміну від шаблону, в даному параметрі можна вказати тільки посилання на 1 об’єкт. При вказівці посилання використовуються наступні префікси: - sys - при посиланні на системну функцію - pack - при посиланні на поле з комплекта - xml - при посиланні на тег документа - dict - при посиланні на призначений для користувача довідник із зазначенням ID довідника (dict.14) - user - при посиланні на дані користувача із зазначенням поля з даних користувача (user.fio) - doc - при посиланні на поле з документа - extra - при посиланні на призначене для користувача поле із зазначенням ID поля (extra.12) З системних функцій реалізовано:  - currentDate - отримання поточної дати і часу  - replaceSpace - заміна прогалин в текстовому значенні Додаткова інформація, яка використовується при описі структури документа, може бути отримана з наступних методів (Рауса):  - / bdoc / store / package в повернутому JSON передається: інформація про компанію (Індекс, Область, Район, Населений пункт, Тип населеного пункту, Вулиця, Будинок, Корпус, Квартира (по юр. І фіз. Адресою); банківські реквізити (Назва банку, Розрахунковий рахунок, МФО БИК, кор. рахунок банку, GUID); UUID комплекта (package_uuid)  - / bdoc / store / package / document в повернутому JSON передається UUID документа (document_uuid)

Function

String

задана функція виконання вибірки з довідника або математичних операцій по вже введеним інших полях документа (updateDictLink і arithmeticOperate) Початок і кінець оголошення функції обрамляється символом $. Функції можливо записувати послідовно, наприклад, $ функція1 $$ функція2 $. Також у функціях при вказівці шляхів задається індекс [@index] елемента масиву, в якому викликається ф-ція: [2] - фіксоване значення індексу (індексація починається з «0») [-1] - операція буде виконана над усіма елементами масиву. Функції: updateDictLink - виробляє вибірку з довідника за шаблоном: $updateDictLink(„Акт.Послуги[2].Код“, „code“)$, де Акт.Послуги[2].Код - маршрут до поля, котре потрібно заповнити code зі довідника; code - поле значення довідника, з якого потрібно взяти значення. Якщо тип даних (array) і функція вказана в полі data - то вона буде працювати тільки для зазначеного елемента масиву, наприклад: «function»: «$updateDictLink(„Акт.Послуги[1].Код“, „code“)$» «Пояснення прикладу: при зміні в першому елементі масиву «index»: 1 поля «id»: «Назва» буде виконана функція «$updateDictLink(„Акт.Послуги[1].Код“, „code“)$» яка запише в поле Акт.Послуги[1].Код значення code із довідника.

Якщо функція вказана в самому вузлі field то вона буде працювати для кожного елемента масиву якщо маршрут вказати наступним чином: „Акт.Послуги[@index].Код“- то він буде посилатися на той же елемент масиву в якому функція була викликана; наприклад:»function»: «$updateDictLink(„Акт.Послуги[@index].Код“, „code“)$»

ArithmeticOperate - виконує математичні операції за вже заповненими іншими полями. Шаблон: $arithmeticOperate(resultPath: string, sourcePath1: string, operationType: string, sourcePath2: string)$, де resultPath - шлях до елементу структурованого документа в який потрібно записати результат; sourcePath1 - шлях до елементу структурованого документа в якому міститься перший аргумент для арифметичної операції; operationType - вид операції, можливі значення «+», «-«, «/», «*»; sourcePath2 - шлях до елементу структурованого документа в якому міститься другий аргумент для арифметичної операції (sourcePath2 може бути відсутнім);

Таблиця 4 - Опис параметрів об’єкта DocStructType

Параметр

Формат

Опис

Об’єкт DocStructType

object

Object

об’єкт; елемент, який є вузлом, структурою зі своїми полями

array

DocFieldTypeArray

об’єкт; елемент, який є таблицею або масивом значень зі своїми полями

number

DocFieldTypeNumeric

об’єкт; числові значення зі знаком і символ розділювача числа в дробовій формі

string

DocFieldTypeString

об’єкт; текстові значення

date

DocFieldTypeDate

об’єкт; дата без часу

time

DocFieldTypeTime

об’єкт; час

aEnum

List<DocFieldTypeEnum>

масив об’єктів; список

Об’єкт DocFieldTypeString

length

Integer

кількість символів

minLength

Integer

мінімальна кількість символів (мінімум 1)

maxLength

Integer

максимальна кількість символів (максимум 9999)

regexp

String

регулярний вираз

case

String

регістр - вказується, в якому регістрі використовувати рядок (upper, lower, camel)

Об’єкт DocFieldTypeArray

minLength

int

мінімальна кількість рядків (мінімум 1)

maxLength

int

максимальна кількість рядків (максимум 9999)

Об’єкт DocFieldTypeNumeric

type

String

тип числа

positive

boolean

додатне число

negative

boolean

від’ємне число

decimal

int

кількість цифр після коми

Об’єкт DocFieldTypeDate

format

String

формат дати, де Y - рік, M - місяць, D - день

Об’єкт DocFieldTypeTime

format

String

формат часу, де H - година, M - хвилина, S - секунда; при цьому H використовується для 24-годинного формату, h - для 12-годинного формату

Об’єкт DocFieldTypeEnum

value

String

значення; значення, яке буде додано в тег

name

String

назва; відображувана назва значення


Приклади

Приклад тіла запиту (json):

{
  "encoding": "utf-8",
  "id": 2393,
  "status": 1,
  "structure": [
    {
      "id": "Акт",
      "title": "АКТ приймання-передачі наданих послуг",
      "optional": true,
      "readonly": false,
      "attribute": false,
      "type": {
        "object": {}
      },
      "fields": [
        {
          "id": "Назва",
          "title": "Найменування робіт, послуг",
          "optional": false,
          "readonly": false,
          "attribute": true,
          "data": [
            {
              "index": 3
            }
          ],
          "type": {
            "enum": []
          }
        },
        {
          "id": "Послуги",
          "title": "Виконавцем були виконані наступні роботи (надані такі послуги):",
          "optional": false,
          "readonly": false,
          "attribute": true,
          "type": {
            "array": {
              "minLength": 1,
              "maxLength": 10
            }
          },
          "fields": [
            {
              "id": "Назва",
              "title": "Найменування робіт, послуг",
              "optional": false,
              "readonly": false,
              "attribute": true,
              "function": "$updateDictLink('Акт.Послуги[@index].Код', 'code')$",
              "data": [
                {
                  "index": -1
                }
              ],
              "type": {
                "enum": []
              }
            },
            {
              "id": "Код",
              "title": "Код",
              "optional": true,
              "readonly": true,
              "attribute": true,
              "type": {
                "string": {
                  "length": 50,
                  "minLength": 1,
                  "maxLength": 50
                }
              }
            }
          ]
        }
      ]
    }
  ]
}

Приклад тіла відповіді (json):

{
  "id": 2393,
  "structure": [
    {
      "id": "Акт",
      "title": "АКТ приймання-передачі наданих послуг",
      "optional": true,
      "readonly": false,
      "attribute": false,
      "type": {
        "object": {}
      },
      "fields": [
        {
          "id": "Назва",
          "title": "Найменування робіт, послуг",
          "optional": false,
          "readonly": false,
          "attribute": true,
          "data": [
            {
              "index": 3
            }
          ],
          "type": {
            "enum": []
          }
        },
        {
          "id": "Послуги",
          "title": "Виконавцем були виконані наступні роботи (надані такі послуги):",
          "optional": false,
          "readonly": false,
          "attribute": true,
          "type": {
            "array": {
              "minLength": 1,
              "maxLength": 10
            }
          },
          "fields": [
            {
              "id": "Назва",
              "title": "Найменування робіт, послуг",
              "optional": false,
              "readonly": false,
              "attribute": true,
              "function": "$updateDictLink('Акт.Послуги[@index].Код', 'code')$",
              "data": [
                {
                  "index": -1
                }
              ],
              "type": {
                "enum": []
              }
            },
            {
              "id": "Код",
              "title": "Код",
              "optional": true,
              "readonly": true,
              "attribute": true,
              "type": {
                "string": {
                  "length": 50,
                  "minLength": 1,
                  "maxLength": 50
                }
              }
            }
          ]
        }
      ]
    }
  ],
  "version": 2,
  "status": 1,
  "dateUpdate": 1557935263,
  "encoding": "utf-8"
}