NIP на касі

Бізнес-клієнти потребують поля NIP на касі для отримання рахунку-фактури ПДВ. Плагін Polski for WooCommerce додає поле NIP з валідацією контрольної суми та верифікацією в базі GUS REGON. Дані компанії заповнюються автоматично.

Функціональність

Модуль NIP верифікує номер на трьох рівнях:

Валідація формату - перевірка, чи номер складається з 10 цифр
Валідація контрольної суми - алгоритм перевірки контрольної цифри NIP
Верифікація GUS REGON - перевірка в базі Головного статистичного управління з автоматичним отриманням даних компанії

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

Перейдіть до WooCommerce > Налаштування > Polski > Каса та налаштуйте розділ “NIP”.

Основні налаштування

Налаштування	Значення за замовчуванням	Опис
Увімкнути поле NIP	Так	Додає поле NIP на сторінку каси
Обов’язкове поле	Ні	Чи є NIP обов’язковим
Позиція поля	Після поля компанії	Де відображати поле NIP
Валідація контрольної суми	Так	Перевіряє коректність номера NIP
Верифікація GUS REGON	Ні	Верифікує NIP у базі GUS
Автоматичне заповнення	Так	Отримує дані компанії з GUS

Умовне відображення

Поле NIP може відображатися:

Завжди - видиме для всіх клієнтів
Після позначення чекбоксу “Chcę fakturę” - з’являється після позначення
Після введення назви компанії - з’являється, коли поле “Firma” заповнене

Рекомендований варіант - відображення після позначення чекбоксу “Chcę fakturę” - це найзрозуміліше для клієнта.

Валідація контрольної суми

Алгоритм валідації NIP базується на системі ваг. Контрольна цифра (остання, десята цифра) обчислюється на основі дев’яти попередніх цифр.

Алгоритм

Ваги для послідовних цифр NIP: 6, 5, 7, 2, 3, 4, 5, 6, 7

NIP: 1234567890
Сума = 1*6 + 2*5 + 3*7 + 4*2 + 5*3 + 6*4 + 7*5 + 8*6 + 9*7 = 214
Залишок = 214 mod 11
Якщо залишок == остання цифра NIP → NIP коректний

Плагін виконує цю валідацію як на стороні клієнта (JavaScript), так і на стороні сервера (PHP). Серверна валідація завжди активна - її неможливо обійти, вимкнувши JavaScript.

Обробка форматів введення

Плагін приймає NIP у різних форматах:

1234567890 - тільки цифри
123-456-78-90 - з дефісами
123 456 78 90 - з пробілами
PL1234567890 - з префіксом країни

Усі формати нормалізуються до 10 цифр перед валідацією.

Верифікація GUS REGON

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

API GUS REGON вимагає ключа доступу. Плагін підтримує два середовища:

Середовище	URL	Ключ	Застосування
Тестове	`https://wyszukiwarkaregontest.stat.gov.pl/wsBIR/UslugaBIRzewnwordbir.svc`	`abcde12345abcde12345` (публічний тестовий ключ)	Розробка та тестування
Продуктивне	`https://wyszukiwarkaregon.stat.gov.pl/wsBIR/UslugaBIRzewnetrzny.svc`	Власний ключ від GUS	Робочий магазин

Отримання продуктивного ключа

Перейдіть на сайт: https://api.stat.gov.pl/Home/BirIndex
Зареєструйтеся та увійдіть
Подайте заявку на доступ до API REGON
Ключ буде надіслано на вказану електронну адресу (час очікування: 1-3 робочі дні)

Налаштування в плагіні

Перейдіть до WooCommerce > Налаштування > Polski > Каса > NIP
Увімкніть Верифікація GUS REGON
Виберіть середовище: Тестове або Продуктивне
Вставте ключ API (для продуктивного середовища)
Збережіть налаштування

Тестовий режим

У тестовому режимі плагін використовує публічний тестовий ключ GUS. Тестова база містить фіктивні дані - вона не призначена для верифікації справжніх номерів NIP. Використовуйте його виключно під час розробки та тестування інтеграції.

Автоматичне отримання даних компанії

Після верифікації NIP у GUS REGON плагін автоматично заповнює поля форми:

Поле WooCommerce	Дані з GUS
Firma (company)	Назва компанії
Адреса 1	Вулиця та номер
Місто	Населений пункт
Поштовий індекс	Поштовий індекс
Воєводство	Воєводство

Клієнт бачить заповнені дані та може їх скоригувати перед оформленням замовлення.

Поведінка автоматичного заповнення

Поля заповнюються лише якщо вони порожні або містять раніше отримані дані з GUS
Якщо клієнт вручну змінив дані, плагін не перезаписує зміни
Клієнт отримує повідомлення про отримання даних

Зберігання NIP

Номер NIP зберігається як метадані замовлення:

ключ: _billing_nip
видимий в адміністративній панелі замовлення
доступний у шаблонах електронних листів
доступний для експорту у звітах

Відображення NIP у замовленні

NIP автоматично відображається:

у деталях замовлення (адміністративна панель)
в електронному листі підтвердження замовлення
на сторінці “Мій обліковий запис > Замовлення”

Програмний доступ

Отримання NIP із замовлення

$order = wc_get_order($order_id);
$nip = $order->get_meta('_billing_nip');

Валідація NIP у PHP

function validate_nip(string $nip): bool {
    $nip = preg_replace('/[^0-9]/', '', $nip);

    if (strlen($nip) !== 10) {
        return false;
    }

    $weights = [6, 5, 7, 2, 3, 4, 5, 6, 7];
    $sum = 0;

    for ($i = 0; $i < 9; $i++) {
        $sum += (int) $nip[$i] * $weights[$i];
    }

    return ($sum % 11) === (int) $nip[9];
}

Hook валідації

add_filter('polski/checkout/validate_nip', function (bool $is_valid, string $nip): bool {
    // Додаткова логіка валідації
    // наприклад, перевірка у списку заблокованих NIP
    $blocked_nips = ['0000000000'];

    if (in_array($nip, $blocked_nips, true)) {
        return false;
    }

    return $is_valid;
}, 10, 2);

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

Верифікація GUS повертає помилку

Перевірте, чи ключ API коректний та активний
Перевірте, чи сервер може встановити з’єднання HTTPS з api.stat.gov.pl
API GUS іноді недоступне - плагін обробляє timeout та відображає відповідне повідомлення
Переконайтеся, що розширення PHP SOAP встановлено на сервері

Поле NIP не відображається

Перевірте, чи модуль NIP увімкнено
Перевірте налаштування умовного відображення
Очистіть кеш (плагіни кешування можуть кешувати форму каси)

Дані компанії не заповнюються автоматично

Перевірте консоль браузера на наявність помилок AJAX
Перевірте, чи endpoint REST API плагіна доступний
Переконайтеся, що NIP коректний і компанія існує в базі GUS

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

Повідомити про проблему

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