NAV DCC API

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. DAC8 - Kriptoeszköz Adatszolgáltatási Keretrendszer (CARF)

A DAC8 a 2011/16/EU irányelv (DAC) szerinti adóügyi adatcsere egyik szolgáltatása, amely a kriptoeszköz-szolgáltatók (RCASP) által végzett kriptoeszköz tranzakciók jelentésére vonatkozó XML sémákat tartalmazza. A DCC-API DAC8 moduljai a Crypto-Asset Reporting Framework (CARF) XML séma implementációját tartalmazzák, amelyet az OECD publikált:

OECD (2024), Kriptoeszköz-jelentési keretrendszer (Crypto-Asset Reporting Framework) XML séma: Felhasználói útmutató adóhatóságok számára, OECD Kiadó, Párizs, https://doi.org/10.1787/578052ec-en.

Validációs dokumentáció [EN]

1.2. 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:

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.
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.
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.

Validációs dokumentáció [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.

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:

Séma réteg (schema) - XSD sémadefiníciók
DTO réteg (dto) - Jakarta EE Data Transfer Object-ek, az XSD sémákból generálva
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-oecd-carf/      # OECD CARF harmadik féltől származó sémák
│   ├── schema-dac8/           # DAC8 CARF envelope API séma
│   ├── schema-oecd-globe/     # OECD GLOBE Pillar Two harmadik féltől származó sémák
│   └── schema-dac9/           # DAC9 Global Tax API séma
├── dto/
│   ├── dto-auth/
│   │   └── dto-auth-jakarta/  # Generált Jakarta EE DTO-k schema-auth sémából
│   ├── dto-oecd-carf/
│   │   └── dto-oecd-carf-jakarta/  # Generált Jakarta EE DTO-k OECD CARF sémából
│   ├── dto-dac8/
│   │   └── dto-dac8-jakarta/  # Generált Jakarta EE DTO-k schema-dac8 sémából
│   ├── dto-oecd-globe/
│   │   └── dto-oecd-globe-jakarta/  # Generált Jakarta EE DTO-k OECD GLOBE sémából
│   └── dto-dac9/
│       └── dto-dac9-jakarta/  # Generált Jakarta EE DTO-k schema-dac9 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-oecd-carf

Az OECD Crypto-Asset Reporting Framework (CARF) XML sémáit tartalmazza. Ezek harmadik féltől származó, az OECD által publikált XSD definíciók, amelyek a DAC8 CARF jelentés tartalmi validációjának alapjául szolgálnak.

schema-dac8

A DAC-8 szolgáltatások API XSD sémáját tartalmazza (a CarfRequest / CarfResponse envelope).

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.

schema-dac9

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

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-oecd-carf-jakarta

Jakarta EE DTO osztályok, amelyek az schema-oecd-carf OECD CARF 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-carf - OECD CARF séma definíciók

dto-dac8-jakarta

Jakarta EE DTO osztályok, amelyek az schema-dac8 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-dac8 - DAC8 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

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

4.3. 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

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/dac8/*`	DCC M2M DAC8 sémák
`http://schemas.nav.gov.hu/DCC/1.0/m2m/dac9/*`	DCC M2M DAC9 sémák
`urn:oecd:ties:carf:v1`	OECD CARF (Crypto-Asset Reporting Framework) fő séma
`urn:oecd:ties:isocarftypes:v1`	OECD CARF ISO ország-, pénznem- és nyelvkód típusok
`urn:oecd:ties:carfstf:v5`	OECD CARF újrafelhasználható típusok
`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

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/dac8/*

DCC M2M DAC8 sémák

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

DCC M2M DAC9 sémák

urn:oecd:ties:carf:v1

OECD CARF (Crypto-Asset Reporting Framework) fő séma

urn:oecd:ties:isocarftypes:v1

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

urn:oecd:ties:carfstf:v5

OECD CARF újrafelhasználható típusok

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

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.2` (NTCA Common)

Java

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.2 (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:

Autentikáció - Token igénylés az M2M kommunikációhoz
DAC8 jelentés beküldés - Crypto-Asset Reporting Framework (CARF) jelentés kezelése
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

5.2. Autentikáció

5.2.1. 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.

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:

Base URL:
- Éles: https://api-dacentral.nav.gov.hu
- Teszt: https://api-dacentral-test.nav.gov.hu
Path: /dcc/m2m/v1/token
HTTP metódus: POST
Fejlécek:
- Content-Type: text/xml vagy application/xml
- Accept: text/xml vagy application/xml

Kérés: M2MTokenRequest

A kérés az NTCA LegacyAuthRequestType 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>1779109982563</requestId>
        <timestamp>2026-03-13T10:02:55.372Z</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">BD9CD4BB9CCCFB04AE24A206DAE13CDE067980074226E1B13CD56F46D678867AB01A79DE05F41197952384D1C1805C0BBC2ACA45A65070B8376B16972DB1EE57</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ása

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:

requestId értéke (esetünkben "1779109982563")
a timestamp tag értéke "yyyyMMddHHmmss" maszkkal, UTC időben (esetünkben "20260313100255")
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(1779109982563 + 20260313100255 + ce-8f5e-215119fa7dd621DLMRHRLH2S).UPPERCASE()

requestSignature = SHA3-512(177910998256320260313100255ce-8f5e-215119fa7dd621DLMRHRLH2S).UPPERCASE()

requestSignature = bd9cd4bb9cccfb04ae24a206dae13cde067980074226e1b13cd56f46d678867ab01a79de05f41197952384d1c1805c0bbc2aca45a65070b8376b16972db1ee57.UPPERCASE()

requestSignature = BD9CD4BB9CCCFB04AE24A206DAE13CDE067980074226E1B13CD56F46D678867AB01A79DE05F41197952384D1C1805C0BBC2ACA45A65070B8376B16972DB1EE57

Java minta

import java.time.OffsetDateTime;
import java.time.format.DateTimeFormatter;

import org.apache.commons.lang3.StringUtils;
import org.bouncycastle.jcajce.provider.digest.SHA3;
import org.bouncycastle.util.encoders.Hex;

public final class UamSignGeneratorExample {

    public static String uamAlgorithm(String requestId, OffsetDateTime timestamp, String xmlSignKey) {

        DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyyMMddHHmmss");
        String timestampString = formatter.format(timestamp);

        String concatenated = StringUtils.join(requestId, timestampString, xmlSignKey);

        SHA3.DigestSHA3 md = new SHA3.DigestSHA3(512);
        md.update(concatenated.getBytes());
        byte[] digest = md.digest();
        String hexDigest = Hex.toHexString(digest);

        return StringUtils.upperCase(hexDigest);
    }
}

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.2.2. Token kérés hibakódok

DCC API M2M autentikáció kommunikáció során előforduló hibakódok listája.

Table 2. Az M2M token kérés során előforduló hibakódok listája.
Hiba kód	Leírás	Mi a teendő?
`SSO_AUTH_FAILED`	Érvénytelen SSO bejelentkezési adatok vagy hiányzó jogosultság!	A M2M token kérés során a beküldött SSO bejelentkezési adatok érvénytelenek, vagy a felhasználónak nincs megfelelő jogosultsága. Ellenőrizze a beküldött SSO bejelentkezési adatokat és a jogosultságokat.
`SSO_INVALID_SIGNATURE`	Az SSO aláírás érvénytelen!	Ellenőrizze az SSO 'requestSignature' számítását.
`SSO_INVALID_TIMESTAMP`	A kapott kérés időbélyege érvénytelen!	Ellenőrizze a beküldött SSO 'M2MTokenRequest/context/timestamp' értékét, nem lehet túl régi vagy jövőbeli időbélyeg.
`DCC_AUTH_FAILED`	Érvénytelen bejelentkezési adatok vagy hiányzó jogosultság!	Ellenőrizze, hogy a M2M felhasználónak megvan a DCC rendszerbeli jogosultsága (Nem az SSO jogosultság, azon sikeres volt már a login).
`SSO_REQUEST_ID_NOT_UNIQUE`	A megadott kérés azonosítója már létezik!	Ellenőrizze a beküldött 'GlobalTaxRequestType/context/requestId' értékét.
`SSO_ERROR`	SSO hiba!	Próbálja újra, vagy vegye fel a kapcsolatot az ügyfélszolgálattal.

5.3. DAC8

5.3.1. DAC8 CarfRequest jelentés beküldés

A hozzáférési token birtokában a DAC-8 CARF (Crypto-Asset Reporting Framework) jelentés küldhető be.

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:

Base URL:
- Éles: https://api-dacentral.nav.gov.hu
- Teszt: https://api-dacentral-test.nav.gov.hu
Path: /dcc/m2m/v1/dac8/carf/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 CarfRequest XML reprezentációja
  - Content-Type: application/xml
- report - A jelentés fájlja (Crypto-Asset Reporting Framework (CARF) 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.

Kérés: CarfRequest

<ns2:CarfRequest xmlns="http://schemas.nav.gov.hu/NTCA/2.0/common/service"
    xmlns:ns2="http://schemas.nav.gov.hu/DCC/1.0/m2m/dac8/carf/carfapi">
    <context>
        <requestId>01a05da9-d9a9-7c41-ad31-fcdd4fc3066f</requestId>
        <timestamp>2026-09-01T15:50:07.531273284Z</timestamp>
    </context>
    <ns2:compressedContent>false</ns2:compressedContent>
    <ns2:reportType>CARF_OECD_V1_5</ns2:reportType>
    <ns2:reportChecksum cryptoType="CRC32">891091852</ns2:reportChecksum>
</ns2:CarfRequest>

Table 3. 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: `CARF_OECD_V1_5`	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

Válasz: CarfResponse

<?xml version="1.0" encoding="UTF-8"?>
<ns2:CarfResponse xmlns="http://schemas.nav.gov.hu/NTCA/2.0/common/service"
    xmlns:ns2="http://schemas.nav.gov.hu/DCC/1.0/m2m/dac8/carf/carfapi">
    <context>
        <requestId>01a05da9-d9a9-7c41-ad31-fcdd4fc3066f</requestId>
        <timestamp>2026-09-01T15:50:07.531273284Z</timestamp>
    </context>
    <resultCode>SUCCESS</resultCode>
    <ns2:carfReportId>01a05d95-016f-7747-9a01-2180d7307079</ns2:carfReportId>
</ns2:CarfResponse>

Table 4. Válasz mezők
Mező	Leírás
`carfReportId`	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.3.2. DAC8 Jelentés státusz lekérdezés

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

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:

Base URL:
- Éles: https://api-dacentral.nav.gov.hu
- Teszt: https://api-dacentral-test.nav.gov.hu
Path: /dcc/m2m/v1/dac8/carf/report/{carfReportId}/status
HTTP metódus: GET
Fejlécek:
- Authorization: Bearer {access_token}
- Accept: text/xml vagy application/xml

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/dac8/carf/carfapi">
    <context>
        <requestId>01a05da9-d9a9-7c41-ad31-fcdd4fc3066f</requestId>
        <timestamp>2026-09-01T15:50:07.531273284Z</timestamp>
    </context>
    <resultCode>SUCCESS</resultCode>
    <ns2:reportStatus>
        <ns2:status>VALID</ns2:status>
    </ns2:reportStatus>
</ns2:ReportStatusResponse>

Table 5. Lehetséges státuszok és teendők
Státusz	Teendő
`UPLOADED`	A jelentés feltöltésre került. Várjon, majd kérdezze le újra a státuszt.
`VALIDATING`	A jelentés ellenőrzés alatt áll. Várjon, majd kérdezze le újra a státuszt.
`VALID`	A jelentés érvényes, technikailag sikeresen feldolgozásra került.
`APPROVED`	A jelentést a felhasználó jóváhagyta. Nincs szükség további teendőre.
`DECLINED`	A jelentést a felhasználó elutasította. Nincs szükség további teendőre.
`INVALID`	A jelentés érvénytelen. Ellenőrizze az `errorCode` és `anomaly` mezőket a hiba okának azonosítá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/dac8/carf/carfapi">
    <context>
        <requestId>01a05da9-d9a9-7c41-ad31-fcdd4fc3066f</requestId>
        <timestamp>2026-09-01T15:50:07.531273284Z</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.3.3. DAC8 Hibakódok

A DCC API M2M kommunikáció során előforduló hibakódok listája.

Hibakód Leírás Teendő

Hibakód	Leírás	Teendő
`DUPLICATE_REQUEST_ID`	A megadott kérés azonosító már létezik a rendszerben!	Ellenőrizze a beküldött 'CarfRequestType/context/requestId' értéket.
`DUPLICATE_CHECKSUM`	A megadott ellenőrző összeg már létezik a rendszerben!	Ellenőrizze a beküldött 'CarfRequestType/reportChecksum' értéket.
`INVALID_VALUE`	A megadott érték érvénytelen!	Az egyik kötelező mező érvénytelen értéket tartalmaz. Ellenőrizze a beküldött 'CarfRequestType' objektumot.
`PACKAGED_CONTENT_TOO_LARGE`	A kérés kicsomagolt mérete meghaladta a megengedett korlátot!	A beküldött multipart GZIP (gz) tömörített objektum mérete kicsomagolva meghaladja a maximális méretet.
`INVALID_CHECKSUM`	A beküldött objektum ellenőrző összege nem egyezik!	Ellenőrizze, hogy a beküldött multipart objektum ellenőrző összege megegyezik-e a 'CarfRequestType/reportChecksum' értékkel. Győződjön meg róla, hogy a beküldött fájl nem sérült.
`INVALID_COMPRESSED_CONTENT`	A feltöltött fájl nem érvényes tömörített fájl!	Ellenőrizze, hogy a feltöltött fájl érvényes GZIP (gz) tömörített fájl-e.
`PAYLOAD_STORE_ERROR`	Hiba történt a tartalom tárolása során!	Próbálja meg később újra a feltöltést, vagy vegye fel a kapcsolatot az ügyfélszolgálattal!

DUPLICATE_REQUEST_ID

A megadott kérés azonosító már létezik a rendszerben!

Ellenőrizze a beküldött 'CarfRequestType/context/requestId' értéket.

DUPLICATE_CHECKSUM

A megadott ellenőrző összeg már létezik a rendszerben!

Ellenőrizze a beküldött 'CarfRequestType/reportChecksum' értéket.

INVALID_VALUE

A megadott érték érvénytelen!

Az egyik kötelező mező érvénytelen értéket tartalmaz. Ellenőrizze a beküldött 'CarfRequestType' objektumot.

PACKAGED_CONTENT_TOO_LARGE

A kérés kicsomagolt mérete meghaladta a megengedett korlátot!

A beküldött multipart GZIP (gz) tömörített objektum mérete kicsomagolva meghaladja a maximális méretet.

INVALID_CHECKSUM

A beküldött objektum ellenőrző összege nem egyezik!

Ellenőrizze, hogy a beküldött multipart objektum ellenőrző összege megegyezik-e a 'CarfRequestType/reportChecksum' értékkel. Győződjön meg róla, hogy a beküldött fájl nem sérült.

INVALID_COMPRESSED_CONTENT

A feltöltött fájl nem érvényes tömörített fájl!

Ellenőrizze, hogy a feltöltött fájl érvényes GZIP (gz) tömörített fájl-e.

PAYLOAD_STORE_ERROR

Hiba történt a tartalom tárolása során!

Próbálja meg később újra a feltöltést, vagy vegye fel a kapcsolatot az ügyfélszolgálattal!

5.4. DAC9

5.4.1. 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.

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:

Base URL:
- Éles: https://api-dacentral.nav.gov.hu
- Teszt: https://api-dacentral-test.nav.gov.hu
Path: /dcc/m2m/v1/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.

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 6. 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

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 7. 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.2. DAC9 Jelentés állapot lekérdezés

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

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:

Base URL:
- Éles: https://api-dacentral.nav.gov.hu
- Teszt: https://api-dacentral-test.nav.gov.hu
Path: /dcc/m2m/v1/dac9/globaltax/report/{globalTaxReportId}/status
HTTP metódus: GET
Fejlécek:
- Authorization: Bearer {access_token}
- Accept: text/xml vagy application/xml

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 8. 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.
`APPROVED`	A jelentés felhasználó által jóváhagyva. Nincs további teendő.
`DECLINED`	A jelentés felhasználó által elutasítva. 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.4.3. DAC9 Hiba kódok

DCC API M2M kommunikáció során előforduló hibakódok listája.

Table 9. Az M2M DAC9 globális minimumadó jelentés beküldése során előforduló hiba kódok listája.
Hiba kód	Leírás	Mi a teendő?
`DUPLICATE_REQUEST_ID`	A megadott kérés azonosítója már létezik a rendszerben!	Ellenőrizze a beküldött 'GlobalTaxRequestType/context/requestId' értékét.
`DUPLICATE_CHECKSUM`	A megadott checksum már létezik a rendszerben!	Ellenőrizze a beküldött 'GlobalTaxRequestType/reportChecksum' értékét.
`INVALID_VALUE`	A megadott érték érvénytelen!	Valamelyik előírt mező értéke érvénytelen. Ellenőrizze a beküldött 'GlobalTaxRequestType' objektumot.
`PACKAGED_CONTENT_TOO_LARGE`	A kicsomagolt kérés mérete meghaladta a befogadható értéket!	A beküldött multipart GZIP (gz) tömörített objektum mérete meghaladja a maximális méretet kicsomagolt formában.
`INVALID_CHECKSUM`	A küldött objektum ellenőrző értéke nem egyezik!	Ellenőrizze, hogy a beküldött multipart objektum ellenőrző értéke megegyezik-e a 'GlobalTaxRequestType/reportChecksum' értékével. Legyen biztos abban, hogy a beküldött fájl nem sérült.
`INVALID_COMPRESSED_CONTENT`	A feltöltött fájl nem érvényes tömörített fájl!	Ellenőrizze, hogy a feltöltött fájl érvényes GZIP (gz) tömörített fájl-e.
`PAYLOAD_STORE_ERROR`	Hiba a letárolás közben!	Próbálja újra a feltöltést később, vagy vegye fel a kapcsolatot az ügyfélszolgálattal.

5.5. OpenAPI

OpenAPI specifikáció letöltése (YAML)

5.6. Java kliens példa

A dto-auth-jakarta, dto-dac8-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.6.1. Maven függőségek

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>hu.gov.nav.dcc.api</groupId>
            <artifactId>bom-project</artifactId>
            <version>1.1.0-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-dac8-jakarta</artifactId>
    </dependency>
    <dependency>
        <groupId>hu.gov.nav.dcc.api</groupId>
        <artifactId>dto-dac9-jakarta</artifactId>
    </dependency>
</dependencies>

5.6.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.6.3. DAC8 jelentés beküldés

import hu.gov.nav.schemas.dcc._1_0.m2m.dac8.carf.carfapi.CarfRequest;
import hu.gov.nav.schemas.dcc._1_0.m2m.dac8.carf.carfapi.CarfResponseType;
import hu.gov.nav.schemas.dcc._1_0.m2m.dac8.carf.carfapi.ReportStatusResponseType;

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

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

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

5.6.4. 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

Modul	ArtifactId	Leírás
Auth DTO	`dto-auth-jakarta`	Jakarta EE DTO-k a Token API (pl. `tokenapi.xsd`) sémából
OECD CARF DTO	`dto-oecd-carf-jakarta`	Jakarta EE DTO-k az OECD Crypto-Asset Reporting Framework sémákból (pl. `CARFXML_v1.5.xsd`)
DAC8 DTO	`dto-dac8-jakarta`	Jakarta EE DTO-k a CARF API (pl. `carfapi.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`)
DAC9 DTO	`dto-dac9-jakarta`	Jakarta EE DTO-k a Global Tax API (pl. `globaltaxapi.xsd`) sémából

Auth DTO

dto-auth-jakarta

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

OECD CARF DTO

dto-oecd-carf-jakarta

Jakarta EE DTO-k az OECD Crypto-Asset Reporting Framework sémákból (pl. CARFXML_v1.5.xsd)

DAC8 DTO

dto-dac8-jakarta

Jakarta EE DTO-k a CARF API (pl. carfapi.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)

DAC9 DTO

dto-dac9-jakarta

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

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

A plugin beolvassa az all-in-one.xsd aggregátor sémát
Az OASIS XML Catalog (catalog.cat) feloldja a névtereket a megfelelő Maven artifact-okra
A JAXB kötési fájl (bindings.xjb) alkalmazásra kerül
A közös típusok Episode fájlból származnak (nem generálódnak újra)
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 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`

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.

NAV DCC API

1. Bevezetés

1.1. DAC8 - Kriptoeszköz Adatszolgáltatási Keretrendszer (CARF)

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

2. Dokumentáció áttekintése

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

4. Architektúra

4.1. Projekt struktúra

4.2. Modul hierarchia

4.2.1. Séma modulok

schema-auth

schema-oecd-carf

schema-dac8

schema-oecd-globe

schema-dac9

4.2.2. DTO modulok

dto-auth-jakarta

dto-oecd-carf-jakarta

dto-dac8-jakarta

dto-oecd-globe-jakarta

dto-dac9-jakarta

4.3. Függőségi diagram

4.4. Névtér stratégia

4.5. Technológiai stack

5. M2M integrációs útmutató

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

5.2. Autentikáció

5.2.1. Token igénylés

Http kérés

Kérés: M2MTokenRequest

requestSignature számítása

Válasz: M2MTokenResponse

5.2.2. Token kérés hibakódok

5.3. DAC8

5.3.1. DAC8 CarfRequest jelentés beküldés

Http kérés

Kérés: CarfRequest

Válasz: CarfResponse

5.3.2. DAC8 Jelentés státusz lekérdezés

Http kérés

Válasz: ReportStatusResponse

5.3.3. DAC8 Hibakódok

5.4. DAC9

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

Http kérés

Kérés: GlobalTaxRequest

Válasz: GlobalTaxResponse

5.4.2. DAC9 Jelentés állapot lekérdezés

Http kérés

Válasz: ReportStatusResponse

5.4.3. DAC9 Hiba kódok

5.5. OpenAPI

5.6. Java kliens példa

5.6.1. Maven függőségek

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

5.6.3. DAC8 jelentés beküldés

5.6.4. DAC9 jelentés beküldés

6. DTO generálás

6.1. DTO modulok

6.2. Generálási folyamat

6.2.1. Lépések

6.2.2. Generálási konfiguráció

6.3. XSD Catalog rendszer

6.3.1. Catalog bejegyzések (Minta)

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

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

6.4.1. generateIsSetMethod

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

6.5. Episode mechanizmus

6.6. JAXB plugin kiegészítők

6.6.1. Fluent API (-Xfluent-api)

6.6.2. Annotate (-Xannotate)

6.6.1. Fluent API (`-Xfluent-api`)

6.6.2. Annotate (`-Xannotate`)