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

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

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.

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:

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

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.

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

requestId értéke (esetünkben "019ce6a6-2a0c-7207-b3f4-cc8373579c7c")
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(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

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.

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.

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.

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

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.

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.

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:

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

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. 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.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.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.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();