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