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"; библиотека типов зарегистрирована успешно
---------------------------------------------------
$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.
Для підключення до драйвера Checkbox, слід виконати функцію OpenPortEx із вказанням IP порта, на якому налаштовано ПЗ Checkbox.Каса (зазвичай, за замовчуванням для зовнішніх інтеграцій вказується порт 13000).
Драйвер може працювати тільки через
TCP/IPзв'язок.
Робота через com-порт не підтримується.
Якщо повернуто відповідь True – можна виконувати інші запити.
Якщо не вдалось встановити зв’язок із портом каси — потрібно перевірити, чи запущено Checkbox.Каса.
Після встановлення з’єднання - необхідно перевірити її поточний стан за допомогою метода GetKasaStatus.
Якщо каса знаходиться в онлайн режимі, ви можете переходити до наступного кроку.
Якщо у відповідь ви отримали, що каса знаходиться в офлайн режимі тривалий час — необхідно звернутись до служби підтримки Checkbox зручним для вас способом.
Максимальний режим роботи в офлайн режимі — 36 годин. Після цього — каса блокується до виходу в онлайн режим роботи із серверами Податкової Служби.
Після отримання інформації про стан каси потрібно перевірити, чи відкрито касову зміну (на випадок, якщо касир забув/забула закрити минулу).
Для цього потрібно виконати команду GetShift. Якщо повернуто відповідь False – касову зміну закрито і для початку видачі чеків потрібно відкрити її.
Касова зміна має бути закрита в той день, коли вона відкрита і не може тривати більше 24х годин.
Існує декілька способів відкриття касової зміни:
Для відкриття касової зміни за допомогою нульового чека, службового внесення або винесення коштів — потрібно зробити відповідні налаштування в Checkbox.Менеджер Каси.
Для створення Х-звіту необхідно виконати функцію CreateXReport. Х-звіт – це не фіскальний чек, призначений для контролю роботи каси. Показує всі операції (підсумкові суми), проведені протягом зміни. Х-звіт можна знімати в будь-який час і в будь-якій кількості протягом робочого часу
Для внесення або винесення готівки на баланс каси необхідно виконати команду CreateServiceReceipt. Внесення і видача готівки – службові (нефіскальні) операції, коли ви вносите розмінні гроші в касу або інкасуєте готівку.
Чек продажу та повернення створюється в 3 етапи:
Відмінність чеку повернення від чека продажу полягає в тому, що при поверненні товару при його додаванні в чек потрібно вказувати параметр is return: true.
Для видалення активного чека необхідно виконати команду DeleteActiveReceipt.
Для закриття касової зміни необхідно виконати команду CloseShift. Z-звіт – це фіскальний підсумковий документ, який повинен сформуватись в той же день коли зміна була відкрита та зробити до 23:59. Формування Z-звіту означає завершення касової зміни і здачу виручки. Виручку до каси підприємства здають тільки юридичні особи. Якщо зміна не була відкрита, то в такому випадку немає необхідності формувати Z-звіт кожен день
Для підключення до драйвера Чекбокс, слід виконати функцію openPortEx із вказанням IP порта, на якому налаштовано Checkbox.Каса (зазвичай, для зовнішніх інтеграцій вказується порт 13000). Якщо повернуто відповідь true – можна виконувати інші запити. Якщо не вдалось встановити зв’язок із портом каси — потрібно перевірити, чи запущено Checkbox.Касу.
Існує декілька способів відкриття касової зміни:
Для відкриття касової зміни потрібно за допомогою нульового чека, службового внесення або винесення коштів — потрібно зробити відповідні налаштування в Checkbox Менеджер Каси.
Для створення Х-звіту необхідно виконати функцію printXReport. Х-звіт – це не фіскальний чек, призначений для контролю роботи каси. Показує всі операції (підсумкові суми), проведені протягом зміни. Х-звіт можна знімати в будь-який час і в будь-якій кількості протягом робочого часу
Для внесення або винесення готівки на баланс каси необхідно потрібно виконати команду printRecCash.
Чек продажу та повернення створюється в 4 етапи:
Для закриття касової зміни необхідно виконати команду printZReport.
| bool | AddReceiptItem(name, price, quantity, taxes, discount, isReturn, code) |
| name | string | Назва товару. |
| price | double | Ціна товару (вказується в копійках за одиницю товару). |
| quantity | double | Кількість товару, 1 шт = 1. (Приклад: 1 шт = 1, 150 грам - 0.150) |
| taxes | list | Цифровий або літерний код ставки податку (попередньо програмується у особистому кабінеті). |
| discount | double | Значення знижки (вказується в копійках). |
| isReturn | bool | Ознака повернення. За замовчуванням false (чек продажу). |
| code | string | Код товару - довільне значення (ее друкується в чеку). |
True у випадку успішного додавання товару до відкритого чека.| bool | CloseReceipt(PaymentInfoEx paymentInfo) |
| bool | Друк паперового чека (за замовчення - виконується друк). | |
| payments | list | Інформація про способи оплати. |
| delivery | string | Інформація про відпарвку чека на e-mail або смс/Viber (за умови активації та передплати послуги в особистому кабінеті). |
| round | bool | Заокруглення суми готівкового чека згідно правил НБУ). За замовченням - не виконується. |
| 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 флаг, який визначає, чи має бути доступною графа для підпису власника картки та касира. |
True у випадку успішьої оплати фіскального чека.$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}))
| bool | CloseShift() |
True у випадку успішного закриття касової зміни.| bool | createXReport() |
True - якщо X-звіт створено.False - якщо X-звіт не створено.| bool | CreateServiceReceipt(double sum) |
| double sum | Сума внесення або винесення коштів в копійках. Винечення коштів вказується зі знаком -. Приклад: внесення 1 грн = 100, винесення 20 грн = -2000 |
True - якщо чек створено.False - якщо чек не створено.| bool | CreateNullReceipt() |
True - якщо нульовий чек створено.False - якщо нульовий чек не створено.| bool | DeleteActiveReceipt() |
True у випадку успішного видалення відкритого чека.| bool | GetKasaStatus() |
| OnlineStatus | bool | True або False |
| HoursInOffline | int | Кількість годин з першої транзакції в статусі PENDING |
| FirstPendingTransaction | datetime | Час першої у списку транзакції в статусі PENDING |
| PendingTransactions | int | Кількість транзакцій в статусі PENDING |
| OfflineCodes | int | Кількість доступних офлайн-кодів |
| OfflineCodesPercent | int | Кількість доступних офлайн кодів у відсотках |
| AdditionalProperties | list | Час останньої відправки go_offline та к-сть годин з цього моменту |
| bool | GetStrKasaStatus() |
| bool | GetLastReceiptTextData() |
receiptId в текстовому форматі.| bool | GetLastReceiptTextData(receiptId) |
| receiptId | string | UUID фіскального чека. |
| bool | GetShift() |
True - якщо касову зміну відкрито.False - якщо касову зміну закрито.| bool | OpenPortEx(IP, Port) |
| IP | Windows: BSTR рядок, Linux: рядок char у кодуванні Windows-1251, IP адреса фіскального реєстратора у вигляді "127.0.0.1". |
| Port | Ціле число, номер порта фіскального реєстратора. |
True у випадку успішного відкриття порта.| bool | OpenReceipt(cashierName, department=null, header=null, footer=null) |
| cashiername | string | Ім'я касира. Не друкується на чеку, якщо це не дозволено налаштуваннями каси. |
| department | string | Назва відділу. Не друкується в чеку. |
| header | string | Друк службової інформації в шапці чека. Не друкується на чеку, якщо це не дозволено налаштуваннями каси. |
| footer | string | Друк службової інформації в підвалі чека. Не друкується на чеку, якщо це не дозволено налаштуваннями каси. |
True - якщо чек відкрито.| bool | OpenShift() |
True - якщо касову зміну відкрито.False - якщо касову зміну закрито.| bool | SendReceiptToEmail(email) |
| string | Електронна поштова скринька. |
True - у випадку успішної відправки чека.| bool | SendReceiptToEmail(receiptId, email) |
| receiptId | string | UUID фіскального чека. |
| string | Електронна поштова скринька. |
True - у випадку успішної відправки чека. $srv.SendReceiptToEmail('e988ec99-4931-4a70-be94-eb2732a9a3bc','[email protected]')
| bool | SendReceiptToSMS(phone) |
| phone | string | Номер телефону у форматі XXTTTYYYYYYY, де XX - код країни, TTT - код оператора, YYYYYYY - номер телефону. |
True - у випадку успішної відправки чека.| bool | SendReceiptToSMS(receiptId, phone) |
| receiptId | string | UUID фіскального чека. |
| phone | string | Номер телефону у форматі XXTTTYYYYYYY, де XX - код країни, TTT - код оператора, YYYYYYY - номер телефону. |
True - у випадку успішної відправки чека.| bool | Version() |
v1.1.53 (build Mon Mar 6 14:07:24 UTC 2023), 1C
Де 1.1.53 - версія зареєстрованого драйверу.
Якщо у Вас виникли питання, Ви знайшли помилку або хочете запропонувати вказати додаткову інформацію в інструкціях - Ви завжди можете зв'язатись з нами зручним для вас способом.