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

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

Магазин на OpenCart? Для нього є окрема версія — Fiskalizacija HR для OpenCart (4.x, 3.x і 2.3), з тим самим підписом, ZKI і форматом запиту; ліцензія для OpenCart — одна оплата, назавжди.

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

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

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

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

Після оплати на сторінці подяки з’являється блок «Fiskalizirani račun»: номер чека у форматі broj/prostor/uređaj, дата й час, спосіб оплати, оператор, ZKI, JIR і QR-код з посиланням на перевірку чека на porezna.gov.hr. Той самий блок є в «Мій акаунт» у замовленні клієнта.

Фіскальні дані й QR-код ідуть і в листи WooCommerce клієнту — «В обробці», «Виконано», рахунок, повернення. QR-код у листі — картинка PNG. Блок на сторінці й у листах можна вимкнути окремо.

Pro. На класичному і блоковому чекауті з’являється поле «OIB tvrtke (za B2B račun)» — для фірм, що платять карткою чи готівкою й хочуть свій OIB на чеку. Плагін перевіряє контрольну цифру OIB: хибний номер не дасть оформити замовлення, з поясненням хорватською. Поле можна сховати, зробити необов’язковим або обов’язковим для B2B-магазину.

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

• WooCommerce → Fiskalizacija з вкладками «Receipts», «Settings» і «Licence» (у хорватській адмінці — Računi, Postavke, Licenca).
• Реєстр чеків: номер і дата, замовлення, сума, спосіб оплати, статус («Fiskaliziran (JIR)», у черзі, відхилений), ZKI і JIR, текст помилки CIS; фільтр за статусом і пошук за номером чи замовленням.
• «Deliver waiting receipts now» надсилає чергу одразу, не чекаючи крону, а «Send all refused receipts again» і «Send again» на окремому чеку — відхилені чеки після виправлення налаштувань.
• Зверху сторінки видно середовище (TEST або PRODUCTION) і повідомлення, якщо CIS відхилив чеки.

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

У кожному замовленні — блок «Fiskalizacija» з номером, сумою, статусом, ZKI, JIR і QR-кодом, а нотатки замовлення фіксують кожен крок: видано чек, фіскалізовано, у черзі, відхилено.

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

1. Пословний простір. Ви реєструєте вебмагазин у ePorezna і записуєте його позначку (наприклад, WEB1) — у плагіні вона має бути точно такою.
2. Налаштування. OIB обвезника, чи ви в системі ПДВ, позначка простору, номер пристрою, послідовність нумерації (за простором або пристроєм), рестарт 1 січня, оператор, статус замовлення, на якому видається чек, і останній використаний номер, якщо продовжуєте серію з іншої програми.
3. Сертифікат. Завантажте .p12 з паролем — для тесту DEMO, для робочого середовища робочий. Плагін показує власника й строк дії сертифіката, попереджає, якщо OIB у ньому не збігається з OIB обвезника (CIS відхилив би такі чеки з s005), і зберігає приватний ключ зашифрованим. «Check connection to CIS» перевіряє зв’язок методом echo.
4. Замовлення. Коли замовлення стає «В обробці» або «Виконано» (як оберете), плагін перевіряє суми й ставки локально, лише тоді бере наступний номер, рахує ZKI, будує й підписує RacunZahtjev і надсилає його в CIS.
5. Відповідь. CIS повертає JIR — плагін перевіряє підпис відповіді, зберігає JIR у замовленні й показує чек клієнту. Помилка s001–s005 чи s013 — чек «відхилено», причину видно в реєстрі, «Send again» після виправлення.
6. Збій зв’язку. CIS не відповів за кілька секунд (типово 8) — чек уже дійсний із ZKI, клієнт його бачить, а плагін доставляє його пізніше з позначкою NakDost і новим ідентифікатором повідомлення, з наростаючою паузою між спробами.

ПДВ береться з податкових рядків кожного замовлення й групується за ставкою — 25 %, 13 %, 5 % або 0 %. Ставку, якої CIS не приймає (наприклад, 19 %), плагін зупиняє ще до відправки, номер не витрачається. Рядки без податку йдуть як звільнення від ПДВ, «не підлягає оподаткуванню» або 0 % — як оберете; збори з назвою на кшталт «povratna naknada» — як Naknade. Копійки округлення між рядками й підсумком замовлення плагін зводить так, щоб сума чека збігалась до цента. Спосіб оплати задається для кожного шлюзу: G готівка, K картка, T рахунок, O інше.

Pro. Повернення WooCommerce — повне, часткове по позиціях або лише сумою — дає storno-чек з мінусовими сумами за тими самими ставками ПДВ; кожне наступне повернення «лише сумою» рахується від залишку після попередніх storno. Фіскальні дані й QR-код (25×25 мм) додаються в рахунки плагіна PDF Invoices & Packing Slips. Реєстр вивантажується в CSV (UTF-8 з BOM, роздільник «;», десяткова кома), а на вказану адресу приходять листи, коли CIS відхилив чек або недоступний.

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

• CIS: RacunZahtjev (фіскалізація), ProvjeraZahtjev (перевірка, лише тест), echo (зв’язок); адреси cistest.apis-it.hr:8449 і cis.porezna-uprava.hr:8449.
• ZKI — MD5 від підпису RSA-SHA256 рядка OIB + дата й час + номер + простір + пристрій + сума, як у розділі 12 специфікації v2.7.
• Підпис запиту — enveloped XMLDSig: Exclusive C14N, RSA-SHA256, дайджест SHA-256. RSA-SHA1 не використовується: тестовий CIS відхиляє його з 1 липня 2026, робочий — з 1 січня 2027.
• TLS і відповідь: з’єднання перевіряється за вкладеними сертифікатами FINA (Fina RDC 2020, Fina Demo CA 2020), підпис відповіді — за сертифікатом fiskalcis. Після заміни CA сертифікати оновлюються з новою версією або фільтром ccfh_ca_file.
• Нумерація з блокуванням: паралельні замовлення не отримують однакового номера й не лишають дірок; окремі лічильники для тесту й продакшну.
• Черга — Action Scheduler WooCommerce (або WP-Cron) з наростаючою паузою; чеки старші за 30 днів не надсилаються (CIS їх відхиляє).
• Сертифікат: приватний ключ зберігається в базі зашифрованим AES-256 ключем, похідним від солей сайту, або як файл поза веб-коренем через CCFH_CERT_FILE і CCFH_CERT_PASSWORD у wp-config.php.
• Модель CIS: константа CCFH_CIS_MOCK (ok, down, s002, s004, s006, s013) моделює відповіді лише в тестовому середовищі — щоб перевірити магазин до отримання сертифіката.
• Видалення плагіна прибирає сертифікати й завдання крону; реєстр, лічильники й налаштування лишаються як податкові записи. Константа CCFH_DELETE_DATA прибирає й їх.

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

1. Плагіни → Додати новий → Завантажити плагін: оберіть catcode-fiskalizacija-hr-for-woocommerce-1.0.0.zip і активуйте (WooCommerce має бути активний).
2. Зареєструйте вебмагазин як пословний простір у ePorezna і запишіть його позначку.
3. WooCommerce → Fiskalizacija → Settings: OIB обвезника, система ПДВ, позначка простору, номер пристрою, оператор, способи оплати.
4. Завантажте DEMO-сертифікат .p12 з паролем і натисніть «Check connection to CIS».
5. Оформіть тестові замовлення, перевірте чеки в реєстрі й кнопкою «Check at CIS test».
6. Покажіть налаштування бухгалтеру, перемкніть середовище на Production і завантажте робочий сертифікат.
7. Для Pro: вставте ліцензійний ключ з листа після оплати або запустіть 7-денний тріал у вкладці «Licence».