English version

1. Bevezetés

A DCC API (Directive on Administrative Cooperation API) projekt a 2011/16/EU irányelv (DAC) szerinti adóügyi adatcsere M2M (Machine-to-Machine) interfészének nyilvános sémadefinícióit tartalmazza.

A projekt célja egy egységes, biztonságos és hatékony elektronikus adatcsere-keretrendszer biztosítása, amely összefogja és támogatja az EU DAC irányelv által előírt valamennyi adatcsere-folyamatot. A rendszer megteremti az interoperabilitás, az átláthatóság és az adatbiztonság egységes alapjait, elősegítve az adóügyi együttműködés magasabb szintjét az Európai Unióban.

1.1. DAC9 - GloBE Információs Adatszolgáltatás (Pillar Two)

A DAC9 a 2011/16/EU irányelv (DAC) szerinti adóügyi adatcsere egyik legfontosabb szolgáltatása, amely a globális minimumadó jelentésére vonatkozó XML sémákat tartalmazza. A DCC-API DAC9 moduljai a Magyarország által az OECD-vel együttműködésben implementált GloBE Information Return (Pillar Two) XML sémák implementációját tartalmazzák, amelyek a következő dokumentumokon alapulnak:

  1. OECD (2025), GloBE Információs Adatszolgáltatás (Pillar Two) XML séma: Felhasználói útmutató adóhatóságok számára, OECD Publishing, Párizs, https://doi.org/10.1787/c594935a-en.

  2. OECD (2025), Az adózás digitalizációjából eredő kihívások - Konszolidált kommentár a Globális Anti-Base Erosion Modell Szabályokhoz (2025): Befogadó Keret a BEPS-re, OECD/G20 Base Erosion and Profit Shifting Project, OECD Publishing, Párizs, https://doi.org/10.1787/a551b351-en.

  3. OECD (2025), Az adózás digitalizációjából eredő kihívások - GloBE Információs Adatszolgáltatás (2025. január): Befogadó Keret a BEPS-re, OECD/G20 Base Erosion and Profit Shifting Project, OECD Publishing, Párizs, https://doi.org/10.1787/a05ec99a-en.

2. Dokumentáció áttekintése

Az alábbi dokumentumok alkotják a DCC API fejlesztési dokumentációját:

Dokumentum Leírás

Architektúra

A projekt felépítése, modul struktúra, függőségi hierarchia és tervezési döntések.

M2M integrációs útmutató

Gépi interfész csatlakozási útmutató külső kliensek számára.

DTO generálás

Jakarta EE DTO objektumok generálásának módja, JAXB konfiguráció és Catalog rendszer.

3. Külső függőségek

A projekt a NAV közös sémaleíró projektjére épül:

  • Common (hu.gov.nav.schemas.common2) - Általános NTCA 2.0 XSD definíciók és Jakarta EE DTO-k. A DCC API sémái és típusai erre a projektre épülnek, felhasználva annak string, type, customer, paging, entity, service és authservice névtereit.

4. Architektúra

A DCC API egy többmodulos Maven projekt, amely a NAV DAC (Directive on Administrative Cooperation) M2M interfész sémadefinícióit tartalmazza. A projekt három fő réteget definiál:

  1. Séma réteg (schema) - XSD sémadefiníciók

  2. DTO réteg (dto) - Jakarta EE Data Transfer Object-ek, az XSD sémákból generálva

  3. BOM réteg (bom) - Bill of Materials a függőségek központi verziókezeléséhez

4.1. Projekt struktúra

DCC-API
├── bom/
│   ├── bom-all/               # Teljes BOM (projekt + külső függőségek)
│   └── bom-project/           # Csak projekt modulok BOM-ja
├── schema/
│   ├── schema-auth/           # M2M Token API séma
│   ├── schema-dac9/           # DAC9 Global Tax API séma
│   └── schema-oecd-globe/     # OECD GLOBE Pillar Two harmadik féltől származó sémák
├── dto/
│   ├── dto-auth/
│   │   └── dto-auth-jakarta/  # Generált Jakarta EE DTO-k schema-auth sémából
│   ├── dto-dac9/
│   │   └── dto-dac9-jakarta/  # Generált Jakarta EE DTO-k schema-dac9 sémából
│   └── dto-oecd-globe/
│       └── dto-oecd-globe-jakarta/  # Generált Jakarta EE DTO-k OECD GLOBE sémából
└── docs/                      # Dokumentáció

4.2. Modul hierarchia

4.2.1. Séma modulok

schema-auth

Az M2M autentikációs token API XSD sémáját tartalmazza.

schema-dac9

A DAC-9 szolgáltatások API XSD sémáját tartalmazza.

schema-oecd-globe

Az OECD GLOBE (Global Anti-Base Erosion) Pillar Two Information Return XML sémáit tartalmazza. Ezek harmadik féltől származó, az OECD által publikált XSD definíciók, amelyek a DAC9 globális minimumadó jelentés tartalmi validációjának alapjául szolgálnak.

4.2.2. DTO modulok

dto-auth-jakarta

Jakarta EE DTO osztályok, amelyek az schema-auth XSD sémáiból generálódnak JAXB segítségével.

  • Függőségek:

    • hu.gov.nav.schemas.common2:dto-jakarta - Közös NTCA 2.0 DTO-k

    • hu.gov.nav.dcc.api:schema-auth - Auth séma definíciók

dto-dac9-jakarta

Jakarta EE DTO osztályok, amelyek az schema-dac9 XSD sémáiból generálódnak JAXB segítségével.

  • Függőségek:

    • hu.gov.nav.schemas.common2:dto-jakarta - Közös NTCA 2.0 DTO-k

    • hu.gov.nav.dcc.api:schema-dac9 - DAC9 séma definíciók

dto-oecd-globe-jakarta

Jakarta EE DTO osztályok, amelyek az schema-oecd-globe OECD GLOBE XSD sémáiból generálódnak JAXB segítségével. Ez a modul önálló, nem használ Episode mechanizmust, mivel az OECD típusok teljesen függetlenek az NTCA Common típusoktól.

  • Függőségek:

    • hu.gov.nav.schemas.common2:core-jakarta - Közös NTCA 2.0 core modul

    • hu.gov.nav.dcc.api:schema-oecd-globe - OECD GLOBE séma definíciók

4.3. Függőségi diagram

DCC API modul függőségi diagram

4.4. Névtér stratégia

A projekt az alábbi névtér hierarchiát alkalmazza:

Névtér minta Leírás

http://schemas.nav.gov.hu/NTCA/2.0/common/*

NTCA 2.0 közös sémák (Common projekt)

http://schemas.nav.gov.hu/DCC/1.0/m2m/token/*

DCC M2M autentikációs sémák

http://schemas.nav.gov.hu/DCC/1.0/m2m/dac9/*

DCC M2M DAC9 sémák

urn:oecd:ties:globe:v2

OECD GLOBE Information Return fő séma

urn:oecd:ties:isoglobetypes:v1

OECD ISO ország-, pénznem- és nyelvkód típusok

urn:oecd:ties:globestf:v5

OECD újrafelhasználható típusok

A névterek a schemas.nav.gov.hu alatt szerveződnek, a DCC/1.0 verziónévvel, az m2m prefix pedig a gépi kommunikáció jellegét jelöli.

4.5. Technológiai stack

Technológia Verzió / Leírás

Java

17

Jakarta EE

JAXB 3.0 (Jakarta XML Binding)

Maven

Multi-module POM struktúra

JAXB plugin

org.jvnet.jaxb:jaxb-maven-plugin:4.0.9

JAXB kiegészítők

Fluent API (jaxb2-fluent-api:3.0), Annotate (jaxb-plugin-annotate:4.0.8)

XSD Catalog

OASIS XML Catalog alapú névtér feloldás

Közös sémák

hu.gov.nav.schemas.common2:2.0.0-rc.1 (NTCA Common)

5. M2M integrációs útmutató

Ez a fejezet az M2M (Machine-to-Machine) gépi interfész csatlakozásának útmutatóját tartalmazza külső kliensek számára. A DCC API következő M2M funkciókat biztosít:

  1. Autentikáció - Token igénylés az M2M kommunikációhoz

  2. DAC9 jelentés beküldés - Globális minimumadó jelentés kezelése

Általános Http kommunikációs szabályok:

  • TLS 1.3 vagy újabb verzió használata kötelező

  • Request/Response XML formátum, ha csak az adott végpont nem ír elő más formátumot.

  • Karakterkódolás UTF-8 minden esetben.

  • Befogadott request méret maximálisan 1 MB, ha csak az adott végpont nem ír elő más méretkorlátot.

  • Tömörítés GZIP formátumban. Ha valahol tömörített adatot kell küldeni, akkor tömörítéskor a leggyorsabb, legkevésbé tömörítő, 1-es compression ratio kerüljön alkalmazásra („gzip -1 [FILE]”).

  • A szerver jellemzően 300ms alatti válaszidőkkel szolgál ki.

  • A szinkronhívások blokkoló timeout értéke 5000 ms. Kérjük, hogy kliens oldalon a fenti értéket meghaladó válaszidőt kezeljék csak időtúllépésként! Az abszolút timeout értéke 60 sec. Ha egy adatszolgáltatásra nem érkezik válasz a 60 másodperces timeout miatt, még nem jelenti a beküldés sikertelenségét.

  • A szerver az időbeállításokat egy zárt, a külvilág számára nem hozzáférhető NTP szervertől kapja. Kliens oldalon a szerveridőhöz szinkronizálás nem követelmény, azonban opcionálisan a következő időszinkronizáció lehetséges: http://www.pool.ntp.org/zone/hu (a csatlakozáshoz NTP kliensre van szükség).

  • A kliensektől elvárt hogy számítsanak az API verzióváltására (előre bejelentett, tervezhető időkkel), és a kérés-válasz feldolgozásakor a verziószámot is vegyék figyelembe.

5.1. Integrációs folyamat áttekintése

M2M integrációs folyamat

5.2. Autentikáció - Token igénylés

Az M2M kommunikáció első lépése a hozzáférési token igénylése a Token API-n keresztül.

5.2.1. Http kérés

A hozzáférési token igénylése HTTP POST kéréssel történik, ahol a következő beállítások szükségesek:

5.2.2. Kérés: M2MTokenRequest

A kérés az NTCA AuthRequestType kiterjesztése, amely tartalmazza a standard hitelesítési fejlécet, felhasználói adatokat és szoftver azonosítót.

M2MTokenRequest XML példa
<?xml version="1.0" encoding="UTF-8"?>
<ns3:M2MTokenRequest xmlns="http://schemas.nav.gov.hu/NTCA/2.0/common/service" xmlns:ns2="http://schemas.nav.gov.hu/NTCA/2.0/common/authservice"
    xmlns:ns3="http://schemas.nav.gov.hu/DCC/1.0/m2m/token/tokenapi">
    <context>
        <requestId>019ce6a6-2a0c-7207-b3f4-cc8373579c7c</requestId>
        <timestamp>2026-03-13T10:02:55.37291704Z</timestamp>
    </context>
    <ns2:auth>
        <ns2:login>m2m_user_example</ns2:login> (1)
        <ns2:passwordHash cryptoType="SHA-512">12B03226A6D8BE9C6E8CD5E55DC6C7920CAAA39DF14AAB92D5E3EA9340D1C8A4D3D0B8E4314F1F6EF131BA4BF1CEB9186AB87C801AF0D5C95B1BEFB8CEDAE2B9</ns2:passwordHash> (2)
        <ns2:taxNumber>12345678</ns2:taxNumber> (3)
        <ns2:predecessorTaxNumber></ns2:predecessorTaxNumber> (4)
        <ns2:requestSignature cryptoType="SHA3-512">6498E406186580DA6403680FD3A6A008FD7F207CA2AFDE5885C38AC700A9A52A3BAADEE914FA0649DBBE103D2D6E99B1236DA403CDD5EF338245A4474770D591</ns2:requestSignature> (5)
    </ns2:auth>
    <ns2:requestVersion>1.0</ns2:requestVersion> (6)
    <ns2:headerVersion>1.0</ns2:headerVersion> (7)
</ns3:M2MTokenRequest>
1 A login tag a technikai felhasználó nevét tartalmazza. A login nevet a rendszer véletlenszerűen generálja a technikai felhasználó létrehozásakor 15 karakter hosszan. A login tag az authentikáció egyik eleme.
2 A passwordHash a login tagban szereplő technikai felhasználó jelszavának nagybetűs SHA-512 hash értéke. A literál jelszót a technikai felhasználót létrehozó elsődleges felhasználó adja meg az Online Számla webfelületen. A passwordHash az authentikáció egyik eleme. Egyetlen elfogadott értéke: SHA-512.
3 A taxNumber azon adózó adószámának első 8 száma, aki nevében a technikai felhasználó tevékenykedik, és akihez tartozik. Csak magyar adószám az elfogadott.
4 A predecessorTaxNumber amennyiben megadásra kerül, akkor validálásra kerül, hogy a taxNumber tagben megadott adózóval jogelőd viszonyban áll-e. A jogelőd viszony rekurzívan kerül ellenőrzésre, közvetett jogelőd megadása is elfogadott. A predecessorTaxNumber megadása befolyásolja az operációk üzleti logikáját.
5 A requestSignature a kliens által generált aláírása az üzenetnek. Minden kéréshez kötelezően tartoznia kell egy requestSignature-nek. A szerver a kérésben szereplő adatok alapján elvégzi a saját requestSignature számítását és csak akkor hajtja végre a kérést, ha a tárolt és kapott adatokból a helyes érték ténylegesen előállítható. A requestSignature számításáról a „requestSignature számítása” fejezet nyújt tájékoztatást. Egyetlen elfogadott értéke: SHA3-512.
6 A requestVersion a kérés verzióját jelöli, nem kötelező - ilyenkor a rendszer "1.0" értéket fog kezelni. Jelenleg csak a "1.0" érték fogadható el.
7 A headerVersion a fejléc verzióját jelöli, nem kötelező - ilyenkor a rendszer "1.0" értéket fog kezelni. Jelenleg csak a "1.0" érték fogadható el.
requestSignature számítására

A requestSignature az interfész-authentikáció egyik fő eleme. A szerepe, hogy illetéktelenek ne tudjanak a rendszerben változtatásokat végrehajtani. A hash értéket a szerver oldal minden operáció minden kérésénél ellenőrzi, és csak akkor hajtja végre a műveletet, ha a tárolt és kapott adatokból a helyes érték ténylegesen előállítható.

A requestSignature számítására a következő mezők értékeinek konkatenációjával történik, sorrendben:

  1. requestId értéke (esetünkben "019ce6a6-2a0c-7207-b3f4-cc8373579c7c")

  2. a timestamp tag értéke "yyyyMMddHHmmss" maszkkal, UTC időben (esetünkben "20260313100255")

  3. a technikai felhasználó aláírókulcsának literál értéke (technikai felhasználó létrehozásakor megadott érték). Példához ennek legyen az értéke "ce-8f5e-215119fa7dd621DLMRHRLH2S"

Az így és sorrendben konkatenált string SHA3-512 hash nagybetűsített eredménye lesz a requestSignature értéke.

algoritmus
requestSignature = SHA3-512(requestId + timestamp + signingKey).UPPERCASE()

requestSignature = SHA3-512(019ce6a6-2a0c-7207-b3f4-cc8373579c7c + 20260313100255 + ce-8f5e-215119fa7dd621DLMRHRLH2S).UPPERCASE()

requestSignature = SHA3-512(019ce6a6-2a0c-7207-b3f4-cc8373579c7c20260313100255ce-8f5e-215119fa7dd621DLMRHRLH2S).UPPERCASE()

requestSignature = 6498e406186580da6403680fd3a6a008fd7f207ca2afde5885c38ac700a9a52a3baadee914fa0649dbbe103d2d6e99b1236da403cdd5ef338245a4474770d591.UPPERCASE()

requestSignature = 6498E406186580DA6403680FD3A6A008FD7F207CA2AFDE5885C38AC700A9A52A3BAADEE914FA0649DBBE103D2D6E99B1236DA403CDD5EF338245A4474770D591

5.2.3. Válasz: M2MTokenResponse

Sikeres hitelesítés esetén a válasz tartalmazza a hozzáférési tokent és annak lejárati időpontját.

M2MTokenResponse XML példa
<?xml version="1.0" encoding="UTF-8"?>
<ns3:M2MTokenResponse xmlns="http://schemas.nav.gov.hu/NTCA/2.0/common/service" xmlns:ns2="http://schemas.nav.gov.hu/NTCA/2.0/common/authservice"
    xmlns:ns3="http://schemas.nav.gov.hu/DCC/1.0/m2m/token/tokenapi">
    <context>
        <requestId>019ce66a-c965-74cd-9795-1102575b62b7</requestId>
        <timestamp>2026-03-13T08:58:04.006840049Z</timestamp>
    </context>
    <resultCode>SUCCESS</resultCode>
    <ns3:accessToken>eyJhbGciOiJIUzI1NiIsInR5cC... JWT token</ns3:accessToken>
    <ns3:accessTokenExpiryAt>2026-03-13T13:59:07.478552281Z</ns3:accessTokenExpiryAt>
</ns3:M2MTokenResponse>
Table 1. Válasz mezők
Mező Leírás Típus

accessToken

A hozzáférési token értéke, amelyet a későbbi API hívásokhoz kell használni

GenericIdType

accessTokenExpiryAt

A token lejárati időpontja (UTC, nanomásodperc pontossággal)

GenericTimestampNanoType
A tokent a lejárati időpont előtt kell megújítani. A lejárt tokennel küldött kérések elutasításra kerülnek.

5.3. DAC9 GlobalTaxRequest jelentés beküldés

A hozzáférési token birtokában a DAC-9 globális minimumadó jelentés küldhető be.

5.3.1. Http kérés

A jelentés beküldése HTTP POST kéréssel történik, ahol a következő beállítások szükségesek:

  • URL: https://api-dacentral.nav.gov.hu/dcc/v1/m2m/dac9/globaltax/report

  • HTTP metódus: POST

  • Fejlécek:

    • Authorization: Bearer {access_token}

    • Content-Type: multipart/form-data

    • Accept: text/xml vagy application/xml

  • Törzs: Két részből álló multipart/form-data:

    • metadata - A GlobalTaxRequest XML reprezentációja

      • Content-Type: application/xml

    • report - A jelentés fájlja (GloBE Information Return (Pillar Two) XML Schema).

      • Content-Type: application/octet-stream

      • Ha a fájl nem tömörített, akkor plaintext XML-ben kell küldeni

      • Ha a fájl tömörített (gzip), akkor tömörítés nyers binary stream-ben kell küldeni.

      • A befogadható fájl maximális mérete: 100 MB (tömörített és nem tömörített formában). Ha a fájl tömörített, akkor a kitömörített tartalom mérete nem haladhatja meg a 250 MB-ot.

    • Minden esetben a karakter kódolás UTF-8

    • Beküldéskor a fájl tartalmának CRC32 ellenőrző összegét is meg kell adni a reportChecksum mezőben. Ha a fájl tömörített, akkor a kitömörített tartalom CRC32 értékét kell megadni.

5.3.2. Kérés: GlobalTaxRequest

<ns2:GlobalTaxRequest xmlns="http://schemas.nav.gov.hu/NTCA/2.0/common/service"
    xmlns:ns2="http://schemas.nav.gov.hu/DCC/1.0/m2m/dac9/globaltax/globaltaxapi">
    <context>
        <requestId>019ce6cd-394b-7622-9c01-6880b92f086d</requestId>
        <timestamp>2026-03-13T10:45:35.180339322Z</timestamp>
    </context>
    <ns2:compressedContent>false</ns2:compressedContent>
    <ns2:reportType>GLOBE_OECD_V1</ns2:reportType>
    <ns2:reportChecksum cryptoType="CRC32">639479525</ns2:reportChecksum>
</ns2:GlobalTaxRequest>
Table 2. Kérés mezők
Mező Leírás Kötelező

compressedContent

true ha a beküldött tartalom tömörített, false egyébként

Igen

reportType

A jelentés típusa. Jelenleg az egyetlen megengedett érték: GLOBE_OECD_V1

Igen

reportChecksum

A jelentés ellenőrző összege (CryptoType). Tömörített tartalom esetén a kitömörített tartalom ellenőrző összegét kell megadni.

Igen

5.3.3. Válasz: GlobalTaxResponse

<?xml version="1.0" encoding="UTF-8"?>
<ns2:GlobalTaxResponse xmlns="http://schemas.nav.gov.hu/NTCA/2.0/common/service"
    xmlns:ns2="http://schemas.nav.gov.hu/DCC/1.0/m2m/dac9/globaltax/globaltaxapi">
    <context>
        <requestId>019ce6cd-394b-7622-9c01-6880b92f086d</requestId>
        <timestamp>2026-03-13T10:45:35.180339322Z</timestamp>
    </context>
    <resultCode>SUCCESS</resultCode>
    <ns2:globalTaxReportId>019ce6cd-4540-78a7-ac4f-5049465a1fa0</ns2:globalTaxReportId>
</ns2:GlobalTaxResponse>
Table 3. Válasz mezők
Mező Leírás

globalTaxReportId

A beküldött jelentés egyedi tranzakció azonosítója. Ez az azonosító szükséges a jelentés állapotának lekérdezéséhez.

5.4. Jelentés állapot lekérdezés

A beküldött jelentés technikai feldolgozási állapota lekérdezhető a tranzakció azonosító alapján.

5.4.1. Http kérés

A jelentés állapotának lekérdezése HTTP GET kéréssel történik, ahol a következő beállítások szükségesek:

5.4.2. Válasz: ReportStatusResponse

<?xml version="1.0" encoding="UTF-8"?>
<ns2:ReportStatusResponse xmlns="http://schemas.nav.gov.hu/NTCA/2.0/common/service"
    xmlns:ns2="http://schemas.nav.gov.hu/DCC/1.0/m2m/dac9/globaltax/globaltaxapi">
    <context>
        <requestId>019cf6ac-b11c-74b6-8b8c-0832f6805328</requestId>
        <timestamp>2026-03-16T12:43:58.620345274Z</timestamp>
    </context>
    <resultCode>SUCCESS</resultCode>
    <ns2:reportStatus>
        <ns2:status>VALID</ns2:status>
    </ns2:reportStatus>
</ns2:ReportStatusResponse>
Table 4. Lehetséges státuszok és teendők
Státusz Teendő

UPLOADED

A jelentés feltöltve. Várjon, majd kérdezze le újra az állapotot.

VALIDATING

A jelentés ellenőrzés alatt. Várjon, majd kérdezze le újra az állapotot.

VALID

A jelentés érvényes, technikailag sikeresen feldolgozva. Nincs további teendő.

INVALID

A jelentés érvénytelen. Ellenőrizze az errorCode és anomaly mezőket a hiba okának feltárásához, majd javítsa és küldje be újra a jelentést.
Példa: Érvénytelen jelentés válasz
<?xml version="1.0" encoding="UTF-8"?>
<ns2:ReportStatusResponse xmlns="http://schemas.nav.gov.hu/NTCA/2.0/common/service"
    xmlns:ns2="http://schemas.nav.gov.hu/DCC/1.0/m2m/dac9/globaltax/globaltaxapi">
    <context>
        <requestId>019cf6ac-b11c-74b6-8b8c-0832f6805328</requestId>
        <timestamp>2026-03-16T12:43:58.620345274Z</timestamp>
    </context>
    <resultCode>SUCCESS</resultCode>
    <ns2:reportStatus>
        <ns2:status>INVALID</ns2:status>
        <ns2:errorCode>INVALID_FILE</ns2:errorCode>
        <ns2:anomaly>
            <field>exampleField</field>
            <error>Invalid value in column 12, line 34</error>
            <lineNumber>34</lineNumber>
            <columnNumber>12</columnNumber>
        </ns2:anomaly>
        <ns2:anomaly>
            <error>Another error without line and column information</error>
        </ns2:anomaly>
    </ns2:reportStatus>
</ns2:ReportStatusResponse>

5.5. Java kliens példa

A dto-auth-jakarta és dto-dac9-jakarta Maven modulok felhasználásával a kérés-válasz objektumok közvetlenül Java-ból is kezelhetők.

5.5.1. Maven függőségek

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>hu.gov.nav.dcc.api</groupId>
            <artifactId>bom-project</artifactId>
            <version>1.0.0-rc.2-SNAPSHOT</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>hu.gov.nav.dcc.api</groupId>
        <artifactId>dto-auth-jakarta</artifactId>
    </dependency>
    <dependency>
        <groupId>hu.gov.nav.dcc.api</groupId>
        <artifactId>dto-dac9-jakarta</artifactId>
    </dependency>
</dependencies>

5.5.2. Token kérés összeállítása

import hu.gov.nav.schemas.dcc._1_0.m2m.token.tokenapi.M2MTokenRequest;
import hu.gov.nav.schemas.dcc._1_0.m2m.token.tokenapi.M2MTokenResponseType;

// Token kérés létrehozása (fluent API)
M2MTokenRequest tokenRequest = new M2MTokenRequest();
// ... fejléc, felhasználó, szoftver adatok beállítása

// Válasz feldolgozása
M2MTokenResponseType response = // ... HTTP hívás eredménye
String accessToken = response.getAccessToken();
OffsetDateTime expiryAt = response.getAccessTokenExpiryAt();

5.5.3. DAC9 jelentés beküldés

import hu.gov.nav.schemas.dcc._1_0.m2m.dac9.globaltax.globaltaxapi.GlobalTaxRequest;
import hu.gov.nav.schemas.dcc._1_0.m2m.dac9.globaltax.globaltaxapi.GlobalTaxResponseType;
import hu.gov.nav.schemas.dcc._1_0.m2m.dac9.globaltax.globaltaxapi.ReportStatusResponseType;

// Jelentés regisztráció kérés
GlobalTaxRequest request = new GlobalTaxRequest();
request.setCompressedContent(true);
request.setReportType(ReportTypeType.GLOBE_OECD_V_1);
// ... checksum beállítása

// Válasz feldolgozása
GlobalTaxResponseType taxResponse = // ... HTTP hívás eredménye
String reportId = taxResponse.getGlobalTaxReportId();

// Státusz lekérdezés
ReportStatusResponseType statusResponse = // ... HTTP hívás eredménye
FileStatusType status = statusResponse.getReportStatus().getStatus();

6. DTO generálás

A DCC API projekt nem tartalmaz kézzel írt Java forráskódot. Az összes Java osztály (DTO – Data Transfer Object) az XSD sémákból generálódik build időben, a JAXB (Jakarta XML Binding) Maven plugin segítségével.

A generálás a következő technológiákat alkalmazza:

  • Jakarta EE JAXB 3.0 – XML-Java kötés

  • XSD Catalog – Névtér feloldás Maven artifact-okból

  • JAXB plugin kiegészítők – Fluent API és annotáció kezelés

  • Episode fájlok – Közös típusok duplikáció-mentes generálása

6.1. DTO modulok

Modul ArtifactId Leírás

Auth DTO

dto-auth-jakarta

Jakarta EE DTO-k a Token API (pl. tokenapi.xsd) sémából

DAC9 DTO

dto-dac9-jakarta

Jakarta EE DTO-k a Global Tax API (pl. globaltaxapi.xsd) sémából

OECD GLOBE DTO

dto-oecd-globe-jakarta

Jakarta EE DTO-k az OECD GLOBE Pillar Two sémákból (pl. GLOBEXML_v1.0.xsd)

6.2. Generálási folyamat

A generálás a org.jvnet.jaxb:jaxb-maven-plugin:4.0.9 plugin segítségével történik, a generate goal futtatásával a Maven build generate-sources fázisában.

6.2.1. Lépések

  1. A plugin beolvassa az all-in-one.xsd aggregátor sémát

  2. Az OASIS XML Catalog (catalog.cat) feloldja a névtereket a megfelelő Maven artifact-okra

  3. A JAXB kötési fájl (bindings.xjb) alkalmazásra kerül

  4. A közös típusok Episode fájlból származnak (nem generálódnak újra)

  5. A generált Java osztályok a target/generated-sources/src/main/java könyvtárba kerülnek

6.2.2. Generálási konfiguráció

<plugin>
    <groupId>org.jvnet.jaxb</groupId>
    <artifactId>jaxb-maven-plugin</artifactId>
    <version>4.0.9</version>
    <executions>
        <execution>
            <id>dcc-super</id>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <episodes>
                    <episode>
                        <groupId>hu.gov.nav.schemas.common2</groupId>
                        <artifactId>dto-jakarta</artifactId>
                    </episode>
                </episodes>
                <strict>false</strict>
                <catalog>src/main/resources/catalog/catalog.cat</catalog>
                <schemaIncludes>
                    <include>catalog/all-in-one.xsd</include>
                </schemaIncludes>
                <bindingIncludes>
                    <include>xjb/bindings.xjb</include>
                </bindingIncludes>
                <generateDirectory>
                    ${project.build.directory}/generated-sources/src/main/java
                </generateDirectory>
            </configuration>
        </execution>
    </executions>
    <configuration>
        <verbose>true</verbose>
        <schemaDirectory>src/main/resources</schemaDirectory>
        <args>
            <arguments>-Xfluent-api</arguments>
            <arguments>-Xannotate</arguments>
        </args>
        <plugins>
            <plugin>
                <groupId>org.jvnet.jaxb2_commons</groupId>
                <artifactId>jaxb2-fluent-api</artifactId>
                <version>3.0</version>
            </plugin>
            <plugin>
                <groupId>org.jvnet.jaxb</groupId>
                <artifactId>jaxb-plugin-annotate</artifactId>
                <version>4.0.8</version>
            </plugin>
        </plugins>
    </configuration>
</plugin>

6.3. XSD Catalog rendszer

Az XSD Catalog az OASIS XML Catalog szabvány szerint működik. A catalog.cat fájlok a névtereket Maven artifact-okra képezik le, lehetővé téve a sémák moduláris felhasználását.

6.3.1. Catalog bejegyzések (Minta)

<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">

    <!-- NTCA 2.0 közös sémák (Common projekt) -->
    <public publicId="http://schemas.nav.gov.hu/NTCA/2.0/common/string"
        uri="maven:hu.gov.nav.schemas.common2:schemas:jar::!/xsd/.../string.xsd" />
    <public publicId="http://schemas.nav.gov.hu/NTCA/2.0/common/type"
        uri="maven:hu.gov.nav.schemas.common2:schemas:jar::!/xsd/.../type.xsd" />
    <!-- ... további NTCA névterek ... -->

    <!-- DCC Auth séma -->
    <public publicId="http://schemas.nav.gov.hu/DCC/1.0/m2m/token/tokenapi"
        uri="maven:hu.gov.nav.dcc.api:schema-auth:jar::!/xsd/.../tokenapi.xsd" />

</catalog>

6.3.2. All-in-one aggregátor séma

Az all-in-one.xsd egy aggregátor séma, amely az összes szükséges névteret importálja egyetlen belépési pontként a JAXB generátor számára:

<xsd:schema
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    targetNamespace="http://catalog.schemas.nav.gov.hu/DCC/1.0/common/all-in-one">

    <!-- NTCA 2.0 közös névterek -->
    <xsd:import namespace="http://schemas.nav.gov.hu/NTCA/2.0/common/string" />
    <xsd:import namespace="http://schemas.nav.gov.hu/NTCA/2.0/common/type" />
    <xsd:import namespace="http://schemas.nav.gov.hu/NTCA/2.0/common/customer" />
    <xsd:import namespace="http://schemas.nav.gov.hu/NTCA/2.0/common/paging" />
    <xsd:import namespace="http://schemas.nav.gov.hu/NTCA/2.0/common/entity" />
    <xsd:import namespace="http://schemas.nav.gov.hu/NTCA/2.0/common/service" />
    <xsd:import namespace="http://schemas.nav.gov.hu/NTCA/2.0/common/authservice" />

    <!-- DCC modul-specifikus séma -->
    <xsd:import namespace="http://schemas.nav.gov.hu/DCC/1.0/m2m/token/tokenapi" />

</xsd:schema>

6.4. JAXB kötési konfiguráció

A bindings.xjb fájl az alábbi globális beállításokat tartalmazza:

6.4.1. generateIsSetMethod

<jaxb:globalBindings generateIsSetMethod="true">

Opcionális mezőkhöz isSet*() metódusok is generálódnak, amelyekkel ellenőrizhető, hogy az adott mező be volt-e állítva (null-tól eltérő értékkel).

6.4.2. Dátum/idő típus leképezések

XSD típus Java típus Adapter osztály

xsd:date

java.time.LocalDate

LocalDateXmlAdapter

xsd:time

java.time.OffsetTime

UtcOffsetTimeXmlAdapter

xsd:dateTime

java.time.OffsetDateTime

UtcOffsetDateTimeXmlAdapter

Az adapter osztályok a hu.gov.nav.schemas.common2.core.adapter csomagban találhatók (a Common projekt dto-jakarta moduljában).

6.5. Episode mechanizmus

Az Episode fájlok biztosítják, hogy ahol a típusok közös NTCA 2.0 típusokat használnak (pl. GenericIdType, BaseRequestType) ne generálódjanak újra minden DTO modulban. Ehelyett a hu.gov.nav.schemas.common2:dto-jakarta artifact Episode fájlját referálja a plugin, így csak a DCC-specifikus típusok kerülnek generálásra.

Például a dto-oecd-globe-jakarta modul nem használ Episode mechanizmust, mivel az OECD GLOBE típusok teljesen önállóak és függetlenek az NTCA Common típusoktól.

Episode konfiguráció
<episodes>
    <episode>
        <groupId>hu.gov.nav.schemas.common2</groupId>
        <artifactId>dto-jakarta</artifactId>
    </episode>
</episodes>

6.6. JAXB plugin kiegészítők

6.6.1. Fluent API (-Xfluent-api)

A jaxb2-fluent-api:3.0 kiegészítő fluent (láncolható) setter metódusokat generál:

// Standard JAXB
request.setCompressedContent(true);
request.setReportType(ReportTypeType.GLOBE_OECD_V_1);

// Fluent API
request.withCompressedContent(true)
       .withReportType(ReportTypeType.GLOBE_OECD_V_1);

6.6.2. Annotate (-Xannotate)

A jaxb-plugin-annotate:4.0.8 kiegészítő lehetővé teszi egyedi annotációk hozzáadását a generált osztályokhoz a kötési fájlon keresztül.