В Device Manager (далі ДМ) доступна можливість отримувати друкований чек в кількох доступних форматах для збереження чи подальшого друку.
В чек можна додавати різну інформацію наприклад QR чи штрих коди або просто додатковий текст.
Додатково є можливість змінювати друковані форми чеків та звітів під власні потреби та побажання що не суперечать вимогам до формату чеків згідно чинного законодавства.
Наприклад змінити формат відображення певних даних в чеку або місце їх розташування, додати картинки чи логотип, прибрати зайві службові поля, які не є обов'язковими за вимогами законодавства, або додати більше інформації в чек, наприклад відображення до товару його суми після застосування знижок.
Загально можливості по кастомізації чеків можна поділити на 2 категорії:
Які форми можна отримати із застосунку при фіскалізації чеків або звітів:
.png);Отримати друковану форму можливо при виконанні завдань по ПРРО:
"task": 1);"task": 2);"task": 3);"task": 4);"task": 5);"task": 10);"task": 11);"task": 12);"task": 13);"task": 14);"task": 15);"task": 16).У випадку виконання завдань:
"task": 22);"task": 23);Доповлення чеку додатковою інформацією доступно лише для чеку на продаж ("task": 1) та повернення ("task": 2). Інші документи (наприклад лотерейний білет, гарантійний талон, квиток тощо.) друкуються через нефіскальний службовий звіт ("task": 5).
Повне редагування форм доступно для:
/dm/vchasno-kasa/api/v1/doc.Редагування не доступне для:
Нижче буде описано як можна першим чи другим способом доповнити або змінити формат чеків або друкувати додаткові дані.
В разі потреби змінити формат чеків чи звітів є користувацькі друковані форми, які застосовуються для всіх створених ПРРО та принтерів в додатку після завантаження через сторінку "Налаштування" в блоці "Налаштування друкованих форм" власного файлу з XML розміткою друкованих форм, або за допомогою API по ендпоінту POST /dm/vchasno-kasa/api/v1/settings. Файл з формами потрібно передати в base64 в значенні ключа "pf_custom" в json body запиту.
ДМ, якщо файлу із користувацькими формами не було завантажено використовує загальний файл розмітки який може змінюватись та оновлюватись з виходом нових релізів додатку.
Отримати даний файл з ДМ можна по ендпоінту:
http://localhost:3939/dm/vchasno-kasa/api/v1/settings/printforms
Якщо було завантажено файл з користувацькими друкованими формами - метод поверне саме файл з користувацькими формами, а не за замовчуванням.
XML файл розмітки має власну структуру, теги та атрибути згідно яких заповнюються потрібні дані у визначеному порядку в даному файлі друкованих форм.
Для заповнення форми більшою мірою використовуються дані які повертаються в JSON відповіді на виконане завдання по ПРРО, відповідно всі дані які є в json відповіді на конкретне завдання доступні для відображення в візуалізації чеку чи звіту.
Також можливо вказувати власні дані:
userdata1, userdata2 та userdata3.Що змінити використовуючи користувацькі форми наразі не є можливим:
<PrintForms> - root елемент в якому розміщені форми для кожного з чеків/звітів.
Структура тегу <PrintForms>
<GlobalSettings> - тег з глобальними налаштуваннями для всіх форм.<CheckForm> - тег з даними розмітки для конкретного чеку. Представлений в форматі: CheckNForm"task") по ПРРО по якому доступна друкована форма, наприклад всередині елементу <Check1Form> знаходиться вся розмітка чеку на продаж("task": 1)Атрибути тегу <GlobalSettings>
| Назва | Опис | Формат | Обов'язковий |
|---|---|---|---|
| decimalseparator | Розділювач для десяткових чисел для відображення в чеку. За замовуванням використовується кома(,) | Будь який спец символ | + |
Структура тегу <CheckForm>
<doc> - тег з розміщенням структури конкретного документу.Атрибути тегу <doc> - розмітка документу.
| Назва | Опис | Формат | Обов'язковий |
|---|---|---|---|
| ver | Версія форми документу. Наразі не використовується та зважди = 1. | Будь яке цілочисельне значення | + |
<doc> - розмітка документу.<obj>)<obj path=".->info->printinfo"/>
тег для переходу між контекстом JSON структури відповіді по завданню (task). Наприклад якщо потрібно з кореня json перейти в інший об'єкт для того щоб відобразити потрібні дані які є в цьому об'єкті, або повернутись з одного об'єкту в інший згідно структури вкладеності JSON.
Атрибути:
path - шлях до потрібного контексту."." - поточний контекст".." - піднятись на рівень вище по контексту"<назва контексту>" - перейти в контекст із заданою назвою.Приклади використання:
path=".->info->printinfo" - залишаючись у поточному контексті перейти в контекст "info", а з нього в контекст "printinfo".
path=".." - перейти на попередній контекст, відносно поточного.
<p1/>)(<p1></p1>).тег для відображення рядка з одним вибраним параметром з JSON відповіді або відображення рядка з кількома параметрами з JSON відповіді. Можна використовувати також для відображення сталого тексту.
Атрибути:
f1 - текстовий рядок для форматування виведення параметру з JSON. Використовується тільки для не парного тегу <p1/>. Обов'язковий параметр.f - текстовий рядок для форматування виведення параметрів з JSON. Використовується тільки для парного тегу <p1></p1>. Обов'язковий параметр.arg1 - найменування параметра з поточного контексту JSON для виведення (можна використовувати переходи по контексту JSON ".." і "->"). Використовується тільки для не парного тегу <p1/>. Необов'язковий параметр.a - вирівнювання тексту. Можливі значення center, left, right. За замовчуванням center. Необов'язковий параметр.fill - аргумент який визначає автозаповенння рядка визначеними симовлами, якщо текст менший за розмір стрічки. За замовчуванням значення порожнє. Необов'язковий параметр.sep - символ або символи, які будуть друкуватися на початку кожного рядка і після перенесення на новий на новий рядок. Необов'язковий параметр. За замовчуванням значення порожнє.fw - ширина тексту. Доступні значення 1 та 2. Працює тільки в комбінації з однаковим значенням висоти. За замовчуванням 1. Необов'язковий параметр.fh - висота тексту. Доступні значення 1 та 2. Працює тільки в комбінації з однаковим значенням ширини. За замовчуванням 1. Необов'язковий параметр.wd - ширина рядку по кількості символів. За замовчуванням рівна ширині в налаштуваннях форм. Необов'язковий параметр.by_word - перенесення по словам на новий рядок, якщо слово не вмістилось в поточний рядок. Можливі значення: 0 - не переносити, перенесення по буквам, 1 - переносити, перенесення по словам. За замовчуванням 0. Необов'язковий параметр.fnu - Відображення тексту в тому ж регістрі що і в JSON даних або в текстових даних в формі. За замовчуванням в друкованій формі у вигляді картинки чи pdf весь текст відображається в uppercase. Можливі значення: 0 - весь текст в картинках та pdf буде в uppercase, 1 - текст в тому ж регістрі що в JSON даних або в формі. За замовчуванням 0. Необов'язковий параметр.Для передачі параметрів всередині <p1></p1> використовується тег <arg/>.
Атрибути:
n - порядковий номер аргументу що буде використаний. Обов'язковий параметр.type - тип даних поточного параметру. Доступні значення: float - для десяткових чисел, int - для цілих чисел, str - текстові дані, dt - дата та час.val - ім'я параметра з поточного контексту JSON (можна використовувати переходи «...» і «->»). Обов'язковий параметр.format_in - вхідний формат рядка дати, який в JSON даних. Цей параметр використовується тільки для типу даних dt. Обов'язковий параметр. Наразі підтримується лише формат: "dd-MM-yyyy hh:nn:ss"format_out - вихідний формат рядка дати який буде відображено у формі. Цей параметр використовується тільки для типу даних dt. Необов'язковий параметр. За замовчуванням "dd-MM-yyyy hh:nn:ss"chsign - параметр необхідності відобразити числове значення з протилежним знаком. Наприклад значення знижки в JSON відповіді "disc": 50 а в чеку має бути -50 а не 50. Якщо передано chsign="" - числове значення буде відображено з протилежним знаком, не передано - буде відображено так як в JSON.Приклади використання <p1/>:
<p1 f1="Періодичний звіт (повний)" fw="2" fh="2" by_word="1"/>
<p1 f1="ПН %s" arg1="vat_code" />
Приклади використання <p1></p1>:
<p1 f="%s - %s" fw="1" fh="1">
<arg n="1" type="dt" val="dt_from_fmt" format_in="dd-MM-yyyy hh:nn:ss" format_out="dd.MM.yyyy hh:nn:ss"/>
<arg n="2" type="dt" val="dt_to_fmt" format_in="dd-MM-yyyy hh:nn:ss" format_out="dd.MM.yyyy hh:nn:ss"/>
</p1>
<p1 f="%s" a="left">
<arg n="1" type="dt" val="dt" format_in="dd-MM-yyyy hh:nn:ss" format_out="dd.MM.yyyy hh:nn:ss" />
</p1>
<pc></pc>)Атрибути:
arr - назва масиву даних із поточного контексту JSON для відображення всіх наявних в масиві даних. Обов'язковий параметр.code_aa. <pc arr="code_aa">
<col f1="Акцизна марка" a="left" wd="14"/>
<col f1="%s" a="right" arg1="."/>
<col f1=" " a="right" wd="2"/>
</pc>
Для друку колонок - кожна колонка всередині <pc></pc> друкується за допомогою використання тегів керування колонками <col/> та <col></col>.
Атрибути:
f1 - текстовий рядок для форматування виведення параметру з JSON. Використовується тільки для не парного тегу <col/>. Обов'язковий параметр.f - текстовий рядок для форматування виведення параметрів з JSON. Використовується тільки для парного тегу <col></col>. Обов'язковий параметр.arg1 - найменування параметра з поточного контексту JSON для виведення (можна використовувати переходи по контексту JSON ".." і "->"). Використовується тільки для не парного тегу <col/>. Необов'язковий параметр.a - вирівнювання тексту. Можливі значення center, left, right. За замовчуванням center. Необов'язковий параметр.fill - аргумент який визначає автозаповенння рядка визначеними симовлами, якщо текст менший за розмір стрічки. За замовчуванням значення порожнє. Необов'язковий параметр.sep - символ або символи, які будуть друкуватися на початку кожного рядка і після перенесення на новий на новий рядок. Необов'язковий параметр. За замовчуванням значення порожнє.fw - ширина тексту. Доступні значення 1 та 2. Працює тільки в комбінації з однаковим значенням висоти. За замовчуванням 1. Необов'язковий параметр.fh - висота тексту. Доступні значення 1 та 2. Працює тільки в комбінації з однаковим значенням ширини. За замовчуванням 1. Необов'язковий параметр.wd - ширина рядку(колонки) по кількості символів. За замовчуванням рівна ширині в налаштуваннях форм. Необов'язковий параметр.by_word - перенесення по словам на новий рядок, якщо слово не вмістилось в поточний рядок. Можливі значення: 0 - не переносити, перенесення по буквам, 1 - переносити, перенесення по словам. За замовчуванням 0. Необов'язковий параметр.fnu - Відображення тексту в тому ж регістрі що і в JSON даних або в текстових даних в формі. За замовчуванням в друкованій формі у вигляді картинки чи pdf весь текст відображається в uppercase. Можливі значення: 0 - весь текст в картинках та pdf буде в uppercase, 1 - текст в тому ж регістрі що в JSON даних або в формі. За замовчуванням 0. Необов'язковий параметр.Для передачі параметрів всередині <col></col> використовується тег <arg/>.
Атрибути:
n - порядковий номер аргументу що буде використаний. Обов'язковий параметр.type - тип даних поточного параметру. Доступні значення: float - для десяткових чисел, int - для цілих чисел, str - текстові дані, dt - дата та час.val - ім'я параметра з поточного контексту JSON (можна використовувати переходи «...» і «->»). Обов'язковий параметр.format_in - вхідний формат рядка дати, який в JSON даних. Цей параметр використовується тільки для типу даних dt. Обов'язковий параметр. Наразі підтримується лише формат: "dd-MM-yyyy hh:nn:ss"format_out - вихідний формат рядка дати який буде відображено у формі. Цей параметр використовується тільки для типу даних dt. Необов'язковий параметр. За замовчуванням "dd-MM-yyyy hh:nn:ss"chsign - параметр необхідності відобразити числове значення з протилежним знаком. Наприклад значення знижки в JSON відповіді "disc": 50 а в чеку має бути -50 а не 50. Якщо передано chsign="" - числове значення буде відображено з протилежним знаком, не передано - буде відображено так як в JSON.Приклади використання <col/>:
<pc>
<col f1="УКТЗЕД" a="left" wd="8"/>
<col f1="%s" a="right" arg1="code2"/>
<col f1=" " a="right" wd="2"/>
</pc>
<pc>
<col f1="Ідент. еквайра" a="left" wd="14"/>
<col f1="%s" arg1="bank_id" a="right"/>
</pc>
Приклади використання <col></col>:
<pc>
<col f1="%s" arg1="name" a="left"/>
<col f1=" " a="right" wd="1"/>
<col f="%.2f" a="right" wd="10">
<arg n="1" type="float" val="cost"/>
</col>
<col f1="%s" arg1="taxlit" a="right" wd="2"/>
</pc>
<pc>
<col f="%s = %.2f%%" a="left">
<arg n="1" type="str" val="tax_name"/>
<arg n="2" type="float" val="tax_percent"/>
</col>
<col f="%.2f" a="right" wd="8">
<arg n="1" type="float" val="tax_sum"/>
</col>
</pc>
<if></if>) та string значень (<ifs></ifs>).<if></if>) та (<ifs></ifs>) можна використовувати всі інші наявні теги для керування відображення тексту.Атрибути:
left - найменування параметра з поточного контексту JSON з яким порівнюється значення right (можна використовувати переходи по контексту ".." і "->"). Обов'язковий параметр.sign - операція порівняння значень left та right. != - не рівні, = - рівні, < - значення left менше за right (тільки для числових значень), > - значення left більше за right (тільки для числових значень), <= - значення left менше рівне за right (тільки для числових значень), >= - значення left більше рівне за right (тільки для числових значень). Обов'язковий параметр.right - найменування параметра з поточного контексту JSON (можна використовувати переходи ".." і "->"), з яким порівнюється значення left. Не використовується якщо передано rightv.rightv - числове значення (для <if></if>) або текстове значення (для <ifs></ifs>) вказане напряму в значенні атрибуту, з яким порівнюється значення left. Не використовується якщо передано right.Для виконання альтернативних умов всередину тегів <if></if> та <ifs></ifs> можна помітисти тег <else></else> куди вказати альтернативні умови якщо результат порівняння заданий в <if></if> та <ifs></ifs> негативний. Тег є необов'язковим. При передачі відображення даних всередині <else></else> буде виконуватись якщо:
<if></if> та <ifs></ifs> має false значення.right та leftдля <if></if> та <ifs></ifs> відсутній в JSON структурі відповіді.тег <else></else> не має атрибутів.
За потреби перевірки виконання додаткових умов(if else) всередину <if></if> та <ifs></ifs> та <else></else> можна поміщати додаткові теги <if></if> та <ifs></ifs>.
<ifс></ifс>) .Тег використовується для встановлення умови відображення певних даних у формі аналогічно <if></if> та <ifs></ifs> проте може вміщувати кілька умов одночасно при виконанні однієї з яких або тільки всіх будуть відображатись певні дані. Умови передаються всередині вкладеного тегу condition.
Атрибути:
mode - Тип порівняння параметрів. Має на вибір одне з 2 значень. Обов'язковий параметр.or - для виконання інструкції всередині <ifс></ifс> хоча б одна умова з тегів condition має бути true.and - для виконання інструкції всередині <ifс></ifс> всі умови з тегів condition мають бути true.Атрибути тегу condition ідентичні атрибутам <if></if> та <ifs></ifs>.
Аналогічно <if></if> та <ifs></ifs> можна всередині <ifс></ifс> використовувати <else></else>.
Приклад використання <ifс></ifс>:
<ifc mode="or">
<condition left="bank_id" sign="!=" rightv=""></condition>
<condition left="term_id" sign="!=" rightv=""></condition>
<condition left="auth_code" sign="!=" rightv=""></condition>
<condition left="rrn" sign="!=" rightv=""></condition>
<condition left="cardmask" sign="!=" rightv=""></condition>
<condition left="paysys" sign="!=" rightv=""></condition>
<pc>
<col f1="Комісія еквайра" a="left" wd="15"/>
<col f="%.2f" a="right">
<arg n="1" type="float" val="commission"/>
</col>
<col f1="%s" arg1="currency" a="right" wd="4"/>
</pc>
<ifs left="oper_type" sign="!=" rightv="">
<pc>
<col f1="%s" arg1="oper_type" a="left"/>
</pc>
<else>
<if left="..->task" sign="=" rightv="1">
<p1 f1="Оплата" a="center"/>
</if>
<if left="..->task" sign="=" rightv="2">
<p1 f1="Повернення" a="center"/>
</if>
</else>
</ifs>
<else>
<ifs left="show_additional_info" sign="=" rightv="true">
<pc>
<col f1="Комісія еквайра" a="left" wd="15"/>
<col f="%.2f" a="right">
<arg n="1" type="float" val="commission"/>
</col>
<col f1="%s" arg1="currency" a="right" wd="4"/>
</pc>
<ifs left="oper_type" sign="!=" rightv="">
<pc>
<col f1="%s" arg1="oper_type" a="left"/>
</pc>
<else>
<if left="..->task" sign="=" rightv="1">
<p1 f1="Оплата" a="center"/>
</if>
<if left="..->task" sign="=" rightv="2">
<p1 f1="Повернення" a="center"/>
</if>
</else>
</ifs>
<else>
<if left="commission" sign=">" rightv="0">
<pc>
<col f1="Комісія еквайра" a="left" wd="15"/>
<col f="%.2f" a="right">
<arg n="1" type="float" val="commission"/>
</col>
<col f1="%s" arg1="currency" a="right" wd="4"/>
</pc>
</if>
</else>
</ifs>
</else>
</ifc>
<loop></loop>)тег для обробки та відображення даних з JSON масивів. Наприклад дані по товарам для чеків в JSON відповіді повертаються в масиві об'єктів info.printinfo.goods, відповідно потрібно пройти по кожному елементу з масиву(фактично товару) та відобразити наявні реквізити товару.
Оператори всередині <loop></loop> працюють з даними з кожного об'єкту в масиві.
Атрибути:
arr - назва масиву із поточного контексту JSON дані з якого будуь відображені в формі чеку. Обов'язковий параметр.Додатково для можливості розділення даних в масиві розділовими лініями або іншою інформацією є теги які можуть використовуватись лише всередині <loop></loop>
<pb/> - відображення тексту перед початком обробки всіх даних в масиві.
<pe/> - відображення тексту в кінці обробки всіх даних в масиві.
Формат атрибутів аналогічний як в тегу .
<ifne></ifne>)Тег для перевірки ключа чи масив даних на предмет його відсутності в JSON або наявності порожнього значення.
Для масивів відбувається перевірка на пустий масив та відсутність самого масиву в JSON
Для string значень перевірка відбувається на відсутність ключа в JSON та порожнє значення рядка, для number - тільки на відсутність ключа.
Якщо порожній, всі інструкції всередині <ifne></ifne> не будуть виконані.
Всередині
<ifne></ifne>використання операторуelseпо аналогії з<if></if>та<ifs></ifs>- не передбачено!
Атрибути:
arr - Назва масиву із поточного контексту JSON для перевірки його наявності в поточному контексті та його розміру. Не використовується якщо передано assigned.assigned - Назва ключа (тільки string або number типи) із поточного контексту JSON для перевірки на порожне значення рядка та відсутність ключа в JSON Не використовується якщо передано arr.Приклади використання <ifne></ifne>:
<ifne assigned="..->is_copy">
<if left="..->is_copy" sign="=" rightv="1">
<p1 f1="КОПІЯ" a="center" fw="2" fh="2"/>
</if>
</ifne>
<bc/>)(<bc></bc>)Атрибути:
f1 - текстовий рядок для форматування виведення параметру з JSON як значення для коду. Використовується тільки для не парного тегу <bc/>. Обов'язковий параметр.f - текстовий рядок для форматування виведення параметрів з JSON як значення для коду. Використовується тільки для парного тегу <bc></bc>. Обов'язковий параметр.arg1 - найменування параметра з поточного контексту JSON для виведення (можна використовувати переходи по контексту JSON ".." і "->"). Використовується тільки для не парного тегу <col/>. Необов'язковий параметр.a - вирівнювання qr або штрихкоду. Можливі значення center, left, right. За замовчуванням center. Необов'язковий параметр.type - тип друкованого qr або штрихкоду. Значення: qr, code128 або ean13. За замовчуванням "qr". Необов'язковий параметр.scale - масштаб у відсотках до ширини стрічки друкованого qr або штрихкоду. Необов'язковий параметр. За замовчуванням "100".Для передачі параметрів всередині <bc></bc> використовується тег <arg/>.
Атрибути:
n - порядковий номер аргументу що буде використаний. Обов'язковий параметр.type - тип даних поточного параметру. Доступні значення: float - для десяткових чисел, int - для цілих чисел, str - текстові дані, dt - дата та час.val - ім'я параметра з поточного контексту JSON (можна використовувати переходи «...» і «->»). Обов'язковий параметр.format_in - вхідний формат рядка дати, який в JSON даних. Цей параметр використовується тільки для типу даних dt. Обов'язковий параметр. Наразі підтримується лише формат: "dd-MM-yyyy hh:nn:ss"format_out - вихідний формат рядка дати який буде відображено у формі. Цей параметр використовується тільки для типу даних dt. Необов'язковий параметр. За замовчуванням "dd-MM-yyyy hh:nn:ss"Приклади:
<bc f="https://cabinet.tax.gov.ua/cashregs/check?id=%s&date=%s&time=%s&fn=%s&sm=%s&mac=%s" type="qr" a="center" scale="75">
<arg n="1" type="str" val="fisn" />
<arg n="2" type="dt" val="dt" format_in="dd-MM-yyyy hh:nn:ss" format_out="yyyyMMdd" />
<arg n="3" type="dt" val="dt" format_in="dd-MM-yyyy hh:nn:ss" format_out="hh:nn:ss" />
<arg n="4" type="str" val="fisid" />
<arg n="5" type="str" val="sum_topay" />
<arg n="6" type="str" val="mac" />
</bc>
<pict/>)Увага! Наразі для відображення підтримуються виключно
монохромні bmpкартинки. Інші формати не підтримуються і відображатись не будуть.
Атрибути:
a - вирівнювання картинки. Можливі значення center, left, right. За замовчуванням center. Необов'язковий параметр.img_b64 - монохромний bmp файл у форматі рядка в Base64 без метаданих. Обов'язковий параметр.В атрибуті будь якого із тегів де потрібно передати параметр з JSON даних потрібно вказати коректне форматування залежно від типу даних атрибуту
float - %f
int - %d
str - %s
dt - %s
Для передачі знаку % використовуэться форматування %%.
Для передачі спец сиволів в XML необхідно використовувати екранування для збереження структури XML документу.
< як <> як >& як &' як '" як "