CheckBox.FiscalDriver – драйвер, створений для обміну інформацією між встановленим ПРРО Checkbox.Каса та обліковими касовими програмами.
Драйвер являється шлюзом на методи локального API каси. Однією з головних переваг драйвера являється майже нульова затримка передачі даних між обліковою програмою та самим API каси. Окрім того, драйвер також містить в собі методи універсального драйверу, тим самим, якщо ваша система раніше працювала через універсальний драйвер — додатково змінювати команди не потрібно.
Варто розуміти, що методи драйвера Checkbox мають набагато більше методів роботи саме з API Checkbox.Каси, ніж універсальний драйвер.
Драйвер завантажується автоматично під час встановлення Checkbox.Каса Remote або Checkbox Менеджера Каси на ПК.
Остання актуальна версія драйверу — 1.1.60 (станом на 01.10.23).
Для реєстрації драйверу необхідно перейти в налаштування Checkbox Менеджера Каси - Протокол - натиснути "Реєстрація OLE".
Якщо ви використовуєте Checkbox.Каса Remote - реєстрацію драйвера необхідно виконати вручну за допомогою командного рядка. Для цього відкрийте його від імені адміністратора та введіть послідовно команди:
set DOTNETFX4=%SystemRoot%\Microsoft.NET\Framework\v4.0.30319
%DOTNETFX4%\regasm.exe С:\checkbox.kasa.remote\com-server\Checkbox.FiscalDriver.dll /codebase /tlb
Де С:\checkbox.kasa.remote\ - ваш шлях встановлення каси.
Якщо драйвер зареєстровано успішно, ви отримаєте відповідь виду:
Типы зарегистрированы успешно
Предупреждение программы экспорта библиотек типов при обработке "CheckBox.FiscalDriver.SetupPrinter(qrScale), CheckBox.FiscalDriver". Предупреждение: Программа экспорта библиотек типов обнаружила экземпляр базового типа в сигнатуре. Базовый код не может быть экспортирован в COM.
Предупреждение программы экспорта библиотек типов при обработке "CheckBox.FiscalDriver.AddReceiptItem1(taxes), CheckBox.FiscalDriver". Предупреждение: Программа экспорта библиотек типов обнаружила экземпляр базового типа в сигнатуре. Базовый код не может быть экспортирован в COM.
Предупреждение программы экспорта библиотек типов при обработке "CheckBox.FiscalDriver.AddReceiptItem(taxes), CheckBox.FiscalDriver". Предупреждение: Программа экспорта библиотек типов обнаружила экземпляр базового типа в сигнатуре. Базовый код не может быть экспортирован в COM.
Сборка экспортирована в "C:\checkbox.kasa.remote\com-server\Checkbox.FiscalDriver.tlb"; библиотека типов зарегистрирована успешно
---------------------------------------------------
Examples
$srv = new-object -comObject "CheckBox.FiscalPrinter"
srv = win32com.client.Dispatch("CheckBox.FiscalPrinter")
srv = Новый COMОбъект("CheckBox.FiscalPrinter");
Перевірка виконується шляхом виклику команди Version. Якщо драйвер зареєстровано успішно, ви отримаєте відповідь:
v1.1.53 (build Mon Mar 6 14:07:24 UTC 2023), 1C
Де 1.1.53 - версія зареєстрованого драйверу.
- Налаштування Checkbox Менеджера Каси.
- Підключення до встановленого драйвера.
- Отримання інформації про стан каси (офлайн/онлайн режим роботи).
- Відкриття зміни.
- Перевірка балансу каси за допомогою Х-звіту (за необхідності).
- Cтворення службового чека внесення готівки (за необхідності).
- Створення чеків продажу або повернення.
- Cтворення службового чека внесення готівки (за необхідності).
- Отримання інформації про стан каси (офлайн/онлайн режим роботи).
- Закриття зміни — створення Z-звіту.
Ніколи не використовуйте бойову касу/касира для цілей тестування, інакше потім вам доведеться, як мінімум, пояснювати податковій, що ви передали некоректні дані та, можливо, сплачувати штраф.
В даній статті описано мінімальний необхідний перелік методів, яких буде достатньо для створення інтеграції та роботи з драйвером Checkbox.
Для підключення до драйвера Checkbox, слід виконати функцію OpenPortEx із вказанням IP порта, на якому налаштовано ПЗ Checkbox.Каса (зазвичай, за замовчуванням для зовнішніх інтеграцій вказується порт 13000).
Драйвер може працювати тільки через TCP/IP зв'язок.
Робота через com-порт не підтримується.
Якщо повернуто відповідь True – можна виконувати інші запити.
Якщо не вдалось встановити зв’язок із портом каси — потрібно перевірити, чи запущено Checkbox.Каса.
Після встановлення з’єднання - необхідно перевірити її поточний стан за допомогою метода GetKasaStatus.
Якщо каса знаходиться в онлайн режимі, ви можете переходити до наступного кроку.
Якщо у відповідь ви отримали, що каса знаходиться в офлайн режимі тривалий час — необхідно звернутись до служби підтримки Checkbox зручним для вас способом.
Максимальний режим роботи в офлайн режимі — 36 годин. Після цього — каса блокується до виходу в онлайн режим роботи із серверами Податкової Служби.
Після отримання інформації про стан каси потрібно перевірити, чи відкрито касову зміну (на випадок, якщо касир забув/забула закрити минулу).
Для цього потрібно виконати команду GetShift. Якщо повернуто відповідь False – касову зміну закрито і для початку видачі чеків потрібно відкрити її.
Касова зміна має бути закрита в той день, коли вона відкрита і не може тривати більше 24х годин.
Існує декілька способів відкриття касової зміни:
Для відкриття касової зміни за допомогою нульового чека, службового внесення або винесення коштів — потрібно зробити відповідні налаштування в Checkbox.Менеджер Каси.
Для створення Х-звіту необхідно виконати функцію CreateXReport. Х-звіт – це не фіскальний чек, призначений для контролю роботи каси. Показує всі операції (підсумкові суми), проведені протягом зміни. Х-звіт можна знімати в будь-який час і в будь-якій кількості протягом робочого часу
Для внесення або винесення готівки на баланс каси необхідно виконати команду CreateServiceReceipt. Внесення і видача готівки – службові (нефіскальні) операції, коли ви вносите розмінні гроші в касу або інкасуєте готівку.
Чек продажу та повернення створюється в 3 етапи:
- Відкриття фіскального чека OpenReceipt
- Додавання товарів до відкритого чека — AddReceiptItem
- Додавання інформації про спосіб оплати, даних ЕПЗ (якщо оплата карткою), доставку чека на пошту або viber/смс (за умови активації послуги в налаштуваннях особистого кабінету та предоплати послуги).
Відмінність чеку повернення від чека продажу полягає в тому, що при поверненні товару при його додаванні в чек потрібно вказувати параметр is return: true.
Для видалення активного чека необхідно виконати команду DeleteActiveReceipt.
Для закриття касової зміни необхідно виконати команду CloseShift. Z-звіт – це фіскальний підсумковий документ, який повинен сформуватись в той же день коли зміна була відкрита та зробити до 23:59. Формування Z-звіту означає завершення касової зміни і здачу виручки. Виручку до каси підприємства здають тільки юридичні особи. Якщо зміна не була відкрита, то в такому випадку немає необхідності формувати Z-звіт кожен день
Інформація
Для підключення до драйвера Чекбокс, слід виконати функцію openPortEx із вказанням IP порта, на якому налаштовано Checkbox.Каса (зазвичай, для зовнішніх інтеграцій вказується порт 13000). Якщо повернуто відповідь true – можна виконувати інші запити. Якщо не вдалось встановити зв’язок із портом каси — потрібно перевірити, чи запущено Checkbox.Касу.
Існує декілька способів відкриття касової зміни:
- допомогою Х-звіту (команда printXReport)
- службовим чеком внесення або винесення готівки (команда printRecCash)
- друком нульового чека (команда printNullReceipt)
- при створенні першого фіскального чека продажу або повернення.
Для відкриття касової зміни потрібно за допомогою нульового чека, службового внесення або винесення коштів — потрібно зробити відповідні налаштування в Checkbox Менеджер Каси.
Для створення Х-звіту необхідно виконати функцію printXReport. Х-звіт – це не фіскальний чек, призначений для контролю роботи каси. Показує всі операції (підсумкові суми), проведені протягом зміни. Х-звіт можна знімати в будь-який час і в будь-якій кількості протягом робочого часу
Для внесення або винесення готівки на баланс каси необхідно потрібно виконати команду printRecCash.
Чек продажу та повернення створюється в 4 етапи:
- відкриття фіскального чека за допомогою команди beginFiscalReceipt
- додавання товарів до відкритого чека — printRecItem
- додавання інформац ії про спосіб оплати за допомогою команди printRecTotal — для готівки та printRecTotalCard – для безготівкового способу оплати.
Відмінність чеку повернення від чека продажу полягає в тому, що при виконанні методу beginFiscalReceipt потрібно вказати тип чека.
Для закриття касової зміни необхідно виконати команду printZReport.
Public Member Functions inherited from CheckBox.FiscalDriver.ApplicationBase - Розгорніть для ознайомлення з описом методів
- Додавання товару до відкритого чека.
| bool |
AddReceiptItem(name, price, quantity, taxes, discount, isReturn, code) |
Parameters
| name |
string |
Назва товару. |
| price |
double |
Ціна товару (вказується в копійках за одиницю товару). |
| quantity |
double |
Кількість товару, 1 шт = 1. (Приклад: 1 шт = 1, 150 грам - 0.150) |
| taxes |
list |
Цифровий або літерний код ставки податку (попередньо програмується у особистому кабінеті). |
| discount |
double |
Значення знижки (вказується в копійках). |
| isReturn |
bool |
Ознака повернення. За замовчуванням false (чек продажу). |
| code |
string |
Код товару - довільне значення (ее друкується в чеку). |
Returns
True у випадку успішного додавання товару до відкритого чека.
Examples
$srv.AddReceiptItem("Кілограм корівок", 10010, 0.100, 8, 0, $false, "1")
| bool |
CloseReceipt(PaymentInfoEx paymentInfo) |
Parameters
| print |
bool |
Друк паперового чека (за замовчення - виконується друк). |
| payments |
list |
Інформація про способи оплати. |
| delivery |
string |
Інформація про відпарвку чека на e-mail або смс/Viber (за умови активації та передплати послуги в особистому кабінеті). |
| round |
bool |
Заокруглення суми готівкового чека згідно правил НБУ). За замовченням - не виконується. |
payments
| type |
string |
const: CASH |
| value |
int |
Сума оплати чека (вказується в копійках). |
| label |
string |
maxLength: 128. minLength: 1. default: Готівка |
| type |
string |
const: CASHLESS |
| value |
int |
Сума оплати чека (вказується в копійках). |
| label |
string |
maxLength: 128. minLength: 1. default: Картка |
| code |
int |
title: Номер оплати. exclusiveMaximum: 10. exclusiveMinimum: 0 |
| card_mask |
string |
Маска карти (не більше 19 символів). |
| bank_name |
string |
Назва банку-емітента. |
| auth_code |
string |
Код авторизації банківської операції. |
| rrn |
string |
Reference Retrieval Number - унікальний ідентифікатор банківської транзакції. |
| payment_system |
string |
Назва платіжної системи. |
| owner_name |
string |
Ім'я власника електронного платіжного засобу. |
| terminal |
string |
Інформація про платіжний термінал. |
| acquirer_and_seller |
string |
Ідентифікатор еквайра та торгівця, або інші реквізити, що дають змогу їх ідентифікувати. |
| receipt_no |
string |
Номер банківського чека. |
| signature_required |
bool |
true/false флаг, який визначає, чи має бути доступною графа для підпису власника картки та касира. |
Returns
True у випадку успішьої оплати фіскального чека.
Examples
- Закриття чека з параметрами "за замовчуванням".
$srv.closereceipt(@{payments=(@{value=0; type='CASHLESS'; label='Картка'},@{value=10000; type='CASH'; label='Готівка'})})
- Закриття чека з відправкою на пошту та друком паперового чека.
$srv.closereceipt((@{payments=(@{value=0; type='CASHLESS'; label='Картка'},@{value=10000; type='CASH'; label='Готівка'});delivery=@{email='[email protected]'}}))
- Закриття чека з відправкою на пошту та без друку паперового чека.
$srv.closereceipt((@{payments=(@{value=0; type='CASHLESS'; label='Картка'},@{value=600; type='CASH'; label='Готівка'});delivery=@{email='[email protected]'};print=$false}))
- Закриття чека з відправкою на пошту, без друка паперового чека та без заокруглення.
$srv.closereceipt((@{payments=(@{value=0; type='CASHLESS'; label='Картка'},@{value=600; type='CASH'; label='Готівка'});delivery=@{email='[email protected]'};print=$false;round=$false}))
- Закриття готівкового чека з даними ЕПЗ, відправко на пошту, без друка паперового чека та без заокруглення.
$srv.closereceipt((@{payments=(@{value=1001; type='CASHLESS'; label='Картка';CardMask='XXXXXXXXXXXX6734';BankName='ПриватБанк';AuthCode='078359';Rrn='305817547765';PaymentSystem='VISA';OwnerName='CHEREZPLETINNOHUZADYRAISHCHENKO PETRO';Terminal='S1LF0EUR';AcquirerAndSeller='PrivetBank';ReceiptNo='1';SignatureRequired=$false},@{value=0; type='CASH'; label='Готівка'});delivery=@{email='[email protected]'};print=$false;round=$false}))
- Закриття відкритої касової зміни.
Returns
True у випадку успішного закриття касової зміни.
Examples
$srv.CloseShift()
Returns
True - якщо X-звіт створено.False - якщо X-звіт не створено.
Examples
$srv.CreateXReport()
- Створення службового чека внесення або винесення готівкових коштів.
| bool |
CreateServiceReceipt(double sum) |
Parameters
| double sum |
Сума внесення або винесення коштів в копійках. Винечення коштів вказується зі знаком -. Приклад: внесення 1 грн = 100, винесення 20 грн = -2000 |
Returns
True - якщо чек створено.False - якщо чек не створено.
Examples
$srv.CreateServiceReceipt(100)
- Створення нульового чека.
Returns
True - якщо нульовий чек створено.False - якщо нульовий чек не створено.
Examples
$srv.CreateNullReceipt()
- Видалення відкритого чека.
| bool |
DeleteActiveReceipt() |
Returns
True у випадку успішного видалення відкритого чека.
Examples
$srv.DeleteActiveReceipt()
- Повертає структуру з даними по касі.
Returns
- Повертає структуру з даними по касі.
| OnlineStatus |
bool |
True або False |
| HoursInOffline |
int |
Кількість годин з першої транзакції в статусі PENDING |
| FirstPendingTransaction |
datetime |
Час першої у списку транзакції в статусі PENDING |
| PendingTransactions |
int |
Кількість транзакцій в статусі PENDING |
| OfflineCodes |
int |
Кількість доступних офлайн-кодів |
| OfflineCodesPercent |
int |
Кількість доступних офлайн кодів у відсотках |
| AdditionalProperties |
list |
Час останньої відправки go_offline та к-сть годин з цього моменту |
Examples
$srv.GetKasaStatus()
- Повертає структуру з даними по касі у текстовому виді.
Returns
- Повертає структуру з даними по касі.
Examples
$srv.GetStrKasaStatus()
- Отримання даних останнього чеку в текстовому форматі.
| bool |
GetLastReceiptTextData() |
Returns
- Повертає текстові дані чеку. Коли в налаштуваннях каси не встановлений параметр "Зберігати txt варіант чека", то повертається пустий рядок.
Examples
$srv.GetLastReceiptTextData()
- Отримання даних по чеку
receiptId в текстовому форматі.
| bool |
GetLastReceiptTextData(receiptId) |
Parameters
| receiptId |
string |
UUID фіскального чека. |
Returns
- Повертає текстові дані чеку. Коли чек не знайдено або в налаштуваннях каси не встановлений параметр "Зберігати txt варіант чека", то повертається пустий рядок.
Examples
$srv.GetLastReceiptTextData('e988ec99-4931-4a70-be94-eb2732a9a3bc')
- Отримання інформації про стан поточної зміни.
Returns
True - якщо касову зміну відкрито.False - якщо касову зміну закрито.
Examples
$srv.GetShift()
- Отримання посилання на чек на сайті ДПС після його успішної фіскалізації. Для використання методу необхідно оновити касу щонайменше до версії 1.5.Х. Версія драйвера - не нижче 1.1.79
Returns
- Повертає значення QR-коду фіскального чека, яке веде на сайт ДПС для його перевірки.
Examples
$srv.LastReceiptQRTaxUrl()
- Підключення до порту каси.
| bool |
OpenPortEx(IP, Port) |
Parameters
| IP |
Windows: BSTR рядок, Linux: рядок char у кодуванні Windows-1251, IP адреса фіскального реєстратора у вигляді "127.0.0.1". |
| Port |
Ціле число, номер порта фіскального реєстратора. |
Returns
True у випадку успішного відкриття порта.
Examples
$srv.OpenPortEx("127.0.0.1", 13000)
- Відкриття фіскального чека продажу або повернення.
| bool |
OpenReceipt(cashierName, department=null, header=null, footer=null) |
Parameters
| cashiername |
string |
Ім'я касира. Не друкується на чеку, якщо це не дозволено налаштуваннями каси. |
| department |
string |
Назва відділу. Не друкується в чеку. |
| header |
string |
Друк службової інформації в шапці чека. Не друкується на чеку, якщо це не дозволено налаштуваннями каси. |
| footer |
string |
Друк службової інформації в підвалі чека. Не друкується на чеку, якщо це не дозволено налаштуваннями каси. |
Returns
True - якщо чек відкрито.
Examples
$srv.OpenReceipt("test_cashier","","test_header","test_footer")
Returns
True - якщо касову зміну відкрито.False - якщо касову зміну закрито.
Examples
$srv.OpenShift()
- Закриття фіскального чека із розширеними даними банківської транзакції. Драйвер версії не нижче 1.1.83
| bool |
printRecTotalCardEx(decimal Sum, int type, string nameBank, string idEkv, string idTerm, double com, string oper, string epz, string plat, string avtor, string receiptNo, string rrn, bool signatureRequired) |
Params
| Sum |
дійсне число, сума сплати у гривнях |
| type |
тип безготівкової оплати |
| nameBank |
назва банку |
| idEkv |
ідентифікатор платіжного еквайєра/торгівця/банку |
| idTerm |
ідентифікатор платіжного терміналу |
| com |
дійсне число, сума комісії у гривнях |
| oper |
назва платіжної операції |
| epz |
ЕПЗ/електронний тип платежу/номер картки |
| plat |
платіжна система |
| avtor |
код авторизації |
| receiptNo |
номер банківського чека |
| rrn |
RRN транзакції |
| signatureRequired |
підпис власника картки |
- Відправка чека на електронну поштову скриньку.
| bool |
SendReceiptToEmail(email) |
Parameters
| email |
string |
Електронна поштова скринька. |
Returns
True - у випадку успішної відправки чека.
Examples
$srv.SendReceiptToEmail('[email protected]')
- Відправка чека на електронну поштову скриньку.
| bool |
SendReceiptToEmail(receiptId, email) |
Parameters
| receiptId |
string |
UUID фіскального чека. |
| email |
string |
Електронна поштова скринька. |
Returns
True - у випадку успішної відправки чека.
Examples
$srv.SendReceiptToEmail('e988ec99-4931-4a70-be94-eb2732a9a3bc','[email protected]')
- Відправка чека на електронну поштову скриньку.
| bool |
SendReceiptToSMS(phone) |
Parameters
| phone |
string |
Номер телефону у форматі XXTTTYYYYYYY, де XX - код країни, TTT - код оператора, YYYYYYY - номер телефону. |
Returns
True - у випадку успішної відправки чека.
Examples
$srv.SendReceiptToSMS('380500520000')
- Відправка чека на електронну поштову скриньку.
| bool |
SendReceiptToSMS(receiptId, phone) |
Parameters
| receiptId |
string |
UUID фіскального чека. |
| phone |
string |
Номер телефону у форматі XXTTTYYYYYYY, де XX - код країни, TTT - код оператора, YYYYYYY - номер телефону. |
Returns
True - у випадку успішної відправки чека.
Examples
$srv.SendReceiptToSMS('e988ec99-4931-4a70-be94-eb2732a9a3bc','380500520000')
- Перевірка версії драйвера та час збірки.
Returns
- Повертає версію драйвера та час збірки.
v1.1.53 (build Mon Mar 6 14:07:24 UTC 2023), 1C
Де 1.1.53 - версія зареєстрованого драйверу.
Examples
$srv.Version()
Якщо у Вас виникли питання, Ви знайшли помилку або хочете запропонувати вказати додаткову інформацію в інструкціях - Ви завжди можете зв'язатись з нами зручним для вас способом.