Fiskalizacija HR для OpenCart — фіскалізація чеків у CIS Porezne uprave (ZKI, JIR, QR)

Fiskalizacija HR для OpenCart — модуль для інтернет-магазинів у Хорватії на OpenCart 4, 3 і 2.3. У Хорватії кожен чек кінцевому покупцеві має бути фіскалізований, хоч би як він платив. Магазин рахує захисний код ZKI, надсилає підписаний чек у сервіс фіскалізації CIS податкової (Porezna uprava) і друкує на чеку ідентифікатор JIR та QR-код. Модуль робить це для замовлень OpenCart напряму в CIS вашим сертифікатом, без стороннього сервісу посередині й без щомісячної підписки.

Магазин на WooCommerce? Для нього є окрема версія — Fiskalizacija HR для WooCommerce, з тим самим підписом, ZKI і форматом запиту.

Що потрібно від вас. OIB фірми або обрту; вебмагазин, зареєстрований як пословний простір у ePorezna (модуль цього не робить — потрібна лише позначка простору, наприклад WEB1); сертифікат для фіскалізації, виданий на ваш OIB, наприклад FINA «Fiskal». Тестове середовище CIS приймає лише DEMO-сертифікати, робоче — лише робочі.

Чесно про перевірку. Модуль зроблено й перевірено за офіційною технічною специфікацією CIS «Tehnička specifikacija za korisnike» v2.7 і схемою FiskalizacijaSchema / WSDL 1.10: кожен згенерований запит — звичайні чеки, пізня доставка, storno з мінусами, чеки з OIB покупця — пройшов офіційну XSD і незалежну перевірку підпису, ZKI перераховано окремо. Повний прогін ішов на локальних магазинах OpenCart 4.1.0.3, 4.0.2.3 (драйвер pdo), 3.0.5.0 і 2.3.0.2 на PHP 7.0 з моделлю відповідей CIS: успіх, відмови, недоступність. Справжній тестовий сервер CIS відповідав нам лише без DEMO-сертифіката: для нього потрібен хорватський OIB, якого в CatCode нема. Тому живий JIR ви отримаєте у своєму 7-денному тріалі Pro з DEMO-сертифікатом FINA. Якщо CIS відповість не так, як описано в специфікації, виправимо оперативно.

Відповідальність за дані чека лишається за магазином. Модуль бере суми й податки із замовлення OpenCart, а систему ПДВ, позначки приміщення й пристрою, оператора, способи оплати й категорію для рядків без ПДВ — з ваших налаштувань. Звірте ці налаштування з бухгалтером до переходу на робоче середовище.

Як це виглядає для покупця

Покупець отримує чек: дані магазину й OIB, номер у форматі broj/prostor/uređaj, дата й час за хорватським часом, оператор, спосіб оплати, позиції зі ставками ПДВ, розклад ПДВ, ZKI, JIR і QR-код з посиланням на перевірку чека на porezna.gov.hr. Сторінка чека відкривається лише за посиланням із ключем і друкується кнопкою «Print».

У кабінеті клієнта, в історії замовлення, з’являється блок «Fiscal receipt» з QR-кодом, номером, сумою, ZKI, JIR і посиланням на чек. Чужих чеків клієнт не бачить; на телефоні блок без горизонтального скролу.

Pro. Фірма, що платить карткою чи готівкою, може вписати свій OIB у поле «Company OIB» на чекауті — штатному і One Page Checkout CatCode. Модуль перевіряє контрольну цифру: хибний OIB зупиняє оформлення біля поля. Після JIR клієнт отримує чек листом.

Що отримує адмін

• Розширення → Модулі → CatCode Fiskalizacija HR з вкладками «Receipts», «Settings», «Tools» і «Licence» (у хорватській адмінці — хорватською).
• Реєстр чеків: номер і час, замовлення, покупець і його OIB, сума, спосіб оплати, статус («Fiscalised», чекає JIR, відхилено, пізня доставка), JIR і ZKI; фільтр за статусом і пошук за номером, JIR, ZKI, OIB чи замовленням.
• «Send receipts without a JIR now» надсилає чергу одразу, «Send again» — відхилений чек після виправлення налаштувань.
• Зверху сторінки видно середовище (TEST або PRODUCTION) і попередження: сертифікат прострочений або закінчується, OIB у сертифікаті не збігається з налаштуваннями, DEMO-сертифікат у робочому середовищі, чеки без JIR довше 30 хвилин.

Сторінка чека показує все, що пішло в CIS і повернулось: номер, статус, ZKI, JIR, чи перевірено підпис відповіді, кількість спроб, рядки чека й розклад ПДВ, усі чеки цього замовлення, а нижче — підписаний запит і відповідь XML. У тестовому середовищі є перевірка provjera — CIS звіряє чек без фіскалізації.

На сторінці замовлення — панель «Fiscal receipt» з чеками й storno цього замовлення, кнопкою «Issue and fiscalise the receipt» і полем OIB покупця для наступного чека (Pro). Кожен крок пишеться в історію замовлення.

Як це працює — крок за кроком

1. Сертифікат. Завантажте .p12 з паролем або .pem. Модуль показує власника, видавця, OIB і строк дії, зберігає приватний ключ зашифрованим (ключ шифрування — у system/storage, не в базі) і бере OIB із сертифіката в налаштування. «Check the connection» перевіряє зв’язок із CIS методом echo.
2. Обвезник і нумерація. OIB, чи ви в системі ПДВ, назва й адреса для чека, позначка простору, номер пристрою, послідовність (за простором P або пристроєм N), «перший номер року», якщо продовжуєте серію з іншої програми, OIB і позначка оператора (порожньо — OIB обвезника й «WEB»).
3. Оплати й податки. Для кожного платіжного модуля — код G, K, T або O; категорія рядків без ПДВ; коди підсумків, які є оплатою, а не продажем (типово voucher і credit).
4. Замовлення. Коли замовлення отримує обраний статус, модуль перевіряє суми й ставки локально, лише тоді бере наступний номер, рахує ZKI, будує й підписує RacunZahtjev і надсилає його в CIS. Повторний статус другого чека не створює.
5. Відповідь. CIS повертає JIR — модуль перевіряє підпис відповіді й зберігає JIR. Помилка s001–s005 чи s013 — чек «Refused», причину видно в реєстрі, «Send again» після виправлення.
6. Збій зв’язку. CIS не відповів — чек уже дійсний із ZKI, а модуль доставляє його пізніше з позначкою NakDost і новим ідентифікатором повідомлення, з наростаючою паузою від 1 до 360 хвилин.

ПДВ береться з податкових рядків замовлення й групується за ставкою — 25 %, 13 %, 5 % або 0 %. Ставку, якої CIS не приймає, модуль зупиняє ще до відправки з поясненням, номер не витрачається. Купони розкладаються між ставками, доставка рахується за її податком, а копійки округлення модуль зводить так, щоб сума чека збігалась із сумою замовлення. Рядки без податку типово йдуть як звільнення від ПДВ, товар із реальною ставкою 0 % — як ПДВ 0 %; інші категорії можна задати примусово.

Pro. Повернення дає storno-чек з мінусовими сумами за тими самими ставками — автоматично на статусах «Refunded» і «Reversed» (можна змінити) або кнопкою. OIB покупця йде в CIS лише з оплатою G або K, як вимагає специфікація. Замовлення в іншій валюті отримує чек у євро за курсом магазину, старі замовлення можна фіскалізувати пакетом за ID, реєстр вивантажується в CSV, а власник отримує лист, коли чек відхилено або він після 5 спроб усе ще без JIR.

Що під капотом

• CIS: RacunZahtjev (фіскалізація), ProvjeraZahtjev (перевірка, лише тест), echo (зв’язок); адреси cistest.apis-it.hr:8449 і cis.porezna-uprava.hr:8449, SOAP 1.1.
• ZKI — MD5 від підпису RSA-SHA256 рядка OIB + дата й час + номер + простір + пристрій + сума, як у розділі 12 специфікації v2.7.
• Підпис запиту — enveloped XMLDSig: Exclusive C14N, RSA-SHA256. RSA-SHA1 не використовується: тестовий CIS відхиляє його з 1 липня 2026, робочий — з 1 січня 2027.
• TLS і відповідь: з’єднання перевіряється за вкладеними сертифікатами FINA (Fina RDC 2020, Fina Demo CA 2020), підпис відповіді — за сертифікатом сервісу.
• Нумерація з блокуванням: паралельні замовлення не отримують однакового номера й не лишають дірок; окремі лічильники для тесту й продакшну. Перевірено на 40 паралельних замовленнях і реєстрі на 3 000 чеків.
• Події OpenCart: модуль не змінює файли ядра — працює через події, тож сумісний з One Page Checkout CatCode (перевірено на 4.1 і 3.0).
• Видалення модуля: OpenCart прибирає налаштування й сертифікат, а реєстр і лічильники лишаються як податкові записи; опція «Delete data on uninstall» прибирає й їх.

Як встановити

1. OpenCart 4: Розширення → Інсталятор → завантажте cc_fiskalhr.ocmod.zip (ім’я архіву не змінюйте) і натисніть «Встановити». OpenCart 3: Розширення → Інсталятор → cc_fiskalhr-oc3.ocmod.zip. OpenCart 2.3: залийте вміст папки upload/ з cc_fiskalhr-oc2.ocmod.zip у корінь магазину (FTP або файловий менеджер хостингу).
2. Розширення → Модулі → CatCode Fiskalizacija HR → «Встановити» → «Редагувати».
3. Settings: завантажте DEMO-сертифікат, натисніть «Check the connection», заповніть OIB, позначку простору, пристрій, оператора й способи оплати, увімкніть фіскалізацію в середовищі TEST.
4. Оформіть тестові замовлення, перевірте чеки в реєстрі й перевіркою provjera.
5. Покажіть налаштування бухгалтеру, перемкніть середовище на PRODUCTION і завантажте робочий сертифікат.
6. Для Pro: вставте ліцензійний ключ з листа після оплати або запустіть 7-денний тріал у вкладці «Licence».