Інтеграція з KSeF

Модуль KSeF надсилає електронні рахунки-фактури до Національної системи е-рахунків (Міністерство фінансів). Рахунки-фактури надсилаються у фоні з автоматичним повтором при помилках.

Що таке KSeF

Національна система е-рахунків (KSeF) - це платформа Міністерства фінансів для виставлення, зберігання та отримання структурованих рахунків-фактур у форматі XML. Плагін забезпечує інструменти для інтеграції WooCommerce з KSeF - генерує рахунки-фактури у необхідному форматі XML та надсилає їх до системи.

Налаштування

Перейдіть до WooCommerce > Налаштування > Polski > Модулі PRO > KSeF.

Параметри з’єднання

Параметр	Опис
Увімкнути інтеграцію з KSeF	Активує модуль
Середовище	Тестове (sandbox) або Продуктивне
Ключ API (токен)	Токен авторизації, згенерований у порталі KSeF
NIP виставника	NIP, пов’язаний з обліковим записом KSeF

Тестове середовище

KSeF надає тестове середовище (sandbox) для перевірки інтеграції. Тестове середовище:

не вимагає справжнього ключа авторизації
приймає рахунки-фактури в ідентичному форматі, як продуктивне середовище
не передає дані до податкової служби
рекомендоване для перших тестів інтеграції

Після успішної перевірки в тестовому середовищі перемкніть на продуктивне середовище та введіть правильний ключ API.

Отримання токена API

Увійдіть до порталу KSeF: https://ksef.mf.gov.pl/
Перейдіть до розділу управління токенами
Згенеруйте новий токен із правами на виставлення рахунків-фактур
Скопіюйте токен та вставте його в налаштуваннях плагіна

Надсилання рахунків-фактур

Автоматичне надсилання

Після увімкнення опції Автоматичне надсилання до KSeF плагін надсилає рахунок-фактуру до KSeF автоматично після зміни його статусу на “Виставлений” (Issued). Надсилання відбувається асинхронно через Action Scheduler.

Ручне надсилання

У панелі замовлення в мета-боксі “Рахунки-фактури” доступна кнопка Надіслати до KSeF. Натискання додає завдання надсилання до черги Action Scheduler.

Асинхронна обробка

Плагін використовує Action Scheduler (вбудований у WooCommerce) для асинхронного надсилання рахунків-фактур. Це означає, що:

надсилання не блокує обробку замовлення
рахунки-фактури надсилаються в черзі, один за одним
у разі великої кількості рахунків-фактур система обробляє їх поступово

Генерація XML

Плагін генерує рахунок-фактуру у форматі XML, сумісному зі схемою KSeF (FA(2)). Документ XML містить:

заголовок із датою та типом рахунка-фактури
дані продавця (NIP, назва, адреса)
дані покупця (NIP, назва, адреса)
позиції рахунка-фактури (назва, кількість, ціна нетто, ставка ПДВ, вартість)
підсумок із розбивкою за ставками ПДВ
інформацію про оплату

XML валідується перед надсиланням. Якщо валідація виявить помилки, рахунок-фактура не буде надісланий, а в лозі з’явиться детальне повідомлення.

Відстеження статусу

Після надсилання рахунка-фактури до KSeF плагін відстежує його статус:

Статус	Опис
Queued	Рахунок-фактура додано до черги надсилання
Submitted	Рахунок-фактура надіслано до KSeF, очікується обробка
Accepted	Рахунок-фактура прийнято KSeF, присвоєно номер KSeF
Rejected	Рахунок-фактура відхилено - перевірте повідомлення про помилку
Error	Помилка зв’язку з API KSeF

Після прийняття рахунка-фактури плагін зберігає референсний номер KSeF у метаданих рахунка-фактури. Цей номер видно в панелі замовлення та на роздруківці PDF.

Опитування статусу

Плагін автоматично перевіряє статус надісланих рахунків-фактур. Після надсилання рахунка-фактури до KSeF плагін опитує API щодо статусу кожні кілька хвилин (через Action Scheduler), поки не отримає відповідь “Accepted” або “Rejected”.

Обробка помилок та повтори

У разі помилки зв’язку з API KSeF плагін застосовує механізм exponential backoff:

Спроба	Затримка
1. повтор	5 хвилин
2. повтор	25 хвилин
3. повтор	125 хвилин

Після трьох невдалих спроб рахунок-фактура отримує статус “Error” і потребує ручного втручання. Адміністратор отримує сповіщення електронною поштою про невдале надсилання.

Типові причини помилок:

неправильний або прострочений токен API
помилки валідації XML (наприклад, відсутні дані покупця)
тимчасова недоступність API KSeF
невідповідність NIP виставника токену

Хуки

`polski_pro_ksef_submit`

Дія, що викликається перед надсиланням рахунка-фактури до KSeF.

/**
 * @param int    $invoice_id ID faktury
 * @param string $xml        Wygenerowany XML faktury
 */
do_action('polski_pro_ksef_submit', int $invoice_id, string $xml);

Приклад:

add_action('polski_pro_ksef_submit', function (int $invoice_id, string $xml): void {
    // Zapisanie kopii XML przed wysyłką
    $upload_dir = wp_upload_dir();
    $xml_path = $upload_dir['basedir'] . '/polski-pro/ksef-xml/';

    if (! is_dir($xml_path)) {
        wp_mkdir_p($xml_path);
    }

    file_put_contents(
        $xml_path . "invoice-{$invoice_id}.xml",
        $xml
    );
}, 10, 2);

`polski_pro_ksef_check_status`

Дія, що викликається після перевірки статусу рахунка-фактури в KSeF.

/**
 * @param int    $invoice_id    ID faktury
 * @param string $status        Nowy status (accepted, rejected, error)
 * @param string $ksef_number   Numer referencyjny KSeF (tylko dla accepted)
 */
do_action('polski_pro_ksef_check_status', int $invoice_id, string $status, string $ksef_number);

Приклад:

add_action('polski_pro_ksef_check_status', function (int $invoice_id, string $status, string $ksef_number): void {
    if ($status === 'accepted') {
        // Powiadomienie zewnętrznego systemu o zaakceptowaniu faktury
        wp_remote_post('https://erp.example.com/api/ksef-update', [
            'body' => wp_json_encode([
                'invoice_id'  => $invoice_id,
                'ksef_number' => $ksef_number,
            ]),
            'headers' => ['Content-Type' => 'application/json'],
        ]);
    }
}, 10, 3);

Діагностика

Логи

Плагін записує всі операції KSeF до логу WooCommerce. Перейдіть до WooCommerce > Статус > Логи та виберіть джерело polski-pro-ksef.

Зареєстровані події:

надсилання рахунка-фактури (request/response)
перевірка статусу
помилки валідації XML
помилки зв’язку з API
повтори надсилання

Тестування з’єднання

У налаштуваннях модуля KSeF доступна кнопка Тестувати з’єднання. Вона надсилає тестовий запит до API KSeF та перевіряє:

правильність токена
зв’язок із сервером KSeF
відповідність NIP токену

Найпоширеніші проблеми

Рахунок-фактура відхилений KSeF

Перевірте повідомлення про помилку в лозі WooCommerce
Найпоширеніші причини: відсутній NIP покупця, неправильна ставка ПДВ, неповні адресні дані
Виправте дані та надішліть повторно

Токен API не працює

Переконайтеся, що токен не прострочений
Перевірте, чи має токен права на виставлення рахунків-фактур
Перевірте відповідність NIP у налаштуваннях плагіна з NIP, пов’язаним із токеном

Action Scheduler не обробляє чергу

Перевірте, чи WP-Cron працює правильно
Перейдіть до Інструменти > Scheduled Actions та перевірте стан черги
Перевірте, чи немає заблокованих завдань

Пов’язані ресурси

Ця сторінка має виключно інформаційний характер і не є юридичною консультацією. Перед впровадженням зверніться до юриста. Polski for WooCommerce - це програмне забезпечення з відкритим кодом (GPLv2), що надається без гарантій.