API NAV Online Számla — spécifications

L'API NAV Online Számla expose 4 endpoints principaux pour le cycle de vie complet du RTIR : authentification, soumission de factures, récupération et validation de partenaire. Documentation officielle sur onlineszamla.nav.gov.hu/dokumentumtar.

Environnements et endpoints

• POST /tokenExchange — récupération d'un token (5 min)
• POST /manageInvoice — soumission de factures (1 à 100)
• POST /queryTransactionStatus — statut d'une transaction
• POST /queryTransactionList — liste paginée des transactions sur période
• POST /queryInvoiceData — récupération d'une facture XML par ID
• POST /queryInvoiceCheck — vérification existence d'une facture (light)
• POST /queryInvoiceDigest — résumé paginé des factures émises/reçues
• POST /queryTaxpayer — validation et données partenaire par adószám

Authentification — TokenExchange

L'authentification NAV est multi-couches, conçue pour combiner sécurité technique et traçabilité juridique :

1. Compte technique (technikai felhasználó). Créé par l'utilisateur principal de l'entreprise via le portail onlineszamla.nav.gov.hu. Il porte un identifiant (login), un mot de passe et une clé de signature partagée (signaturKey).
2. Software ID. Tout client API doit s'enregistrer avec un identifiant logiciel unique au format HU<adoszam>-<identifiant_libre> (ex. HU12345678-MYERP01).
3. Requête TokenExchange. Envoi POST XML signé avec le hash SHA-512 du mot de passe et la signature SHA3-512 calculée sur les paramètres de requête. Voir exemple ci-dessous.
4. Réponse. NAV retourne un token base64 valable 5 minutes. Ce token est inséré dans toutes les requêtes ultérieures via la balise exchangeToken.
5. Renouvellement. Pas de refresh token — il faut ré-appeler tokenExchange à expiration. En batch, il est recommandé de demander un token toutes les 3-4 minutes pour éviter les coupures en cours de traitement.

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 — soumission

L'endpoint manageInvoice est le cœur du RTIR. Il accepte 1 à 100 opérations par appel, chaque opération étant soit une création (CREATE), une modification (MODIFY), une annulation (STORNO), ou une rectification (ANNUL).

• invoiceOperation = CREATE. Nouvelle facture classique. La majorité des cas.
• invoiceOperation = MODIFY. Facture corrective (módosító számla) qui amende une facture initiale via le bloc invoiceReference dans le XML.
• invoiceOperation = STORNO. Annulation d'une facture émise par erreur. La facture annulée doit avoir été préalablement déclarée via CREATE.
• invoiceOperation = ANNUL. Annulation technique-seulement (INVOICE_ANNULMENT) — équivalent d'un retrait de soumission, utilisé quand la facture déclarée n'aurait jamais dû partir.
• Batch. Jusqu'à 100 opérations regroupées. Chaque opération porte un index séquentiel (1 à 100). Les données XML invoiceData de chaque opération sont encodées base64 individuellement.
• Compression. Si compressedContent=true, le bloc invoiceData est compressé GZIP avant base64 — recommandé à partir de 10 factures.

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 — récupération

Trois variantes complémentaires pour interroger les factures déjà soumises :

• queryInvoiceData. Retourne le XML complet d'une facture donnée par son invoiceNumber + supplierTaxNumber + invoiceDirection (OUTBOUND/INBOUND).
• queryInvoiceCheck. Vérification légère : la facture existe-t-elle dans NAV ? Pas de retour de contenu, juste un booléen + transactionId. Très utile pour le suivi de production.
• queryInvoiceDigest. Résumé paginé (max 100 lignes par page, jusqu'à 500 pages) des factures émises ou reçues sur une période. Filtres par adószám, date, statut. C'est l'API qu'utilisent les ERP pour synchroniser les factures fournisseurs reçues via RTIR.

QueryTaxpayer — partenaire

Service de validation de partenaire essentiel pour le B2B :

• Entrée : adószám (numéro fiscal hongrois sur 8 chiffres).
• Sortie : statut (actif/inactif), dénomination, adresse, codes d'activité TEÁOR, appartenance à un groupe TVA (csoportos áfa).
• Latence cible : < 1 seconde.
• Cas d'usage. Validation à la saisie d'un nouveau partenaire, cross-check pré-émission, détection d'adoszám désactivé (felfüggesztett).
• Détaillé dans la page dédiée — QueryTaxpayer.

Codes d'erreur et logs

NAV retourne des codes structurés en cas d'erreur, regroupés par famille :

• Logs côté contribuable. Obligation de conserver les couples requête/réponse XML pendant 11 ans (durée TVA), en cas de contrôle NAV.
• Logs côté NAV. Tracés sur le portail web pour les 90 derniers jours, accessibles via login technique.

Limites et quotas

• Taille payload : 17 MB après décompression GZIP.
• Batch : 100 opérations par appel ManageInvoice.
• Token : 5 minutes de validité, ré-émission à la demande.
• Rate limit production : ~100 requêtes/seconde par adószám, jusqu'à 500 en pic court.
• Rate limit test : ~10 requêtes/seconde — non représentatif de la production.
• Pagination queryInvoiceDigest : 100 lignes par page, max 500 pages = 50 000 factures par requête.
• Polling queryTransactionStatus : recommandé toutes les 30 s, jamais plus rapide que 10 s.

Pièges courants

• Confondre prod et test endpoints. Une facture soumise en test (api-test) n'a aucune valeur juridique mais bloque souvent les ERP lors du switch de production — vérifier les configurations multi-environnements.
• Mauvais hash mot de passe. NAV exige SHA-512 du mot de passe en hexadécimal MAJUSCULE. Beaucoup d'implémentations utilisent minuscule par défaut, ce qui déclenche AUTH-INVALID_USER.
• Signature SHA3-512 mal calculée. La signature doit concaténer requestId + timestamp + signaturKey + sumWeb (hash invoiceData) dans un ordre précis. La doc NAV est explicite mais souvent mal interprétée.
• Saturation rate limit en pic fin de mois. Les batches de 100 factures soumis en boucle dépassent fréquemment le quota — prévoir un mécanisme de back-pressure côté ERP.
• Polling trop fréquent. Polling toutes les 1-2 s du queryTransactionStatus déclenche un RATE-LIMIT_EXCEEDED et cache l'erreur réelle. Polling 30 s recommandé.

Liens transverses

• Hub Hongrie — RTIR complet
• NAV Online Számla — plateforme
• RTIR — architecture
• Schémas XSD v1.0 → v3.0
• QueryTaxpayer — validation partenaire
• Documentation NAV — API
• Sandbox NAV — endpoint test