NAV OSA API

A developer-friendly wrapper around the Hungarian NAV Online Számla (Online Invoice) REST API v3.0.

Why this exists

The NAV Online Invoice System requires all Hungarian businesses to report invoice data in real-time to the tax authority. The official API uses XML request/response bodies with complex authentication involving SHA-512 password hashing, SHA3-512 request signatures, and AES-128 ECB token encryption.

NAV OSA API simplifies this by providing:

• JSON in, JSON out — no XML handling required on your side
• Automatic authentication — token exchange, signature calculation, and encryption handled internally
• Simplified invoice format — flat SimpleInvoice structure that maps to the full NAV XML schema
• Clear error messages — structured error responses with NAV error codes
• Simple REST endpoints — intuitive paths like POST /v1/invoices instead of XML-based operations

Quick example

# Check API health
curl https://api.osa.xme.sh/health

# Submit an invoice
curl -X POST https://api.osa.xme.sh/v1/invoices \
  -H "Content-Type: application/json" \
  -d '{
    "credentials": {
      "apiUrl": "https://api-test.onlineszamla.nav.gov.hu/invoiceService/v3",
      "login": "your-login",
      "passwordHash": "...",
      "taxNumber": "12345678",
      "signingKey": "...",
      "exchangeKey": "...",
      "softwareId": "HU12345678-01",
      "softwareName": "MyApp"
    },
    "operations": [
      {
        "operation": "CREATE",
        "invoice": { ... }
      }
    ]
  }'

# Query a taxpayer
curl -X POST https://api.osa.xme.sh/v1/taxpayer \
  -H "Content-Type: application/json" \
  -d '{
    "credentials": { ... },
    "taxNumber": "12345678"
  }'

Architecture

Your App  →  NAV OSA API (Hono + Bun)  →  NAV Online Számla REST API
  JSON            JSON ↔ XML                XML (government)

Hosted at: https://api.osa.xme.sh
Source:    https://github.com/matteohorvath/nav-osa-api

The wrapper handles all the complexity of XML serialization, cryptographic operations, and protocol requirements so you can focus on your business logic.

NAV environments

Environment	URL
Test	https://api-test.onlineszamla.nav.gov.hu/invoiceService/v3
Production	https://api.onlineszamla.nav.gov.hu/invoiceService/v3

tip

Always develop and test against the test environment first. You need separate credentials for test and production.