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

Модуль KSeF надсилає електронні рахунки до Krajowy System e-Faktur (Міністерство фінансів Польщі). Рахунки надсилаються у фоновому режимі, з автоматичним повторенням спроб у разі помилок.

Що таке KSeF

KSeF це платформа Міністерства фінансів для обробки рахунків у форматі XML. Плагін генерує рахунки у потрібному форматі та передає їх до KSeF.

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

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

Налаштування з’єднання

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

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

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

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

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

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

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

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

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

Увімкніть Автоматичне надсилання до KSeF, щоб плагін надсилав рахунок до KSeF після зміни статусу на “Виставлений”. Надсилання працює у фоновому режимі через Action Scheduler.

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

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

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

Плагін використовує Action Scheduler (вбудований у WooCommerce) для надсилання у фоновому режимі:

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

Генерування XML

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

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

XML валідується перед надсиланням. У разі помилок валідації рахунок не буде надіслано, а в журналі з’явиться повідомлення.

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

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

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

Після прийняття плагін зберігає номер KSeF. Він видимий у панелі замовлення та на PDF.

Опитування статусу (polling)

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

Обробка помилок та повторення спроб

У разі помилок API плагін повторює спроби зі зростаючою затримкою (exponential backoff):

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

Після трьох невдалих спроб рахунок отримує статус “Error”. Адміністратор отримує e-mail про невдале надсилання.

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

• неправильний або прострочений токен 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. Тест перевіряє:

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

Найчастіші проблеми

Рахунок відхилено KSeF

1. Перевірте повідомлення про помилку в журналі WooCommerce
2. Найчастіші причини: відсутній NIP покупця, неправильна ставка VAT, неповні адресні дані
3. Виправте дані та надішліть повторно

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

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

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

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

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

• Система рахунків
• Інформація про KSeF
• Повідомити про проблему

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