QueryTaxpayer — validation adószám

QueryTaxpayer est le service NAV de validation en temps réel des numéros fiscaux hongrois (adószám). Indispensable pour fiabiliser les flux B2B et éviter les rejets RTIR pour TaxNumber non reconnu.

Structure de l'adószám

L'adószám hongrois (numéro fiscal d'un contribuable assujetti) suit une structure rigide à 11 chiffres, divisée en trois blocs :

• Format standard. 12345678-2-42 ou sans tirets 12345678242.
• Préfixe UE. Pour les opérations intra-UE, ajout du préfixe HU sur le tax base number : HU12345678. Validation séparée via VIES.
• Particuliers. Les particuliers ont un adóazonosító jel (numéro d'identification personnelle, 10 chiffres, différent du adószám). Pas validable via queryTaxpayer.

Endpoint et requête

• URL prod : https://api.onlineszamla.nav.gov.hu/invoiceService/v3/queryTaxpayer
• URL test : https://api-test.onlineszamla.nav.gov.hu/invoiceService/v3/queryTaxpayer
• Méthode : POST + XML signé (mêmes headers common:header / common:user / software que les autres endpoints)
• Auth : nécessite un token TokenExchange préalable

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

<?xml version="1.0" encoding="UTF-8"?>
<QueryTaxpayerRequest xmlns="http://schemas.nav.gov.hu/OSA/3.0/api">
  <common:header>...</common:header>
  <common:user>...</common:user>
  <software>...</software>
  <taxNumber>12345678</taxNumber>
</QueryTaxpayerRequest>

<?xml version="1.0" encoding="UTF-8"?>
<QueryTaxpayerResponse xmlns="http://schemas.nav.gov.hu/OSA/3.0/api">
  <common:header>...</common:header>
  <common:result><common:funcCode>OK</common:funcCode></common:result>
  <software>...</software>
  <taxpayerValidity>true</taxpayerValidity>
  <taxpayerData>
    <taxpayerName>Példa Nagykereskedelmi Kft.</taxpayerName>
    <taxpayerShortName>Példa Kft.</taxpayerShortName>
    <taxNumberDetail>
      <base:taxpayerId>12345678</base:taxpayerId>
      <base:vatCode>2</base:vatCode>
      <base:countyCode>42</base:countyCode>
    </taxNumberDetail>
    <incorporation>SELF_EMPLOYED_OR_OTHER</incorporation>
    <taxpayerAddressList>
      <taxpayerAddressItem>
        <taxpayerAddressType>HQ</taxpayerAddressType>
        <taxpayerAddress>
          <base:countryCode>HU</base:countryCode>
          <base:postalCode>1051</base:postalCode>
          <base:city>Budapest</base:city>
          <base:streetName>Példa</base:streetName>
          <base:publicPlaceCategory>utca</base:publicPlaceCategory>
          <base:number>12</base:number>
        </taxpayerAddress>
      </taxpayerAddressItem>
    </taxpayerAddressList>
  </taxpayerData>
  <infoDate>2026-05-19T08:00:00.000Z</infoDate>
</QueryTaxpayerResponse>

Statuts retournés

Le champ taxpayerValidity est un booléen synthétique, mais d'autres champs détaillent la situation :

• taxpayerValidity = true. Numéro actif. Émission / réception de factures normale.
• taxpayerValidity = false. Numéro inactif ou inexistant. Plusieurs causes possibles, détaillées dans incorporation et les éléments taxpayerStatus.
• incorporation = SELF_EMPLOYED_OR_OTHER. Personne physique indépendante ou autre forme juridique.
• incorporation = INDIVIDUAL. Personne physique (rare en B2B).
• incorporation = ORGANIZATION. Entreprise ou organisation (PME, SA, BV, GmbH, etc.).
• taxpayerStatus = ACTIVE. Actif. Pas de restriction.
• taxpayerStatus = SUSPENDED. Suspendu (felfüggesztett). Ne pas émettre vers ce destinataire, le droit à déduction de la TVA en amont est bloqué côté acheteur.
• taxpayerStatus = DELETED. Radié. L'adoszám n'existe plus, ne sera jamais réactivé.

Groupes TVA (csoportos áfa)

Le régime de groupe TVA hongrois (csoportos áfa, art. 8 ÁFA tv.) permet à plusieurs sociétés liées de se regrouper fiscalement, avec un seul adoszám de groupe émetteur de factures :

• Identification. Un membre de groupe a vatCode = 5 (csoport tag) dans son adószám individuel. Le groupe lui-même a vatCode = 3 (groupe).
• Champ groupMemberTaxNumber. Sur les factures émises par un groupe, le champ groupMemberTaxNumber doit identifier le membre opérationnel responsable.
• Validation. queryTaxpayer retourne le bloc taxpayerGroupMembership indiquant l'appartenance et l'adózszám du groupe parent (parentTaxNumber).
• Effet RTIR. Le tax number du destinataire utilisé dans la facture est celui du groupe (au sens vatCode=3), pas du membre. Une erreur déclenche un rejet REF-INVALID_RECIPIENT.

Intégration ERP et caching

Bonne pratique pour les intégrations ERP traitant des volumes significatifs :

• Cache 24h. Les données NAV sont rafraîchies à J+1 max. Un cache local de 24h suffit pour 99 % des cas (changement de statut rare).
• Invalidation. Au moindre rejet RTIR pour REF-TAXPAYER_NOT_FOUND ou statut SUSPENDED, invalider l'entrée cache et requeryer.
• Pre-flight check. À la saisie d'un nouveau partenaire dans l'ERP, valider en temps réel. À la modification d'une fiche partenaire, revalider.
• Batch validation. Pas de mode batch officiel pour queryTaxpayer. Pour valider 10 000 partenaires, séquentialiser les appels et respecter le rate limit (~100 req/s).
• Cross-référence VIES. Pour les opérations intra-UE, queryTaxpayer ne remplace pas la validation VIES (qui teste le préfixe HU + base number en mode européen). Faire les deux pour les flux cross-border.

Pièges courants

• Passer l'adószám complet à queryTaxpayer. NAV n'accepte que la racine 8 chiffres (tax base number), pas les vatCode/countyCode. Passer 12345678242 au lieu de 12345678 déclenche un format error.
• Ne pas distinguer SUSPENDED de DELETED. Un partenaire SUSPENDED peut redevenir actif après régularisation auprès de NAV. Un DELETED est définitif. Politiques commerciales différentes.
• Croire au cache infini. Une fois /an, un acteur majeur passe en redressement et son statut bascule SUSPENDED pendant 30 jours. Un cache non invalidé propage l'erreur pendant tout ce délai.
• Confondre adószám et adóazonosító jel. L'adóazonosító est le numéro d'identification personnelle (10 chiffres) d'un particulier, sans préfixe pays. Pas validable via queryTaxpayer (B2C n'a pas besoin de validation NAV).
• Mauvaise gestion du groupe TVA. Une facture adressée à un membre de groupe doit porter le tax number du groupe (vatCode=3), pas celui du membre (vatCode=5). Confusion fréquente lors d'imports BeNeLux opérant des filiales hongroises en groupe.

Liens transverses

• Hub Hongrie — RTIR complet
• NAV Online Számla — plateforme
• API NAV — spécifications
• Régimes TVA hongrois
• RTIR — architecture
• NAV — vérification adoszám (UI web)
• VIES — validation TVA UE
• Documentation NAV — API