# 🔧 NAV Online Számla API v3 - Hibajavítási Összefoglaló

**Dátum:** 2026-06-07
**Forrás:** `Online_Szamla_interfesz specifikacio_HU_v3.0. (2026.02.12).pdf`
**Érintett fájlok:**
- `.env` (NAV konfigurációs értékek)
- `backend/app/services/nav_service.py` (NAV API integráció)
- `backend/app/api/v1/endpoints/organizations.py` (lookup-tax végpont)
- `backend/app/core/config.py` (Pydantic Settings)

---

## 1. A NAV API v3 Működési Modellje

A NAV Online Számla API v3.0 **nem REST/JSON**, hanem **SOAP-alapú XML** kommunikációt használ, amit modern HTTP(S) kérésekbe csomagoltak.

### 1.1. Kommunikációs Rétegek

```
FastAPI endpoint (organizations.py)
    |
    v
NavService (nav_service.py)
    |  XML body osszeallitas
    |  Kriptografiai alairasok szamitasa
    |  HTTP fejlecek beallitasa
    v
httpx.AsyncClient POST
    |
    v
NAV API szerver (api-test.onlineszamla.nav.gov.hu)
    |
    v
XML valasz feldolgozasa (ElementTree)
```

### 1.2. Vegpont

```
POST https://api-test.onlineszamla.nav.gov.hu/invoiceService/v3/queryTaxpayer
```

---

## 2. Kriptografiai Reszletek (A Legkritikusabb Resz)

### 2.1. passwordHash (SHA-512)

A jelszo **nyers UTF-8** stringkent kerul a hash-be. Nincs semmilyen elofeldolgozas (salt, peppering).

### 2.2. requestSignature (SHA3-512) - KET KULONBOZO HELYEN

| Hely | Algoritmus | Input | Kulcs |
|------|-----------|-------|-------|
| **HTTP Header** `RequestSignature` | SHA3-512 | requestId + timestamp + NAV_API_EXCHANGE_KEY | Exchange Key |
| **XML body** `<user><requestSignature>` | SHA3-512 | requestId + timestamp + NAV_API_SIGN_KEY | Sign Key |

### 2.3. HTTP Fejlecek

- `Content-Type`: application/xml; charset=UTF-8
- `Accept`: application/xml
- `User`: NAV_API_USER
- `PasswordHash`: SHA-512(password) hex, UPPERCASE
- `ExchangeKey`: NAV_API_EXCHANGE_KEY
- `RequestId`: UUID (max 30 karakter, kotojelek nelkul)
- `Timestamp`: YYYY-MM-DDTHH:MM:SS.000Z
- `RequestSignature`: SHA3-512(requestId + timestamp + exchangeKey)

### 2.4. XML Body Szerkezet

```xml
<?xml version="1.0" encoding="UTF-8"?>
<QueryTaxpayerRequest xmlns="http://schemas.nav.gov.hu/OSA/3.0/api">
    <header xmlns="http://schemas.nav.gov.hu/NTCA/1.0/common">
        <requestId>{uuid_30_char}</requestId>
        <timestamp>{UTC_ISO}</timestamp>
        <requestVersion>3.0</requestVersion>
        <headerVersion>1.0</headerVersion>
    </header>
    <user xmlns="http://schemas.nav.gov.hu/NTCA/1.0/common">
        <login>{NAV_API_USER}</login>
        <passwordHash cryptoType="SHA-512">{SHA512(password)}</passwordHash>
        <taxNumber>{hivo_fel_adoszama_8_jegy}</taxNumber>
        <requestSignature cryptoType="SHA3-512">{SHA3(requestId+timestamp+signKey)}</requestSignature>
    </user>
    <software>
        <softwareId>SF-NAV-API-001-000</softwareId>
        <softwareName>ServiceFinder</softwareName>
        <softwareOperation>LOCAL_SOFTWARE</softwareOperation>
        <softwareMainVersion>1.0</softwareMainVersion>
        <softwareDevName>ServiceFinder Kft</softwareDevName>
        <softwareDevContact>dev@sftest.hu</softwareDevContact>
        <softwareDevCountryCode>HU</softwareDevCountryCode>
        <softwareDevTaxNumber>12345678</softwareDevTaxNumber>
    </software>
    <taxNumber>{lekerdezendo_ceg_adoszama_8_jegy}</taxNumber>
</QueryTaxpayerRequest>
```

---

## 3. AZONOSITOTT HIBAK

### HIBA #1 (KRITIKUS): .env fajlban idezojelek a NAV ertekek korul

**Hely:** `.env` sorok 90-94

A `.env` fajlban a NAV ertekek korul idezojelek (aposztróf, dupla idezojel) vannak, amiket a Pydantic Settings literalisan olvas be.

```env
NAV_API_PASSWORD='Tevelegelek&99'          <- aposztrofokkal egyutt! (12 helyett 14 kar.)
NAV_API_SIGN_KEY=02-b52b-3d9e7d638c695EPWNIUAEGHS  <- OK
NAV_API_EXCHANGE_KEY=a5cf5EPWNIU9DP8O              <- OK
NAV_API_CALLER_TAX_NUMBER="48952046133"  <- idezojellel egyutt! (11 helyett 12 kar.)
```

**Kovetkezmenyek:**
1. `passwordHash = SHA-512("'Tevelegelek&99'")` -> **ROSSZ hash** (aposztrofokkal)
2. `caller_tax_number[:8] = '"4895204'` -> **ROSSZ adoszam** (az elso 8 karakterbe beleesik a ")

**Bizonyitas:**
```
SHA-512('Tevelegelek&99')    -> 452506A930168C81DB06...
SHA-512(Tevelegelek&99)      -> CC854A1E4F49B484396A...
                              ^ NEM egyezik!
```

### HIBA #2 (MODSZERTANI): Nincs beepitett quote stripping a config-ban

**Hely:** `backend/app/core/config.py` (NAV_API_* mezo definiciok)

A Pydantic Settings nem strippeli automatikusan az idezojeleket.

### NEM HIBA: A kod logikaja helyes

A `nav_service.py` kod szerkezetileg megfelel a NAV API v3 specifikacionak:
- SHA-512 a passwordHash-hoz
- SHA3-512 a requestSignature-hoz
- Ket kulonbozo kulcs: exchangeKey (HTTP) vs signKey (XML)
- UUID max 30 karakter, timestamp UTC formaban
- Helyes XML namespace-ek (OSA/3.0/api es NTCA/1.0/common)
- Helyes HTTP hibakezeles (503 ha NAV nem elerheto, 404 ha nincs talalat)

---

## 4. JAVITASI TERV

### 4.1. .env fajl javitasa

Valtoztasd meg a kovetkezo sorokat:

```
# REGI (hibas):
NAV_API_PASSWORD='Tevelegelek&99'
NAV_API_CALLER_TAX_NUMBER="48952046133"

# UJ (helyes):
NAV_API_PASSWORD=Tevelegelek&99
NAV_API_CALLER_TAX_NUMBER=48952046133
```

### 4.2. Config quote stripping (vedohalo)

Add hozza a kovetkezo validatort `backend/app/core/config.py`-hoz a Settings osztalyba a NAV_API_* mezok utan:

```python
from pydantic import field_validator

# Add this validator for all NAV fields:
@field_validator('NAV_API_PASSWORD', 'NAV_API_SIGN_KEY', 'NAV_API_EXCHANGE_KEY', 'NAV_API_CALLER_TAX_NUMBER')
@classmethod
def strip_quotes(cls, v: str) -> str:
    if v:
        v = v.strip()
        if len(v) >= 2 and v[0] == v[-1] and v[0] in ('"', "'"):
            v = v[1:-1]
    return v
```

### 4.3. Service biztonsagi javitas

`nav_service.py`-ban a `_build_query_taxpayer_xml()` modositas:

```python
target_tax_number_core = (
    tax_number
    .strip()
    .replace("-", "")
    .replace(" ", "")[:8]
)
```

### 4.4. Teszteles

A javitas utan:

```bash
# 1. Kontener ujrainditas
docker compose restart sf_api

# 2. Teszt lekerdezes
docker exec sf_api python3 -c "
from app.services.nav_service import NavService
import asyncio
result = asyncio.run(NavService.query_taxpayer('24742063'))
print(result)
"
```

Sikeres valasz formatuma:
```json
{
  "full_name": "CEG NEVE KFT.",
  "name": "CEG NEVE KFT.",
  "display_name": "CEG NEVE KFT.",
  "address_zip": "1234",
  "address_city": "BUDAPEST",
  "address_street_name": "Fo utca",
  "address_street_type": "utca",
  "address_house_number": "1"
}
```

---

## 5. Alternativak (Ha a NAV API tovabbra sem mukodik)

| Megoldas | Tipus | Elony | Hatrany |
|----------|-------|-------|---------|
| VIES (EU VAT) | SOAP/XML | Ingyenes, EU-s hivatalos | Csak EU-s adoszamok |
| OpenCorporates | REST/JSON | Konnyu integracio | Ingyenes verzio limitalt |
| Opten / Bisnode | Fizetos API | Teljes magyar cegadatok | Fizetos |
| ceginfo.hu | REST API | Magyar fokusz | Fizetos |

Ha tovabbra is `INVALID_REQUEST_SIGNATURE`, akkor a NAV portalon (https://onlineszamla.nav.gov.hu/) uj signKey/exchangeKey part kell igenyelni.