Перевірка правильності номера ПДВ / VAT EU Pro модуль для PrestaShop

Найважливіші функції та переваги модуля

🌍 Валідація EU VAT — ланцюг провайдерів

• VIES REST API (Європейська Комісія) — офіційний сервіс ЄС, безкоштовний, без API-ключів, повертає номер консультації, що відповідає вимогам законодавства
• VATcomply — безкоштовний проксі до VIES, ліміт 2 запити/с/IP, без автентифікації
• VATLayer (APILayer) — комерційне API з високою доступністю, вимагає API-ключ, повертає повні дані компанії
• viesapi.eu — польський комерційний проксі VIES з HTTP Basic Auth, швидкий час відповіді
• Налаштовуваний ланцюг із 3 слотів — виберіть Provider 1 (основний), Provider 2 (резервний), Provider 3 (останній шанс)
• Автоматичний fallback — якщо перший провайдер поверне помилку або timeout, модуль автоматично спробує наступного
• Per-provider timeout і retry — налаштуйте окремі ліміти часу для кожного провайдера
• Per-provider cache TTL — різні строки дії кешу для кожного API
• Захист від дублікатів — JavaScript блокує вибір того самого провайдера у 2 слотах, серверна валідація на боці PHP

🇵🇱 Валідація польського NIP — реєстр GUS

• Інтеграція з GUS BIR1.1 API — офіційний державний реєстр REGON, безкоштовний ключ з api.stat.gov.pl
• Проста перевірка контрольної суми NIP — зважений алгоритм відповідно до офіційної специфікації MF
• Відхилення неправильних шаблонів — усі нулі, самі одиниці, однакові цифри — блокуються автоматично
• Валідація checksum = 10 — відповідно до офіційної специфікації NIP, значення 10 є недійсним
• Отримання даних компанії — назва, адреса, поштовий індекс, населений пункт із реєстру REGON
• Налаштовуваний timeout і retry — адаптація до продуктивності серверів GUS

💰 Автоматичне звільнення від VAT (0% reverse charge)

• Автоматичне застосування 0% VAT для перевірених клієнтів B2B з країн ЄС
• Налаштовувана країна джерела — вимкнення 0% для внутрішніх транзакцій (відповідно до закону про VAT)
• Список країн для перевірки VIES — виберіть конкретні країни, на які поширюється валідація
• Опція "дозволити, якщо валідація не вдалася" — не блокуйте реєстрацію у разі збою VIES
• Інтеграція з рушієм податків PrestaShop через `TaxManagerInterface`

👥 Автоматичне керування групами клієнтів

• Автопризначення групи після валідації — наприклад, автоматично додайте до групи "B2B" або "Звільнені від VAT"
• Збереження наявних груп — клієнт не втрачає жодної зі своїх поточних груп
• Ідемпотентне додавання — без дублікатів навіть при багаторазовій валідації
• Валідація Group::isLoadedObject — безпека у разі видалених груп

📧 Сповіщення e-mail

• E-mail адміністратору при новій B2B-валідації — миттєва інформація про нового корпоративного клієнта
• E-mail при невдачі повторної валідації — безпекове сповіщення, коли VAT перестав бути дійсним
• Багатомовні шаблони (польська, англійська) — редагуються у стандартному редакторі PS
• Налаштовувана адреса відправника — за замовчуванням e-mail магазину з налаштувань PS

🔄 Повторна валідація при зміні статусу замовлення

• Автоматична повторна перевірка VAT при зміні замовлення на вибраний статус (наприклад, "Платіж прийнято")
• Захист відповідності — виявлення ситуацій, коли VAT втратив чинність між замовленням і відправленням
• Повний аудит-лог — кожна повторна валідація записується з consultation number VIES
• Multishop-aware — використовує контекст магазину із замовлення, а не поточного селектора адміністратора

📊 Професійна панель адміністратора

• 5 секцій dashboard — ланцюг провайдерів, статистика валідації, останні валідації, телеметрія провайдерів, посібник швидкого старту
• Візуалізація ланцюга — 3 слоти з іконками, назвами, статусом (активний/вимкнений/немає ключа)
• 7 KPI-карток — усього, правильні, неправильні, останні 7 днів, VIES, GUS, записи кешу
• Таблиця останніх 10 валідацій — номер VAT, джерело, результат, компанія, клієнт, дата
• Телеметрія провайдерів — per-provider success rate, кількість перевірок, останній виклик
• Картки провайдерів із badges FREE/PAID — чітка інформація про витрати
• Автоматична кольорова індикація — зелений (OK), помаранчевий (warn), червоний (error)

🏪 Повна підтримка multistore

• Ізоляція кешу для кожного магазину — колонка `id_shop` у таблиці кешу, composite UNIQUE key
• Ізоляція логів для кожного магазину — аудит для кожної юридичної особи
• Per-shop конфігурація — різні провайдери, API-ключі, групи клієнтів для кожного магазину
• Shop-aware повторна валідація — hook використовує контекст замовлення, а не адміністратора
• Автоматичне встановлення defaults для всіх магазинів під час інсталяції

⚡ Продуктивність і оптимізація

• Дворівневий кеш — статичний (in-memory) + persistent (база даних)
• Negative cache — без повторних DB-запитів для невалідованих номерів
• TTL enforcement при читанні — старі записи автоматично ігноруються
• Lazy render dashboard — статистика обчислюється лише на вкладці Панель
• Одиничний агрегований SQL-запит — 6 COUNT(*) → 1 SUM(CASE WHEN)
• Read replica для всіх читань (`_PS_USE_SQL_SLAVE_`)
• Виділені індекси — idx_date, idx_source, idx_shop
• Зберігання логів через CRON — автоматичне очищення після налаштовуваного періоду (default 365 днів)

🔒 Безпека

• CSRF tokens у всіх точках входу (front, admin, CRON)
• Timing-safe comparison (`hash_equals`) для валідації токенів
• Повна санітизація SQL — `pSQL()`, `(int)`, `bqSQL()` всюди
• Екранування Smarty — `htmlall:UTF-8` для всіх змінних у шаблонах
• SSL verification — `CURLOPT_SSL_VERIFYPEER=true` у всіх викликах провайдерів
• Whitelist провайдерів — неможливо зберегти неправильного провайдера в ланцюгу
• _PS_VERSION_ guard у кожному PHP-файлі
• AdminSecurity annotation у Symfony admin controller

🛠️ Сумісність і залежності

• PrestaShop 1.7.0 – 9.x — повна сумісність, версійовані guard-и
• PHP 7.0 – 8.5 — без сучасного синтаксису без guard-ів
• MySQL 5.6+ / MariaDB 10.x+ — charset utf8mb4
• Zero Composer / vendor — власний PSR-4 autoloader (15 рядків коду)
• Dual translation system — trans() + l() fallback працює на всіх версіях PS
• Повні польські переклади — 200+ записів у pl.php і файлах XLF
• Dual theme support — legacy (Smarty) і modern (Symfony) admin themes

👨‍💼 Адміністративна панель — 10 вкладок

• Панель — dashboard із 5 секціями, вкладка за замовчуванням
• Налаштування — загальні опції валідації, ISO check, auto-group, cache TTL, повторна валідація
• Налаштування EU VAT — увімкнення VIES, список країн, ставка 0%, allow on fail, країна джерела
• Ланцюг провайдерів — 3 select-и з JavaScript, що блокує дублікати
• VIES REST — timeout, cache TTL, retry (без ключів)
• VATcomply — timeout, cache TTL, retry (без ключів)
• VATLayer — API key, timeout, cache TTL, retry
• viesapi.eu — identifier, access key, timeout, cache TTL, retry
• Конфігурація GUS — увімкнення, країна, ключ користувача, allow on fail, timeout, cache TTL, retry
• Інструменти — URL CRON для очищення кешу та логів

🎯 Для кого цей модуль?

• Магазини PrestaShop, що продають компаніям (B2B) в Європейському Союзі
• Продавці, які виставляють рахунки-фактури зі зворотним нарахуванням (reverse charge)
• Магазини, що обслуговують польський ринок і потребують перевірки NIP у GUS
• Платформи multistore з різними юридичними особами для кожного магазину
• Продавці, яким потрібен аудит валідації VAT, що відповідає податковим вимогам
• Магазини з великим обсягом B2B-транзакцій, яким потрібні кеш і висока доступність