Hungary Invoices (NAV Online Szamla 3.0 reporting API)

Official2 toolsLive

by junter1989k-ai · JavaScript

Hungary NAV Online Szamla 3.0 invoice reporting for AI agents: report invoice data, query status.

Topics

ai-agentclaudee-invoicehungaryinvoicemcpmcp-servernavtaxvatwishpool

Captured live from the server via tools/list.

submit_invoice

Report a Hungary invoice to NAV Online Számla 3.0 (számla adatszolgáltatás) — the national invoice-data reporting API of the Hungarian tax authority (NAV). This is REPORTING, not issuing: the merchant issues the actual invoice to the buyer; this tool submits the invoice data to NAV as legally required and returns a transactionId. Bring your own technical-user credentials via headers, all self-minted in the Online Számla web portal (onlineszamla.nav.gov.hu -> Technical users): x-nav-login, x-nav-password, x-nav-signkey, x-nav-exchangekey, x-nav-taxnumber (your 8-digit tax number). Runs against the NAV TEST environment by default (no legal effect); set header x-nav-mode: prod to report real invoices. The server exchanges a token, builds the InvoiceData XML, signs the request (SHA3-512), submits a CREATE operation, and returns the transactionId — then call query_transaction to read the processing result. Amounts are in HUF; each line carries a NET unit price and a Hungarian ÁFA (VAT) rate (27, 18, 5, or 0) — the server computes per-rate net/VAT and the invoice gross total.

Parameters15

supplier_name	string	required	Supplier (seller) legal name — your company. The supplier tax number comes from the x-nav-taxnumber header.
supplier_postal_code	string	optional	Supplier address postal code (default 0000).
supplier_city	string	optional	Supplier address city (default Budapest).
supplier_address_line	string	optional	Supplier street address line (default "-").
customer_name	string	required	Buyer legal name (or private person name).
customer_tax_number	string	optional	Buyer Hungarian tax number for B2B: 8 digits (core) or 11 digits (core+vatCode+countyCode, e.g. 12345678-2-41). Omit for a private person (customerVatStatus becomes PRIVATE_PERSON).
customer_postal_code	string	optional	Buyer address postal code (default 0000).
customer_city	string	optional	Buyer address city (default Budapest).
customer_address_line	string	optional	Buyer street address line (default "-").
invoice_number	string	required	Your invoice number (számlaszám) exactly as issued to the buyer, e.g. 2026/00123.
issue_date	string	optional	Invoice issue date (kelt) YYYY-MM-DD. Defaults to today (UTC).
delivery_date	string	optional	Fulfilment date (teljesítés) YYYY-MM-DD. Defaults to the issue date.
currency	string	optional	ISO currency code. Default HUF (only HUF is supported in v0.1).
payment_method	string	optional	Payment method. Default TRANSFER.
items	array	required	Line items. Each: name, quantity, unit_net_price (HUF, per unit, NET/excl. VAT), vat_rate (27, 18, 5, or 0).

Raw schema

{
  "type": "object",
  "properties": {
    "supplier_name": {
      "type": "string",
      "description": "Supplier (seller) legal name — your company. The supplier tax number comes from the x-nav-taxnumber header."
    },
    "supplier_postal_code": {
      "type": "string",
      "description": "Supplier address postal code (default 0000)."
    },
    "supplier_city": {
      "type": "string",
      "description": "Supplier address city (default Budapest)."
    },
    "supplier_address_line": {
      "type": "string",
      "description": "Supplier street address line (default \"-\")."
    },
    "customer_name": {
      "type": "string",
      "description": "Buyer legal name (or private person name)."
    },
    "customer_tax_number": {
      "type": "string",
      "description": "Buyer Hungarian tax number for B2B: 8 digits (core) or 11 digits (core+vatCode+countyCode, e.g. 12345678-2-41). Omit for a private person (customerVatStatus becomes PRIVATE_PERSON)."
    },
    "customer_postal_code": {
      "type": "string",
      "description": "Buyer address postal code (default 0000)."
    },
    "customer_city": {
      "type": "string",
      "description": "Buyer address city (default Budapest)."
    },
    "customer_address_line": {
      "type": "string",
      "description": "Buyer street address line (default \"-\")."
    },
    "invoice_number": {
      "type": "string",
      "description": "Your invoice number (számlaszám) exactly as issued to the buyer, e.g. 2026/00123."
    },
    "issue_date": {
      "type": "string",
      "description": "Invoice issue date (kelt) YYYY-MM-DD. Defaults to today (UTC)."
    },
    "delivery_date": {
      "type": "string",
      "description": "Fulfilment date (teljesítés) YYYY-MM-DD. Defaults to the issue date."
    },
    "currency": {
      "type": "string",
      "description": "ISO currency code. Default HUF (only HUF is supported in v0.1)."
    },
    "payment_method": {
      "type": "string",
      "enum": [
        "TRANSFER",
        "CASH",
        "CARD",
        "VOUCHER",
        "OTHER"
      ],
      "description": "Payment method. Default TRANSFER."
    },
    "items": {
      "type": "array",
      "minItems": 1,
      "description": "Line items. Each: name, quantity, unit_net_price (HUF, per unit, NET/excl. VAT), vat_rate (27, 18, 5, or 0).",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Item name (megnevezés)."
          },
          "quantity": {
            "type": "number",
            "description": "Quantity. Default 1."
          },
          "unit_net_price": {
            "type": "number",
            "description": "NET unit price in HUF (excludes ÁFA)."
          },
          "vat_rate": {
            "type": "number",
            "enum": [
              27,
              18,
              5,
              0
            ],
            "description": "Hungarian ÁFA rate percent: 27 standard, 18 reduced, 5 reduced, 0 zero-rated."
          }
        },
        "required": [
          "name",
          "unit_net_price",
          "vat_rate"
        ]
      }
    }
  },
  "required": [
    "supplier_name",
    "customer_name",
    "invoice_number",
    "items"
  ]
}

query_transaction

Check the NAV processing status of an invoice-data submission by its transactionId (returned by submit_invoice). Status values (per invoice index): RECEIVED (NAV received it), PROCESSING (validating), SAVED (stored — non-fatal warnings possible), DONE (successfully processed and stored — this is the success terminal), ABORTED (rejected — read validation_messages for the reason). Authenticates with your technical-user keys; safe to call anytime.

Parameters1

transaction_id

string

required

The transactionId returned by submit_invoice.

Raw schema

{
  "type": "object",
  "properties": {
    "transaction_id": {
      "type": "string",
      "description": "The transactionId returned by submit_invoice."
    }
  },
  "required": [
    "transaction_id"
  ]
}

README.md6 KBView on GitHub

Hungary Invoice MCP 🇭🇺 — How can my AI agent report an invoice to NAV Online Számla (számla adatszolgáltatás)?

Use it in 60 seconds

Paste this into your MCP client config (Claude Desktop, Cursor, Windsurf, or any MCP-capable agent):

json

{
  "mcpServers": {
    "hungary-invoice": {
      "type": "http",
      "url": "https://inv-hu.wishpool.app/mcp"
    }
  }
}

Nothing to install. Credentials, when you need them, travel as HTTP headers on each request and are never stored — see the threat model.

Or run it yourself

Would you rather not send production credentials to a server you do not control? Deploy this identical code to your own account and point your agent at your own URL:

bash

git clone https://github.com/junter1989k-ai/hungary-invoice-mcp && cd hungary-invoice-mcp && npx vercel --prod

MIT-licensed. Self-hosting removes us from the picture entirely, at no cost and with no loss of function.

Remote MCP server that lets any AI agent report Hungary invoice data to NAV Online Számla 3.0 — the Hungarian tax authority's national invoice-data reporting API (számla adatszolgáltatás). It builds the InvoiceData XML, runs the signed token-exchange + manageInvoice flow, and returns the government transactionId. Stateless, bring-your-own credentials, never stores anything.

This is reporting, not issuing. NAV Online Számla is a data-reporting system: the merchant issues the actual invoice to the buyer with their own invoicing software, and — as required by Hungarian law — reports the invoice data to NAV. This server does that reporting step; it does not deliver invoices to buyers.

Live endpoint: https://inv-hu.wishpool.app/mcp · Registry: app.wishpool/hungary-invoice-mcp

Quick start

json

{
  "mcpServers": {
    "hungary-invoice": {
      "type": "http",
      "url": "https://inv-hu.wishpool.app/mcp",
      "headers": {
        "x-nav-login": "your-technical-user-login",
        "x-nav-password": "your-technical-user-password",
        "x-nav-signkey": "your-signature-key",
        "x-nav-exchangekey": "your-16-byte-exchange-key",
        "x-nav-taxnumber": "12345678",
        "x-nav-mode": "prod"
      }
    }
  }
}

Self-mint all five keys as a technical user in the Online Számla web portal (onlineszamla.nav.gov.hu → Technical users). Omit x-nav-mode to stay in the NAV TEST environment (no legal effect). Your keys stay with you — this server never stores them.

Tools

Tool	What it does
`submit_invoice`	Report an invoice to NAV — `supplier_name`, `customer_name` (+ optional `customer_tax_number` for B2B), `invoice_number`, `items` (name, quantity, `unit_net_price`, `vat_rate` 27/18/5/0) in, transactionId out. Supplier tax number comes from the header; per-rate net/VAT and the gross total are computed for you (HUF). Omit `customer_tax_number` for a private person.
`query_transaction`	Read the NAV processing status by transactionId: `RECEIVED` / `PROCESSING` / `SAVED` / `DONE` (success terminal) / `ABORTED` (rejected — see `validation_messages`).

Owner policy guardrails ride optional headers (x-agentpay-max-amount, x-agentpay-approval-above, x-agentpay-allowed-tools) — set by the human owner in client config; the agent cannot relax them. The cap applies to the invoice gross total (HUF).

Scope & honest gaps

CREATE only in v0.1. Correcting or cancelling a reported invoice (MODIFY / STORNO operations) is a separate reporting flow kept out of this version to stay focused. To correct a mistake, issue a modifying/cancelling invoice to the buyer and report it.
HUF only. Foreign-currency invoices (with exchangeRate) are not supported yet.
Domestic B2B / private person. customerVatStatus is DOMESTIC (with buyer tax number) or PRIVATE_PERSON (without). OTHER (foreign) buyers and special cases (margin scheme, reverse charge, EKÁER, product codes) are out of scope for v0.1.

How it works (NAV Online Számla 3.0 flow)

Token exchange: POST /tokenExchange — sign the request with SHA3-512 over requestId + timestamp(yyyyMMddHHmmss) + signKey, hash the password with SHA-512; NAV returns encodedExchangeToken, which we AES-128-ECB decrypt with your exchange key.
Report: build the InvoiceData XML (namespace schemas.nav.gov.hu/OSA/3.0/data), base64 it, and POST /manageInvoice with a CREATE operation. The manageInvoice signature is index-chained: SHA3-512( requestId + timestamp + signKey + SHA3-512(operation + base64data) ). NAV returns a transactionId.
Status: POST /queryTransactionStatus with that transactionId returns the per-invoice invoiceStatus and any technical/business validation messages.

The password hash, request signature and token decryption all happen in memory per-request; nothing is embedded or stored.

Develop

bash

node test/serve.js   # local server on :3243
node test/e2e.js     # protocol + validation + ÁFA-math + signature test vectors + LIVE probe against api-test.onlineszamla.nav.gov.hu

The e2e suite asserts the signature algorithm against fixed test vectors (fixed input → fixed SHA3-512 / SHA-512 / AES-128 output) and makes a real call to the government NAV test API: a well-formed tokenExchange with placeholder credentials runs the full SHA3-512 signing path and surfaces NAV's native INVALID_SECURITY_USER error — the deepest verification possible without a portal-minted technical user.

Safety

Pure stateless translation layer straight to the government NAV API. The NAV registration and tax context stay with the merchant; credentials travel per-request in headers, nothing is stored or logged. Privacy policy.

Sister servers

National e-invoices: Poland KSeF 2.0 inv-pl · Mexico CFDI 4.0 inv-mx · Chile DTE inv-cl · Brazil NF-e inv-br · Local payments in 81 countries, one family: mcp.wishpool.app · Taiwan e-invoice 電子發票 included.

MIT licensed.

Install

Tools (2)

submit_invoicequery_transaction

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://inv-hu.wishpool.app/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "hungary-invoice-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://inv-hu.wishpool.app/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.