frontend 2026-06-10 bontva a 2 felület
This commit is contained in:
Roo
235
docs/nav_api_v3_fix_summary.md
Normal file
235
docs/nav_api_v3_fix_summary.md
Normal file
@@ -0,0 +1,235 @@
|
||||
# 🔧 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.
|
||||
Reference in New Issue
Block a user