NAV Online Számla для WooCommerce — угорські рахунки із замовлень напряму в NAV (API 3.0)

NAV Online Számla для WooCommerce — плагін для магазинів в Угорщині, які продають на WooCommerce і мусять звітувати про кожен виставлений рахунок у систему Online Számla податкової служби NAV. Плагін виставляє рахунок із замовлення і сам передає його дані в NAV Online Számla API 3.0 від імені вашого технічного користувача — так, як це роблять програми рахунків, але без платного сервісу посередині й без щомісячної підписки. Номер рахунку, ідентифікатор транзакції, статус обробки й попередження NAV зберігаються в замовленні.

Що потрібно від вас. Фірма, зареєстрована в Online Számla; технічний користувач, якого в вебінтерфейсі Online Számla створює основний користувач (primary user), з правом звітувати про рахунки, і два ключі — ключ підпису (XML aláírókulcs) і ключ обміну (XML cserekulcs). Тестова система NAV (onlineszamla-test.nav.gov.hu) потребує окремої реєстрації й окремого технічного користувача. Без цього плагін нічого не звітує: рахунки чекають у черзі, а вгорі адмінки висить нагадування.

Чесно про перевірку. Плагін перевірено на локальному магазині WooCommerce з вбудованим симулятором NAV, який відтворює відповіді за офіційною специфікацією API 3.0: DONE з попередженнями, ABORTED з помилками, техроботи, недоступність, втрачена відповідь, дублікат номера. Підписи запитів, хеш пароля і розшифровка токена збігаються з тестовими прикладами специфікації NAV, а кожен згенерований документ — рахунки приватним особам і фірмам, модифікуючі, сторно, покупці з ЄС — пройшов офіційні XSD NAV. З живим NAV, тестовим чи робочим, ми його ще не запускали: для цього потрібна реєстрація угорської фірми. Почніть із тестової системи NAV на своїй фірмі у 7-денному тріалі Pro — якщо NAV відповість не так, як описано в специфікації, виправимо оперативно.

Відповідальність за зміст рахунку і звіт лишається за магазином. Плагін будує рахунок з даних замовлення WooCommerce і з налаштувань ПДВ, які ви обираєте: кейси рядків без ПДВ (TAM, ATK, AAM), іноземні покупці (KBAET, EUFAD37, EAM, HO), паперовий чи електронний рахунок. Інтернет-магазин, що сам виставляє рахунки, фактично стає програмою рахунків, і до неї є вимоги постанови 23/2014 NGM — повідомити NAV про програму, мати документацію, давати експорт для перевірки. Плагін закриває з цього лише експорт документів; решту звірте з бухгалтером до переходу на PRODUCTION.

Що отримує адмін

• WooCommerce → NAV Online Számla: вкладки «Invoices», «Tax authority export», «Settings» і «Licence».
• Журнал рахунків: номер і тип документа (рахунок, модифікуючий, сторно), замовлення, покупець з adószám або «private person», сума, статус NAV, ідентифікатор транзакції, попередження або текст відмови; фільтр за статусом і пошук за номером, транзакцією, adószám чи замовленням. Посилання на деталі, друкований рахунок і XML.
• «Send / check now» надсилає чергу і перевіряє статуси одразу, не чекаючи крону.
• Повідомлення вгорі адмінки: відхилені або недоставлені документи, технічний користувач не налаштований, NAV зараз недоступний.

У кожному замовленні — блок «NAV Online Számla»: номер рахунку, тип покупця («Private person», «Hungarian company», «Other / foreign»), статус («Queued», «Processing at NAV», «Reported to NAV», «Rejected by NAV») і транзакція. Для замовлення без рахунку — кнопка «Issue and report», а якщо рахунок не можна скласти — пояснення, чого бракує. Нотатки замовлення фіксують кожен крок.

Відхилений рахунок видно одразу: у журналі, в замовленні й у повідомленні вгорі адмінки, поруч — коди й тексти помилок від NAV. Виправили замовлення — «Rebuild and send» перебудовує рахунок з тим самим номером: клієнт бачить рахунок лише після обробки в NAV, тож до нього відхилений документ не доходив. Непотрібний документ — «Discard». Якщо NAV відповів INVOICE_NUMBER_NOT_UNIQUE, бо цей рахунок у нього вже є, — «Mark as reported».

Як це виглядає для покупця

На чекауті з’являється поле «Tax number (for a company invoice)» (угорською — «Adószám (céges számlához)») і, поки WooCommerce ховає своє поле «Компанія», «Company name (for the invoice)». Без номера замовлення оформлюється як на приватну особу. Якщо номер введено, плагін перевіряє контрольну цифру і формат (8 або 11 цифр, пробіли прибирає), а номер без назви фірми не пропускає. Поле можна зробити обов’язковим для B2B-магазину, сховати або читати номер з мета-поля іншого плагіна. Працює на класичному і блоковому чекауті.

Після того як NAV обробив рахунок, клієнт отримує лист зі стандартним шаблоном WooCommerce і посиланням на рахунок, а в «Мій акаунт» і на сторінці замовлення з’являється блок «Invoice». Друкована сторінка — з підписами угорською й англійською: Számla, Eladó / Seller, Vevő / Buyer, adószám, дата виконання, спосіб оплати, ÁFA за ставками і підсумки. Гість відкриває рахунок за ключем замовлення, чужий користувач — ні.

Як це працює — крок за кроком

1. Технічний користувач. У вебінтерфейсі Online Számla основний користувач створює технічного користувача з правом звітувати про рахунки (і правом запитів — для перевірки adószám у Pro) та генерує ключ підпису й ключ обміну.
2. Підключення. WooCommerce → NAV Online Számla → Settings: логін, пароль, обидва ключі, збереження, потім «Check the connection» — плагін просить у NAV токен (tokenExchange) і дані продавця за adószám, нічого не звітуючи.
3. Продавець. Adószám, назва, адреса, банківський рахунок, статус ПДВ, серія номерів, спосіб видачі (ELECTRONIC або PAPER).
4. Чекаут. Покупець-фірма вводить adószám; хибний номер або номер без назви фірми не пройдуть.
5. Статус замовлення. Замовлення стає «Виконано» (або «В обробці» — як оберете) — плагін перевіряє дані за блокуючими правилами NAV (ставки ПДВ, дані покупця, adószám, поштовий індекс, банківський рахунок, номер 1–50 символів) і за XSD, лише тоді бере наступний номер. Рахунок, який не збирається, номер не витрачає.
6. Звіт. tokenExchange → manageInvoice (до 50 документів одним запитом) → queryTransactionStatus з наростаючою паузою.
7. Відповідь. DONE — «Reported to NAV», попередження WARN зберігаються в журналі й замовленні, клієнт отримує рахунок. ABORTED — «Rejected by NAV» зі списком помилок.
8. Збої. Мережа, помилки сервера NAV, MAINTENANCE_MODE, прострочений токен — повтор з наростаючою паузою. Помилка облікових даних техкористувача — черга чекає, у налаштуваннях видно останню помилку. Відповідь загубилась — через 5 хвилин плагін шукає транзакцію через queryTransactionList і або підхоплює її, або надсилає заново, тож рахунок не звітується двічі.

ПДВ береться з податків WooCommerce кожного замовлення: 27%, 18%, 5% і 0%, кілька ставок в одному рахунку. Для внутрішніх рядків без ПДВ треба один раз обрати кейс — TAM (звільнена діяльність), ATK (поза сферою ПДВ) або ставку 0%; поки кейс не обрано, такі рахунки не створюються. Продавець на alanyi adómentes звітує всі рядки як AAM, для pénzforgalmi elszámolás є окремий перемикач.

Експорт для податкової перевірки (23/2014 NGM § 11/A): вкладка «Tax authority export» віддає ZIP з усіма документами за діапазоном дат або номерів — кожен у вигляді InvoiceData XML, як його отримав NAV, плюс index.csv.

Pro. Повернення WooCommerce — по позиціях або сумою — дає модифікуючий рахунок (MODIFY), скасування замовлення з рахунком — сторно (STORNO). Документ ланцюжка будується в момент відправки, коли NAV уже обробив оригінал і попередні зміни: з правильним індексом модифікації й продовженням нумерації рядків. Фірми з ЄС з VAT-номером отримують рядки без ПДВ як KBAET або EUFAD37, покупці поза ЄС — EAM або HO; замовлення в EUR та інших валютах — з курсом HUF із налаштувань. Масова дія «Report to NAV (invoice)» у списку замовлень виставляє рахунки для минулих замовлень.

Що під капотом

• NAV Online Számla API 3.0: tokenExchange (токен розшифровується AES-128 вашим ключем обміну), manageInvoice, queryTransactionStatus, queryTransactionList для втрачених відповідей, queryTaxpayer для перевірки з’єднання і adószám у Pro.
• Підписи: requestSignature SHA3-512 (для manageInvoice — з хешами кожного документа), passwordHash SHA-512 — звірено з тестовими прикладами специфікації NAV.
• Офіційні схеми NAV (invoiceData, invoiceApi, invoiceBase, common — MIT, з github.com/nav-gov-hu) вкладено в плагін; кожен документ перевіряється за ними локально, без мережі.
• Облікові дані: пароль зберігається лише як хеш SHA-512, ключ підпису і ключ обміну — зашифровано (AES-256 з ключами сайту) або константами CCNAV_LOGIN, CCNAV_PASSWORD, CCNAV_SIGN_KEY, CCNAV_EXCHANGE_KEY у wp-config.php.
• Нумерація з блокуванням: два замовлення в ту саму секунду не отримають однаковий номер; окремі лічильники для TEST і PRODUCTION. Перемикання на PRODUCTION вимагає підтвердження.
• Симулятор NAV: константа CCNAV_NAV_MOCK у wp-config.php моделює відповіді NAV лише в тестовому середовищі — щоб перевірити магазин без реєстрації.
• Видалення плагіна прибирає облікові дані технічного користувача, крони й чергу; реєстр рахунків лишається як бухгалтерський запис. Константа CCNAV_DELETE_DATA прибирає все.

Як встановити

1. Плагіни → Додати новий → Завантажити плагін: оберіть nav-online-szamla-for-woocommerce-1.0.0.zip і активуйте.
2. WooCommerce → NAV Online Számla → Settings: дані продавця (adószám, назва, адреса, банківський рахунок) і серія номерів — окрема, якщо рахунки виписує ще й інша програма.
3. У блоці «Technical user (NAV)» — логін, пароль і обидва ключі, «Save settings», потім «Check the connection».
4. У блоці «VAT» оберіть кейс для рядків без ПДВ, якщо такі товари є.
5. Залиште середовище TEST (з техкористувачем тестової системи NAV), оформіть тестове замовлення і переведіть його у «Виконано» — у замовленні з’явиться номер і статус NAV.
6. Покажіть налаштування бухгалтеру і перемкніть середовище на PRODUCTION з техкористувачем робочої системи.
7. Для Pro: вставте ліцензійний ключ з листа після оплати або запустіть 7-денний тріал.