# 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)

```csharp
// 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`](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/`](docs/) mappában — teljes index: **[`docs/README.md`](docs/README.md)**.

**Kezdd a kivonatokkal** (token-takarékos, a 2.2 MB PDF helyett):
- [`docs/EKAER_INTERFACE.md`](docs/EKAER_INTERFACE.md) — transport, endpoint, **auth-algoritmus** (teszt-vektorral)
- [`docs/EKAER_TRADECARD.md`](docs/EKAER_TRADECARD.md) — a bejelentés **payload**-ja (a `Shipping → TradeCard` mappinghez)
- [`docs/EKAER_OPERATIONS.md`](docs/EKAER_OPERATIONS.md) — műveletek + státusz-életciklus
- [`docs/EKAER_VALIDATION.md`](docs/EKAER_VALIDATION.md) — szabályok + hibakódok

**Hiteles forrás:** [`docs/eKAERManagementService_2.2.pdf`](docs/eKAERManagementService_2.2.pdf) + [`docs/ekaermanagement.xsd`](docs/ekaermanagement.xsd) / [`docs/common.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.