69 lines
4.4 KiB
Markdown
69 lines
4.4 KiB
Markdown
# 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.
|