AyCode.Core/AyCode.Services/Nav

Nav — NAV adatszolgáltatás (általános base réteg)

Általános, API-független infrastruktúra a magyar NAV felé történő XML-adatszolgáltatáshoz (EKÁER, Online Számla, jövőbeli NAV-jelentések). A konkrét API-k (pl. EKÁER) ebből származnak — itt nincs API-specifikus típus.

Tervezési háttér és a réteg-felosztás indoklása: a NAV-rendszerek REST-szerű HTTP POST + XML body-t használnak (nem SOAP), közös SHA-512 aláírás-auth-hal. A típusok API-nként külön XML namespace-ben generálódnak (EKÁER EKAER/1.0, Online Számla NTCA/2.0/common), ezért a közös rész viselkedés + interfész, nem közös típus.

Fájlok

Fájl	Szerep
NavInterfaces.cs	Közös szerződések: INavCredentials, INavRequestHeader, INavUserHeader, INavRequest, INavResult, INavResponse. A generált API-modellek partial class-szal implementálják őket.
NavAuthHelper.cs	SHA-512 hash-ek: passwordHash és requestSignature (nagybetűs hex).
NavXmlHelper.cs	UTF-8 XML (de)szerializáció (Utf8StringWriter-rel, hogy az XML-deklaráció utf-8 legyen).
NavReportException.cs	NAV hiba (HTTP-szintű vagy funcCode != OK).
NavReportServiceBase.cs	Abstract base: a teljes send-flow (auth → szerializál → POST → deszerializál → sikeresség-ellenőrzés).

Egy konkrét NAV API bekötése (2. réteg)

// 1) A generált request/response/header típusokra ráhúzzuk az interfészeket (partial, nem invazív):
public partial class BasicHeaderType : INavRequestHeader { }          // RequestId, Timestamp már megvannak
public partial class UserHeaderType : INavUserHeader
{
    string INavUserHeader.TaxNumber { get => VatNumber; set => VatNumber = value; } // EKÁER: VATNumber → TaxNumber
}
public partial class BasicRequestType : INavRequest
{
    INavRequestHeader INavRequest.RequestHeader => Header;
    INavUserHeader INavRequest.UserHeader => User;
}

// 2) A konkrét service a base-ből származik:
public class EkaerReportService
    : NavReportServiceBase<ManageTradeCardsRequest, ManageTradeCardsResponse>
{
    public EkaerReportService(HttpClient http, INavCredentials creds) : base(http, creds) { }
    protected override string OperationPath => "TradeCardManagementService/customer/manageTradeCards";
}

Platform-függetlenség

A HttpClient-et a hívó injektálja — a réteg nem köthető szerverhez (egy jövőbeli standalone MAUI app közvetlenül hívhatja). Böngésző-WASM-ből CORS miatt nincs közvetlen NAV-hívás; ott SignalR-en át a szerver proxyzik.

Nyitott pont

• Az aláírás-timestamp időzónája (CET vs UTC) a docs/eKAERManagementService_2.2.pdf-ből pontosítandó (NavReportServiceBase.ApplyAuthentication, TODO). A header- és a signature-timestamp ugyanaz az időpont.

Referenciák (NAV dokumentáció)

A NAV hivatalos forrásai + LLM-barát kivonatok a docs/ mappában — teljes index: docs/README.md.

Kezdd a kivonatokkal (token-takarékos, a 2.2 MB PDF helyett):

• docs/EKAER_INTERFACE.md — transport, endpoint, auth-algoritmus (teszt-vektorral)
• docs/EKAER_TRADECARD.md — a bejelentés payload-ja (a Shipping → TradeCard mappinghez)
• docs/EKAER_OPERATIONS.md — műveletek + státusz-életciklus
• docs/EKAER_VALIDATION.md — szabályok + hibakódok

Hiteles forrás: docs/eKAERManagementService_2.2.pdf + docs/ekaermanagement.xsd / docs/common.xsd. Online: https://ekaer.nav.gov.hu/faq/?page_id=9

Modell-újragenerálás (ha a séma frissül) — a common és ekaermanagement XSD-namespace-t külön C# namespace-be kell tenni, különben a TradeCardType (common: enum S/N ↔ ekaermanagement: class) ütközik:

xscgen --nullable --separateFiles --output <out> \
  --namespace "http://schemas.nav.gov.hu/EKAER/1.0/ekaermanagement=AyCode.Services.Nav.Ekaer.Models" \
  --namespace "http://schemas.nav.gov.hu/EKAER/1.0/common=AyCode.Services.Nav.Ekaer.Models.Common" \
  docs/ekaermanagement.xsd

Az xscgen az enum-tagokat PascalCase-eli (OK → Ok); az XML-érték az [XmlEnum]-ban marad.