Hungary (NAV Online Számla)

Hungarian invoices must be reported to NAV, the Hungarian tax authority, in real time. Once you connect your NAV technical user, Space Invoices reports every invoice, credit note, void and advance invoice automatically, and shows NAV’s response on each document.

Prerequisites

Requirement	Description
Hungarian entity	An entity with `country_code: "HU"` and a Hungarian tax number
NAV technical user	Login, password, signing key and exchange key, created on the NAV Online Számla portal

Sandbox entities report to NAV’s test system and live entities to production. NAV issues separate technical users for the two, so create one for each environment you use.

Scope

Supported	Not supported
Invoices, credit notes and voids	Online cash registers and receipts
Advance invoices, and advance deductions on final invoices	Simplified, aggregate and self-billed invoices
Business, private-person, EU and non-EU customers	Margin schemes and VAT groups
VAT rates of 5%, 18% and 27%, plus exempt, out-of-scope and reverse-charge lines	One-Stop-Shop (OSS) invoices and MNB exchange rates
	More than one tax on a line, and other VAT rates

Until NAV reporting is enabled with verified credentials, a Hungarian entity can create drafts but can’t issue final invoices, unless you record an exemption.

Setup

1. Store your NAV credentials

Space Invoices verifies them with NAV. They are write-only and never returned by the API.

Store NAV technical user credentialstypescript

const _settings = await sdk.entities.storeEntityNavCredentials("ent_abc123", {
  login: "abc123XY",
  password: "correct-horse-battery-staple",
  signing_key: "synthetic-signing-key-value",
  exchange_key: "0123456789abcdef",
});

2. Enable NAV reporting

Enable NAV dispatchtypescript

const _settings = await sdk.entities.modifyEntityNavSettings("ent_abc123", {
  enabled: true,
});

Two optional settings go in the same call:

ecb_exchange_rate_elected: true if you invoice in foreign currencies and have elected ECB exchange rates with NAV.
cash_accounting: true if you use the cash accounting scheme (pénzforgalmi elszámolás).

Not required to report?

If your entity doesn’t have to report to NAV, record the exemption and its legal basis instead of enabling it:

Declare an entity exempt from NAV reportingtypescript

const _settings = await sdk.entities.modifyEntityNavSettings("ent_abc123", {
  obligation: "exempt",
  exemption_reason: "Entity only issues invoices out of scope of Hungarian real-time reporting.",
});

Issuing invoices

Create invoices as usual. Space Invoices reports each one to NAV when it is issued, and adds the wording Hungarian law requires to the PDF.

Zero-rate, exempt and reverse-charge lines

A line taxed at 5%, 18% or 27% (not reverse charge) needs nothing extra. Zero-rate, untaxed and reverse-charge lines need items[].e_invoicing.hungary.vat_treatment:

`type`	Use for
`exemption`	VAT-exempt supplies. Needs a `case` (for example `KBAET` for an intra-Community supply) and a `reason`. Some cases, such as `KBAET`, need a matching customer type.
`out_of_scope`	Supplies outside the scope of Hungarian VAT. Needs a `case` and a `reason`.
`domestic_reverse_charge`	Domestic reverse charge, where the customer accounts for the VAT. The line’s tax must be marked as reverse charge.
`no_vat_charge`	Any other line with no VAT.

An intra-Community exempt supply:

Create an invoice with an exempt linetypescript

const _invoice = await sdk.invoices.create({
  customer: {
    name: "Berlin Handels GmbH",
    country: "Germany",
    country_code: "DE",
    tax_number: "DE123456789",
    address: "Unter den Linden 1",
    city: "Berlin",
    post_code: "10117",
  },
  items: [
    {
      name: "Intra-Community supply of goods",
      quantity: 10,
      price: 1200,
      classification: "product",
      unit: "UN",
      taxes: [{ rate: 0, classification: "exempt" }],
      e_invoicing: {
        hungary: {
          vat_treatment: {
            type: "exemption",
            case: "KBAET",
            reason: "Intra-Community exempt supply of goods.",
          },
        },
      },
    },
  ],
});

Domestic reverse charge:

Create an invoice with a domestic reverse-charge linetypescript

const _invoice = await sdk.invoices.create({
  customer: {
    name: "Budapest Ipari Kft.",
    country: "Hungary",
    country_code: "HU",
    tax_number: "12345678-2-42",
    address: "Váci út 1.",
    city: "Budapest",
    post_code: "1133",
  },
  items: [
    {
      name: "Construction subcontracting service",
      quantity: 1,
      price: 500000,
      classification: "service",
      unit: "UN",
      taxes: [{ rate: 0, classification: "reverse_charge" }],
      e_invoicing: {
        hungary: { vat_treatment: { type: "domestic_reverse_charge" } },
      },
    },
  ],
});

Private-person customers

Mark the customer with is_end_consumer: true. The invoice keeps the customer’s name and address, and Space Invoices leaves them out of the NAV report, as NAV requires.

Create an invoice for a private-person customertypescript

const _invoice = await sdk.invoices.create({
  customer: {
    name: "Kovács János",
    is_end_consumer: true,
    country: "Hungary",
    country_code: "HU",
    address: "Kossuth Lajos utca 5.",
    city: "Debrecen",
    post_code: "4024",
  },
  items: [
    {
      name: "Consulting service",
      quantity: 1,
      price: 80000,
      classification: "service",
      unit: "UN",
      taxes: [{ rate: 27, classification: "standard" }],
    },
  ],
});

Corrections

To correct an invoice, issue a credit note that references it. Each credit note references exactly one original, which must already be reported to NAV.
Voiding an invoice reports the cancellation to NAV. Reported credit notes, advance invoices and invoices with applied advances can’t be voided. To undo a credit note, issue another credit note.
When you apply an advance invoice to a final invoice, Space Invoices adds the advance deduction to the final invoice’s report.

Once an invoice is issued and queued for NAV, it can’t be edited, unless NAV rejected the report (aborted or failed). Correct it with a credit note instead.

NAV status

Each reported document has a nav object with the current state:

`nav.status` values

reserved, dispatching, submitted

Being reported. No action needed.

done

NAV accepted the invoice.

done_with_warnings

NAV accepted the invoice with warnings, listed in nav.messages.

aborted, failed

NAV rejected the report or it didn't reach NAV. Fix the reported problem, then retry.

ambiguous

The outcome isn't known yet. Space Invoices keeps checking with NAV; you can also reconcile.

annulment_pending, annulled

A technical annulment is waiting for approval on the NAV portal, or was approved.

nav.retry_available, nav.reconcile_available and nav.annulment_available tell you which action you can take.

Retry a rejected report after fixing the problem, or after a technical annulment is approved:

Retry a failed NAV submissiontypescript

const _invoice = await sdk.invoices.retryInvoiceNav("inv_abc123");

Reconcile to check the outcome with NAV now, instead of waiting for the next automatic check:

Reconcile a NAV submission nowtypescript

const _invoice = await sdk.invoices.reconcileInvoiceNav("inv_abc123");

Technical annulment withdraws a report that NAV accepted by mistake, for example with the wrong invoice number. You approve it on the NAV portal. Business corrections need a credit note instead.

Technically annul a NAV submissiontypescript

const _invoice = await sdk.invoices.annulInvoiceNav("inv_abc123", {
  annulment_code: "ERRATIC_DATA",
  reason: "Duplicate submission cancelled.",
});

If a document stays ambiguous, check whether the invoice appears on the NAV Online Számla portal. If it doesn’t, contact support.

Common errors

Every NAV error has a code and a message that explains the fix. The ones you’re most likely to see:

Code	Fix
`NAV_NOT_CONFIGURED`	Complete Setup, or record an exemption.
`NAV_CREDENTIALS_REJECTED`	NAV rejected the credentials. Check them on the NAV portal and store them again.
`NAV_NUMBER_FORMATS_OVERLAP`	Give invoices, credit notes and advance invoices their own number formats. New Hungarian entities already have them.
`NAV_INVOICE_DATA_INVALID`	The response’s `issues` array names each field to correct.
`NAV_DOCUMENT_IMMUTABLE`	The invoice is already queued or reported. Issue a credit note.

See the Entities API Reference, Invoices API Reference, Credit Notes API Reference, and Advance Invoices API Reference.