KSeF E-Invoicing для OpenCart — е-фактури FA(3) у польський KSeF прямо із замовлень

KSeF E-Invoicing для OpenCart — модуль для магазинів у Польщі, які виставляють фактури компаніям. З 2026 року польські платники ПДВ передають фактури B2B через Національну систему е-фактур (Krajowy System e-Faktur, KSeF). Модуль перетворює замовлення OpenCart на структуровану фактуру в офіційному форматі FA(3) і надсилає її прямо в API KSeF 2.0 — без бухгалтерського SaaS посередині й без щомісячної підписки. Номер KSeF, офіційне підтвердження прийняття (UPO) і QR-код перевірки зберігаються в замовленні. Збірки — для OpenCart 4.x, 3.x і 2.3.

Що потрібно від вас. Токен KSeF для NIP вашої компанії: його генерують в Aplikacja Podatnika KSeF обраного середовища (розділ «Tokeny», дозволи на виставлення і перегляд фактур). Чесно про перевірку: модуль перевірено на офіційному тестовому середовищі KSeF Міністерства фінансів на OpenCart 4.1, 4.0.2, 3.0.5 і 2.3 — фактури прийнято з реальними номерами KSeF і UPO, а кожен XML валідний за офіційною XSD-схемою FA(3). У DEMO і PRODUCTION ми його ще не запускали: там той самий API, але потрібна справжня компанія. Спробуйте на своєму NIP у 7-денному тріалі Pro — якщо KSeF відповість інакше, ніж на тесті, виправимо оперативно.

Відповідальність за зміст фактури лишається за магазином: модуль будує FA(3) з даних замовлення OpenCart (товари, рядки підсумків, податки, адреси, NIP). Податкові рішення — як розкладати купон по ставках, коли 0 % WDT чи EX, коли замовлення вважається оплаченим, тип корекції — зроблено за логікою OpenCart і документацією Міністерства фінансів; перед переходом на PRODUCTION варто показати налаштування вашому бухгалтеру.

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

Модуль додає до магазину власне поле OpenCart «NIP (for a VAT invoice)» — його створює кнопка «Create the NIP field» у налаштуваннях. Поле показують штатний чекаут, реєстрація, сторінки акаунта і One Page Checkout (CatCode). Заповнювати його необов’язково: без NIP замовлення оформлюється як звичайне, і фактура в KSeF не створюється. Якщо NIP введено, модуль перевіряє контрольну суму — хибний номер зупиняє оформлення з помилкою біля поля. Приймаються записи «5265877635», «526-587-76-35» і «PL5265877635», а також номери VAT інших країн ЄС (для фактури таким покупцям потрібен Pro).

На телефоні все так само: помилка з’являється під полем, решта чекауту не змінюється. Покупець, який уже має акаунт в OpenCart 4, бачить поле NIP у своєму кабінеті, а не на чекауті, — так OpenCart показує поля акаунта. Для таких замовлень NIP можна вписати на сторінці замовлення в адмінці (див. нижче).

У Pro покупець отримує лист «Your invoice is in KSeF» з номером KSeF і QR-кодом, блок фактури на сторінці замовлення в кабінеті і друковану фактуру за захищеним посиланням. Друкована фактура — інформаційна копія; юридично чинна — XML у KSeF.

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

• Extensions → Modules → KSeF E-Invoicing: вкладки «Invoices», «Settings», «Tools» і «Licence».
• Токен KSeF зберігається зашифрованим, а ключ шифрування лежить у файлі storage/cc_ksef.key.php, не в базі; у формі видно лише «saved». Можна задати токен і константою CC_KSEF_API_TOKEN у config.php.
• «Check the connection to KSeF» проходить повну автентифікацію і пише, з яким NIP і в якому середовищі все працює, або показує помилку KSeF текстом (наприклад, 450 для хибного токена).
• Середовище — TEST, DEMO або PRODUCTION; поки увімкнено TEST чи DEMO, вгорі сторінки висить нагадування, що фактури не мають юридичної сили.
• Статуси, при яких виставляється фактура, продавець (Podmiot1) з KRS / REGON / BDO, формат номера, джерело ПДВ, одиниця виміру, префікс рядка доставки, рядки підсумків, які є оплатою (подарункові сертифікати, бонусний рахунок), термін оплати і IBAN для банківського переказу.

• Реєстр фактур: номер, замовлення, покупець з NIP, сума, статус, номер KSeF або текст відмови; фільтр за статусом, пошук і пагінація.
• «Send queued invoices now» надсилає чергу одразу, включно з фактурами, що чекають повтору.
• Нотатки в історії замовлення: «створено і поставлено в чергу», «прийнято, номер KSeF …» або причина відмови.

Панель KSeF на сторінці замовлення: NIP покупця з позначкою про перевірку, поле, щоб вписати або виправити NIP саме для фактури (поле клієнта при цьому не змінюється), статус, номер KSeF, QR-код KOD I і посилання на деталі. Для замовлення без фактури — кнопка «Issue KSeF invoice», а якщо фактури немає з певної причини (наприклад, замовлення споживача), панель пише, чому.

Сторінка фактури: дата, статус, номер KSeF, сесія, SHA-256 файлу, кнопки «Download XML», «Download UPO», друкована фактура, QR-код і повний XML FA(3), який бачив KSeF. Відхилена фактура показує текст KSeF польською і кнопки «Regenerate and send» (після виправлення даних) та «Discard». У Pro тут же — коригувальна фактура: кількості повернутих товарів по рядках і/або зменшення ціни, розкладене по ставках; модуль не дасть скоригувати більше, ніж лишилось.

Номер уже зайнято іншою програмою. Якщо на тому ж NIP ви виставляєте фактури ще й в іншій програмі або в іншому магазині з таким самим шаблоном номера, KSeF відмовить у другій фактурі з тим самим номером (код 440). Модуль звіряє файл з UPO оригіналу: свій файл (наприклад, коли загубилась відповідь KSeF) приймається з його номером KSeF, а чужий — ніколи. Така фактура стає «Rejected by KSeF» з поясненням і номером KSeF чужого документа; змініть формат номера (наприклад, префікс SKLEP/) і натисніть «Regenerate and send» — фактура отримає новий номер. Поки оригінал не вдається порівняти, фактура до 24 годин лишається в статусі обробки і перевіряється кожні 2 хвилини.

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

1. Налаштування. Токен KSeF → «Check the connection to KSeF» → дані продавця → «Create the NIP field» → увімкнути «Issue KSeF invoices». Почніть із середовища TEST.
2. Чекаут. Покупець-компанія вводить NIP. Хибний NIP не пройде; без NIP — звичайне замовлення без фактури.
3. Статус замовлення. Замовлення отримує обраний статус (за замовчуванням — «виконані» статуси магазину) — модуль будує фактуру FA(3) з наступним номером і ставить її в чергу. Рядки — з товарів замовлення і рядків підсумків: доставка, збори, купони (розкладені по ставках).
4. Відправка. На сервері з PHP-FPM фактура йде одразу після відповіді адмінці; крім того, чергу перевіряють планувальник OpenCart 4 (щогодини), cron-адреса з ключем з вкладки «Tools» (радимо кожні 5 хвилин) і відкриття адмінки.
5. Статус KSeF. Прийнято — номер KSeF і QR-код у замовленні, UPO з’являється в KSeF трохи пізніше за номер і підтягується наступним проходом; відхилено — текст причини в реєстрі, на сторінці фактури й в історії замовлення.
6. Збої. KSeF недоступний, 429 чи 503 — фактура чекає й повторюється сама; той самий XML байт-у-байт, тож другої фактури не буде.
7. Повернення (Pro). Замовлення отримує статус корекції (за замовчуванням Refunded / Reversed) — повна коригувальна фактура KOR з номером KSeF оригіналу; часткова — вручну на сторінці фактури.
8. Клієнт (Pro). Лист «Your invoice is in KSeF» з номером KSeF і QR-кодом KOD I, блок у кабінеті і друкована фактура.

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

• FA(3), схема 1-0E — порядок елементів строго за XSD Міністерства фінансів; усі фактури з тестових прогонів на OpenCart 4, 3 і 2.3 (B2B з кількома ставками, купони, EUR, ЄС, B2C, KOR) валідні за офіційною схемою.
• API KSeF 2.0 без сторонніх бібліотек: автентифікація токеном (RSA-OAEP SHA-256), онлайн-сесія, AES-256-CBC, опитування статусу, UPO. Access- і refresh-токени кешуються; 401 — повторна автентифікація.
• Суми як у замовленні. Купони й знижки розкладаються по ставках пропорційно нетто товарів, податок доставки і зборів береться з рядків податків замовлення, а залишок округлення потрапляє в найбільший рядок — P_15 фактури дорівнює сумі замовлення, і в злотих, і в другій валюті.
• Оплата: накладений платіж → форма 1, банківський переказ → форма 6 з IBAN з налаштувань; «оплачено» — за обраними статусами, інакше термін оплати.
• XML не змінюється після створення. Повтор — той самий файл, тож загублена відповідь KSeF дає 440 з оригінальним номером, а не другу фактуру. Дублікат 440 приймається лише для власного файлу (SkrotDokumentu з UPO оригіналу або SHA-256 файлу з KSeF).
• Нумерація з блокуванням (MySQL GET_LOCK): два замовлення в ту саму секунду не отримають однаковий номер.
• Курс NBP (Pro) — таблиця A за останній робочий день перед датою продажу; у XML — KursWaluty і ПДВ у злотих (P_14_xW). Друкована фактура в EUR показує курс, а ПДВ у злотих є в XML.
• Свої таблиці (cc_ksef_invoice, cc_ksef_order, cc_ksef_kv) і події OpenCart — без правок файлів ядра: install.xml у збірках 3.x і 2.3 не містить жодної модифікації.
• Офлайн-режими KSeF (offline24, аварійний, KOD II) не реалізовано: коли KSeF недоступний, фактури чекають у черзі.
• Видалення модуля. OpenCart сам стирає налаштування модуля, тож після перевстановлення токен і дані продавця вводяться знову; реєстр фактур, лічильники і ліцензія лишаються. Перемикач «Delete data on uninstall» прибирає й реєстр.

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

1. OpenCart 4: Extensions → Installer → завантажте cc_ksef.ocmod.zip (ім’я архіву не змінюйте) і натисніть «Install». OpenCart 3: Extensions → Installer → cc_ksef-oc3.ocmod.zip. OpenCart 2.3: залийте вміст папки upload/ з cc_ksef-oc2.ocmod.zip у корінь магазину (FTP або файловий менеджер хостингу) — штатний інсталятор 2.3 вимагає FTP-доступу, ручне заливання простіше.
2. Extensions → Extensions → Modules → KSeF E-Invoicing → «Install», потім «Edit».
3. Середовище TEST, токен з Aplikacja Podatnika KSeF того ж середовища, «Check the connection to KSeF».
4. Дані продавця, формат номера (власний префікс, якщо є інша програма фактурування) і джерело ПДВ; «Create the NIP field»; увімкніть «Issue KSeF invoices».
5. Оформіть тестове замовлення з NIP і переведіть його в статус «Complete» — за хвилину на сторінці замовлення буде номер KSeF.
6. Переходите на PRODUCTION — перемкніть середовище і вставте токен PRODUCTION.
7. Для Pro: вкладка «Licence» — ключ з листа після оплати або 7-денний тріал.