NAV Online Számla for WooCommerce — Hungarian invoices from orders reported straight to NAV (API 3.0)

NAV Online Számla for WooCommerce is a plugin for shops in Hungary that sell on WooCommerce and have to report every invoice they issue to the Online Számla system of the Hungarian tax authority NAV. The plugin issues an invoice from the order and reports its data to the NAV Online Számla API 3.0 on behalf of your own technical user — the way invoicing programs do it, but without a paid service in between and without a monthly subscription. The invoice number, the transaction ID, the processing status and the NAV warnings are kept with the order.

What you need. A company registered in Online Számla; a technical user, created by the primary user in the Online Számla web interface, with the right to report invoices; and its two keys — the signature key (XML aláírókulcs) and the exchange key (XML cserekulcs). The NAV test system (onlineszamla-test.nav.gov.hu) needs a separate registration and a separate technical user. Without them the plugin reports nothing: invoices wait in the queue and a reminder stays at the top of the admin.

Honestly about testing. The plugin has been tested on a local WooCommerce shop with the built-in NAV simulator, which reproduces the answers described in the official API 3.0 specification: DONE with warnings, ABORTED with errors, maintenance, NAV unreachable, a lost answer, a duplicate number. The request signatures, the password hash and the token decryption match the test examples of the NAV specification, and every generated document — invoices to private persons and companies, modifying and cancelling invoices, EU buyers — passed the official NAV XSD. We have not yet run it against the live NAV, test or production: that takes a registered Hungarian company. Start with the NAV test system for your company during the 7-day Pro trial — if NAV answers differently from the specification, we fix it promptly.

Responsibility for the content of the invoice and the report stays with the shop. The plugin builds the invoice from the WooCommerce order data and from the VAT settings you choose: the cases for lines without VAT (TAM, ATK, AAM), foreign buyers (KBAET, EUFAD37, EAM, HO), paper or electronic invoice. An online shop that issues its own invoices effectively becomes an invoicing program, and Decree 23/2014 NGM sets rules for such programs — notifying NAV about the program, keeping documentation, providing an export for audits. Of these the plugin covers only the document export; check the rest with your accountant before switching to PRODUCTION.

What the admin gets

• WooCommerce → NAV Online Számla: the “Invoices”, “Tax authority export”, “Settings” and “Licence” tabs.
• Invoice register: number and document type (invoice, modifying, cancelling), order, buyer with the adószám or “private person”, total, NAV status, transaction ID, warnings or the refusal text; a status filter and search by number, transaction, adószám or order. Links to the details, the printable invoice and the XML.
• “Send / check now” sends the queue and checks the statuses right away, without waiting for cron.
• Notices at the top of the admin: rejected or undelivered documents, technical user not set up, NAV currently unreachable.

Every order has a “NAV Online Számla” box: the invoice number, the buyer type (“Private person”, “Hungarian company”, “Other / foreign”), the status (“Queued”, “Processing at NAV”, “Reported to NAV”, “Rejected by NAV”) and the transaction. An order without an invoice gets an “Issue and report” button, and if an invoice cannot be built, the box says what is missing. The order notes record every step.

A rejected invoice shows up right away: in the register, in the order and in the notice at the top of the admin, next to the NAV error codes and texts. Once the order is fixed, “Rebuild and send” rebuilds the invoice with the same number: the customer only sees an invoice after NAV has processed it, so the rejected document never reached them. A document you don’t need — “Discard”. If NAV answered INVOICE_NUMBER_NOT_UNIQUE because it already has this invoice — “Mark as reported”.

What the buyer sees

The checkout gets a “Tax number (for a company invoice)” field (“Adószám (céges számlához)” in Hungarian) and, while WooCommerce hides its own “Company” field, “Company name (for the invoice)”. Without a number the order is placed as a private person. When a number is entered, the plugin checks the check digit and the format (8 or 11 digits, spaces removed) and does not accept a number without a company name. The field can be made required for a B2B shop, hidden, or read from the order meta of another plugin. It works on the classic and the block checkout.

Once NAV has processed the invoice, the customer gets an e-mail in the standard WooCommerce template with a link to it, and an “Invoice” block appears in My Account and on the order page. The printable page carries Hungarian and English labels: Számla, Eladó / Seller, Vevő / Buyer, adószám, delivery date, payment method, ÁFA by rate and totals. A guest opens the invoice with the order key; another user cannot.

How it works — step by step

1. Technical user. In the Online Számla web interface the primary user creates a technical user with the right to report invoices (and the query right — for the adószám check in Pro) and generates the signature key and the exchange key.
2. Connection. WooCommerce → NAV Online Számla → Settings: login, password, both keys, save, then “Check the connection” — the plugin asks NAV for a token (tokenExchange) and for the seller data by adószám, reporting nothing.
3. Seller. Adószám, name, address, bank account, VAT status, number series, invoice appearance (ELECTRONIC or PAPER).
4. Checkout. A company buyer enters the adószám; a wrong number or a number without a company name won’t pass.
5. Order status. The order becomes “Completed” (or “Processing” — your choice) — the plugin checks the data against the NAV blocking rules (VAT rates, buyer data, adószám, postcode, bank account, number of 1–50 characters) and the XSD, and only then takes the next number. An invoice that cannot be built uses no number.
6. Reporting. tokenExchange → manageInvoice (up to 50 documents per request) → queryTransactionStatus with a growing pause.
7. Answer. DONE — “Reported to NAV”, WARN warnings are kept in the register and the order, the customer gets the invoice. ABORTED — “Rejected by NAV” with the error list.
8. Failures. Network, NAV server errors, MAINTENANCE_MODE, an expired token — retried with a growing pause. Wrong technical user credentials — the queue waits and the settings show the last error. A lost answer — after 5 minutes the plugin looks the transaction up with queryTransactionList and either picks it up or sends again, so an invoice is never reported twice.

VAT comes from the WooCommerce taxes of each order: 27%, 18%, 5% and 0%, several rates on one invoice. For domestic lines without VAT you choose the case once — TAM (exempt activity), ATK (outside the scope of VAT) or the 0% rate; until you do, such invoices are not created. A seller under alanyi adómentes reports every line as AAM, and pénzforgalmi elszámolás has its own switch.

Tax audit export (Decree 23/2014 NGM § 11/A): the “Tax authority export” tab gives a ZIP with every document of a date or number range — each as the InvoiceData XML NAV received — plus index.csv.

Pro. A WooCommerce refund — by item or by amount — gives a modifying invoice (MODIFY), cancelling an invoiced order gives a cancelling invoice (STORNO). A document of the chain is built when it is sent, after NAV has processed the original and the earlier changes: with the right modification index and continued line numbering. EU companies with a VAT number get their lines without VAT as KBAET or EUFAD37, buyers outside the EU as EAM or HO; orders in EUR and other currencies use the HUF exchange rate from the settings. The bulk action “Report to NAV (invoice)” in the orders list issues invoices for past orders.

Under the hood

• NAV Online Számla API 3.0: tokenExchange (the token is decrypted with AES-128 and your exchange key), manageInvoice, queryTransactionStatus, queryTransactionList for lost answers, queryTaxpayer for the connection check and the adószám check in Pro.
• Signatures: requestSignature SHA3-512 (for manageInvoice with the hash of every document), passwordHash SHA-512 — matched against the test examples of the NAV specification.
• Official NAV schemas (invoiceData, invoiceApi, invoiceBase, common — MIT, from github.com/nav-gov-hu) ship with the plugin; every document is validated against them locally, without the network.
• Credentials: the password is stored only as a SHA-512 hash, the signature key and the exchange key encrypted (AES-256 with the site keys) or as the constants CCNAV_LOGIN, CCNAV_PASSWORD, CCNAV_SIGN_KEY, CCNAV_EXCHANGE_KEY in wp-config.php.
• Numbering with a lock: two orders in the same second never get the same number; separate counters for TEST and PRODUCTION. Switching to PRODUCTION asks for confirmation.
• NAV simulator: the CCNAV_NAV_MOCK constant in wp-config.php simulates NAV answers in the test environment only — to try the shop without a registration.
• Deleting the plugin removes the technical user credentials, cron jobs and the queue; the invoice register stays as an accounting record. The CCNAV_DELETE_DATA constant removes everything.

Installation

1. Plugins → Add New → Upload Plugin: choose nav-online-szamla-for-woocommerce-1.0.0.zip and activate it.
2. WooCommerce → NAV Online Számla → Settings: the seller data (adószám, name, address, bank account) and the number series — a separate one if another program issues invoices too.
3. In “Technical user (NAV)” — the login, the password and both keys, “Save settings”, then “Check the connection”.
4. In “VAT” choose the case for lines without VAT if you sell such products.
5. Keep the TEST environment (with the technical user of the NAV test system), place a test order and set it to “Completed” — the order gets its number and NAV status.
6. Show the settings to your accountant and switch the environment to PRODUCTION with the technical user of the live system.
7. For Pro: paste the licence key from the e-mail after payment, or start the 7-day trial.