236 lines
6.9 KiB
Markdown
236 lines
6.9 KiB
Markdown
# 🔧 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.
|