kincses/service-finder

Fork 0

Files

Roo 90e3173fbc frontend 2026-06-10 bontva a 2 felület

2026-06-10 08:06:07 +00:00

6.9 KiB

Raw Blame History

🔧 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 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.

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:

passwordHash = SHA-512("'Tevelegelek&99'") -> ROSSZ hash (aposztrofokkal)
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:

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:

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

4.4. Teszteles

A javitas utan:

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

{
  "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.

6.9 KiB Raw Blame History