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

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

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

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

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

У покупця на чекауті з’являється поле «NIP (for a VAT invoice)». Заповнювати його необов’язково: без NIP замовлення оформлюється як звичайне, і фактура в KSeF не створюється. Якщо NIP введено, модуль перевіряє контрольну суму — хибний номер зупиняє замовлення з поясненням. Приймаються записи «5265877635», «526-587-76-35» і «PL5265877635».

У WooCommerce 11 поле «Компанія» за замовчуванням приховане, і фактура пішла б на ім’я людини. Тому, поки поле WooCommerce приховане, модуль показує поруч з NIP своє поле «Company name (for a VAT invoice)»: з NIP воно обов’язкове, а назва фірми йде у фактуру як покупець. Увімкнете поле «Компанія» в налаштуваннях WooCommerce — модуль працюватиме з ним.

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

• WooCommerce → KSeF: вкладки «Invoices», «Settings» і «Licence».
• Токен KSeF зберігається в базі зашифрованим ключами, похідними від секретних солей сайту; у формі видно лише останні символи. Можна задати його й константою CCKSEF_TOKEN у wp-config.php.
• «Check the connection to KSeF» проходить повну автентифікацію і пише, з яким NIP і в якому середовищі все працює, або показує помилку KSeF текстом (наприклад, 450 для хибного токена).
• Середовище — TEST, DEMO або PRODUCTION; поки увімкнено TEST чи DEMO, вгорі сторінки висить нагадування, що фактури не мають юридичної сили.
• Продавець (Podmiot1): NIP, назва, адреса, контакти, KRS / REGON / BDO у підвалі фактури.
• Нумерація: формат на зразок FV/{YYYY}/{MM}/{N}, скидання щомісяця, щороку або ніколи, окремі лічильники для кожного середовища; зайняті номери пропускаються.
• ПДВ: з податків WooCommerce, фіксована ставка, включена в ціни, або продавець, звільнений від ПДВ (zw з підставою).

• Журнал фактур: номер, замовлення, покупець з NIP, сума, статус, номер KSeF або текст відмови; фільтр за статусом і пошук.
• Блок «KSeF invoice» у замовленні: номер фактури, статус, номер KSeF, QR-код, посилання на деталі, XML і UPO. Для замовлення без фактури — кнопка «Issue KSeF invoice».
• Нотатки замовлення: «створено і поставлено в чергу», «прийнято, номер KSeF …» або причина відмови.
• «Send queued invoices now» надсилає чергу одразу, включно з фактурами, що чекають повтору.

Відхилену фактуру видно одразу: у журналі, в замовленні й у повідомленні вгорі адмінки. Поруч — текст KSeF польською, як його повернуло Міністерство фінансів, і повний XML FA(3). Після виправлення (дата, дані покупця, ставка) — кнопка «Regenerate and send»; фактура, яка так і не потрапила в KSeF, скасовується кнопкою «Discard».

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

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

1. Налаштування. WooCommerce → KSeF → Settings: середовище, NIP і адреса продавця, токен KSeF, «Check the connection to KSeF».
2. Чекаут. Покупець-компанія вводить NIP (і назву фірми, якщо поле «Компанія» приховане). Хибний NIP не пройде.
3. Статус замовлення. Замовлення стає «Виконано» (або «В обробці» — як оберете) — модуль будує фактуру FA(3) з наступним номером і ставить її в чергу.
4. Відправка. Action Scheduler одразу відкриває онлайн-сесію KSeF, шифрує фактуру і надсилає її; крон кожні 5 хвилин — страховка.
5. Статус KSeF. Модуль опитує KSeF: прийнято — номер KSeF у замовленні, за хвилину-дві підтягується UPO; відхилено — текст причини в журналі й у замовленні.
6. Збої. KSeF недоступний, 429 чи 503 — фактура чекає й повторюється сама; той самий XML байт-у-байт, тож другої фактури не буде.
7. Повернення (Pro). Повернення WooCommerce по позиціях або сумою дає коригувальну фактуру KOR з номером KSeF оригіналу; вона чекає, поки оригінал отримає номер.
8. Клієнт (Pro). Лист «Your invoice is in KSeF» з номером KSeF і QR-кодом KOD I, блок у «Мій акаунт» і друкована фактура.

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

• FA(3), схема 1-0E — порядок елементів строго за XSD Міністерства фінансів; вісім типів документів (B2B з кількома ставками, zw, ЄС у EUR, B2C, експорт, KOR з номером KSeF і без, мінімальний) валідні за офіційною схемою.
• API KSeF 2.0 без сторонніх бібліотек: автентифікація токеном (RSA-OAEP SHA-256), онлайн-сесія до 20 фактур, AES-256-CBC, опитування статусу, UPO. Access- і refresh-токени кешуються; 401 — повторна автентифікація, 21470 (зміна ключа МФ) — ключі перечитуються.
• XML не змінюється після створення. Повтор — той самий файл байт-у-байт, тож загублена відповідь KSeF дає 440 з оригінальним номером, а не другу фактуру.
• Дублікат 440 приймається лише для власного файлу: SkrotDokumentu з UPO оригіналу порівнюється з SHA-256 нашого XML. Не вдалося порівняти — повтор до 24 годин, а не «прийнято навмання».
• Нумерація з блокуванням (MySQL GET_LOCK): два замовлення в ту саму секунду не отримають однаковий номер.
• Курс NBP (Pro) — таблиця A за останній робочий день перед датою продажу; у XML — KursWaluty і ПДВ у злотих (P_14_xW).
• Друкована фактура (Pro) — інформаційна копія: для фактури в EUR на друці немає суми ПДВ у злотих, вона є в XML, переданому в KSeF.
• Офлайн-режими KSeF (offline24, аварійний, KOD II) не реалізовано: коли KSeF недоступний, фактури чекають у черзі.
• Видалення плагіна прибирає токен, кеш токенів і крони; реєстр фактур і лічильники лишаються, щоб нумерація продовжилась після перевстановлення. Константа CCKSEF_DELETE_DATA прибирає все.

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

1. Плагіни → Додати новий → Завантажити плагін: оберіть ksef-e-invoicing-for-woocommerce-1.0.1.zip і активуйте.
2. WooCommerce → KSeF → Settings: увімкніть «Issue KSeF invoices», оберіть середовище (почніть з TEST), заповніть NIP, назву й адресу продавця.
3. Згенеруйте токен в Aplikacja Podatnika KSeF того ж середовища, вставте його і натисніть «Check the connection to KSeF».
4. Перевірте ставки податків WooCommerce і формат номера (дайте магазину власний префікс, якщо є інша програма фактурування).
5. Оформіть тестове замовлення з NIP і переведіть його у «Виконано» — за хвилину в замовленні буде номер KSeF.
6. Переходите на PRODUCTION — перемкніть середовище і вставте токен PRODUCTION.
7. Для Pro: вставте ліцензійний ключ з листа після оплати або запустіть 7-денний тріал.