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 и либо подхватывает её, либо отправляет заново, так что счёт не уходит в NAV дважды.

НДС берётся из налогов 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-дневный триал.