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-дневный триал.