NAV Online Számla API — specifications

The NAV Online Számla API exposes 4 main endpoints for the full RTIR lifecycle: authentication, invoice submission, retrieval, and partner validation. Official documentation on onlineszamla.nav.gov.hu/dokumentumtar.

Environments and endpoints

• POST /tokenExchange — token retrieval (5 min)
• POST /manageInvoice — invoice submission (1 to 100)
• POST /queryTransactionStatus — transaction status
• POST /queryTransactionList — paginated list of transactions over a period
• POST /queryInvoiceData — XML invoice retrieval by ID
• POST /queryInvoiceCheck — invoice existence check (light)
• POST /queryInvoiceDigest — paginated summary of issued/received invoices
• POST /queryTaxpayer — partner validation and data by adószám

Authentication — TokenExchange

NAV authentication is multi-layered, designed to combine technical security and legal traceability:

1. Technical account (technikai felhasználó). Created by the company's main user via the onlineszamla.nav.gov.hu portal. It carries an identifier (login), a password and a shared signing key (signaturKey).
2. Software ID. Any API client must register with a unique software identifier in the format HU<adoszam>-<free_id> (e.g. HU12345678-MYERP01).
3. TokenExchange request. Sending a signed XML POST with the SHA-512 password hash and the SHA3-512 signature calculated on request parameters. See example below.
4. Response. NAV returns a base64 token valid 5 minutes. This token is inserted into all subsequent requests via the exchangeToken tag.
5. Renewal. No refresh token — tokenExchange must be called again upon expiry. In batch processing, it is recommended to request a token every 3-4 minutes to avoid mid-processing outages.

POST /invoiceService/v3/tokenExchange HTTP/1.1
Host: api.onlineszamla.nav.gov.hu
Content-Type: application/xml
Accept: application/xml

<?xml version="1.0" encoding="UTF-8"?>
<TokenExchangeRequest xmlns="http://schemas.nav.gov.hu/OSA/3.0/api">
  <common:header>
    <common:requestId>TEC-2026-05-19-XYZ123</common:requestId>
    <common:timestamp>2026-05-19T10:00:00.000Z</common:timestamp>
    <common:requestVersion>3.0</common:requestVersion>
    <common:headerVersion>1.0</common:headerVersion>
  </common:header>
  <common:user>
    <common:login>SZAMLA-LOGIN-123</common:login>
    <common:passwordHash cryptoType="SHA-512">...</common:passwordHash>
    <common:taxNumber>12345678</common:taxNumber>
    <common:requestSignature cryptoType="SHA3-512">...</common:requestSignature>
  </common:user>
  <software>
    <softwareId>HU12345678-MYERP01</softwareId>
    <softwareName>MyERP</softwareName>
    ...
  </software>
</TokenExchangeRequest>

ManageInvoice — submission

The manageInvoice endpoint is the heart of RTIR. It accepts 1 to 100 operations per call, each operation being either a creation (CREATE), a modification (MODIFY), a cancellation (STORNO), or a rectification (ANNUL).

• invoiceOperation = CREATE. Classical new invoice. The majority of cases.
• invoiceOperation = MODIFY. Corrective invoice (módosító számla) amending an original via the invoiceReference block in the XML.
• invoiceOperation = STORNO. Cancellation of an invoice issued in error. The cancelled invoice must have been previously declared via CREATE.
• invoiceOperation = ANNUL. Technical-only cancellation (INVOICE_ANNULMENT) — equivalent to a submission withdrawal, used when the declared invoice should never have been sent.
• Batch. Up to 100 operations grouped. Each operation carries a sequential index (1 to 100). The invoiceData XML data of each operation is base64-encoded individually.
• Compression. If compressedContent=true, the invoiceData block is GZIP-compressed before base64 — recommended from 10 invoices upward.

POST /invoiceService/v3/manageInvoice HTTP/1.1
Host: api.onlineszamla.nav.gov.hu
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8"?>
<ManageInvoiceRequest xmlns="http://schemas.nav.gov.hu/OSA/3.0/api">
  <common:header>...</common:header>
  <common:user>...</common:user>
  <software>...</software>
  <exchangeToken>aW52b2ljZS10b2tlbi1leGFtcGxlLi4u</exchangeToken>
  <invoiceOperations>
    <compressedContent>false</compressedContent>
    <invoiceOperation>
      <index>1</index>
      <invoiceOperation>CREATE</invoiceOperation>
      <invoiceData>PD94bWwgdmVyc2lvbj0iMS4wIi4uLg==</invoiceData>
    </invoiceOperation>
  </invoiceOperations>
</ManageInvoiceRequest>

QueryInvoice — retrieval

Three complementary variants to query already-submitted invoices:

• queryInvoiceData. Returns the complete XML of a given invoice by its invoiceNumber + supplierTaxNumber + invoiceDirection (OUTBOUND/INBOUND).
• queryInvoiceCheck. Light verification: does the invoice exist in NAV? No content return, just a boolean + transactionId. Very useful for production monitoring.
• queryInvoiceDigest. Paginated summary (max 100 lines per page, up to 500 pages) of issued or received invoices over a period. Filters by adószám, date, status. This is the API ERPs use to sync supplier invoices received via RTIR.

QueryTaxpayer — partner

Essential partner validation service for B2B:

• Input: adószám (Hungarian 8-digit tax number).
• Output: status (active/inactive), legal name, address, TEÁOR activity codes, VAT group membership (csoportos áfa).
• Target latency: < 1 second.
• Use cases. New partner data entry validation, pre-issuance cross-check, detection of deactivated (felfüggesztett) adószám.
• Detailed in dedicated page — QueryTaxpayer.

Error codes and logs

NAV returns structured error codes, grouped by family:

• Taxpayer-side logs. Obligation to retain XML request/response pairs for 11 years (VAT period), in case of NAV control.
• NAV-side logs. Available on the web portal for the last 90 days, accessible via technical login.

Limits and quotas

• Payload size: 17 MB after GZIP decompression.
• Batch: 100 operations per ManageInvoice call.
• Token: 5 minutes validity, re-issue on demand.
• Production rate limit: ~100 requests/second per adószám, up to 500 in short peaks.
• Test rate limit: ~10 requests/second — not representative of production.
• queryInvoiceDigest pagination: 100 lines per page, max 500 pages = 50,000 invoices per request.
• queryTransactionStatus polling: recommended every 30 s, never faster than 10 s.

Common pitfalls

• Confusing prod and test endpoints. An invoice submitted in test (api-test) has no legal value but often blocks ERPs at production switch — verify multi-environment configurations.
• Wrong password hash. NAV requires SHA-512 of the password in UPPERCASE hexadecimal. Many implementations use lowercase by default, triggering AUTH-INVALID_USER.
• Miscalculated SHA3-512 signature. The signature must concatenate requestId + timestamp + signaturKey + sumWeb (invoiceData hash) in a precise order. NAV's documentation is explicit but often misinterpreted.
• End-of-month rate limit saturation. Looped submissions of 100-invoice batches frequently exceed the quota — provide back-pressure mechanism on the ERP side.
• Polling too frequently. Polling queryTransactionStatus every 1-2 s triggers RATE-LIMIT_EXCEEDED and hides the real error. 30 s polling recommended.

Cross-links

• Hungary hub — full RTIR
• NAV Online Számla — platform
• RTIR — architecture
• XSD schemas v1.0 → v3.0
• QueryTaxpayer — partner validation
• NAV documentation — API
• NAV sandbox — test endpoint