qtx-nav-evat

qtx-nav-evat is a focused Python client package for the NAV EVAT API, built on top of qtx-nav-core. qtx-nav-core provides the shared NAV transport, request envelope, authentication, XML and hashing utilities; this package adds EVAT-specific configuration, request bodies, response parsers, and a high-level client.

Version 0.5.0

This version includes the following API corrections:

• The misspelled update_enviroment method was corrected to update_environment.
• declaration_submission() returns no value (None) when the request succeeds. If NAV or the transport layer reports an error, the exception is propagated to the caller.

What It Contains

• EvatConfig and EvatEnvironment for selecting the NAV EVAT endpoint
• EvatClient for the supported EVAT operations
• DeclarationSchema, AttachmentStatus, and DeclarationProcessingStatusCode string enums
• typed request body classes for tax code, attachment, and declaration flows
• parsed response dataclasses for attachment, tax code, and declaration responses
• a local demo runner in main.py

Requirements

• Python 3.12 or newer
• qtx-nav-core>=0.2.3
• lxml>=5.2.0

Installation

Install from the project root in editable mode during development:

pip install -e .

Or install it as a normal dependency in another project:

pip install qtx-nav-evat

Quick Start

from qtx_nav_core import NavAuth, NavRequestContext, NavSoftwareInfo
from qtx_nav_evat import DeclarationSchema, EvatClient, EvatConfig, EvatEnvironment

config = EvatConfig(environment=EvatEnvironment.TEST)

context = NavRequestContext(
    auth=NavAuth(
        login="login",
        password="password",
        tax_number="12345678",
        sign_key="sign-key",
    ),
    software=NavSoftwareInfo(),
)

with EvatClient(config=config, context=context) as client:
    catalog = client.query_tax_code_catalog(taxpoint_date="2025-01-01")
    print(catalog.valid_from, catalog.valid_to)
    print(len(catalog.tax_codes))

    attachments = client.query_attachment_list()
    print(len(attachments))

    data = client.query_declaration_data(
        declaration_processing_id="processing-id",
        declaration_schema=DeclarationSchema.A60_DECLARATION,
    )

Supported Operations

Tax Code Catalog

• query_tax_code_catalog(taxpoint_date=None, request_body=None)

• endpoint path: /queryTaxCodeCatalog

• returns QueryTaxCodeCatalogResult

• query_invoice_tax_code(invoice_number="", invoice_direction=InvoiceDirection.INBOUND, request_body=None)

• endpoint path: /queryInvoiceTaxCode

• returns QueryInvoiceTaxCodeResponse

• query_customs_declaration_digest(page=1, declaration_direction=DeclarationDirection.IMPORTER, request_body=None)

• endpoint path: /queryCustomsDeclarationDigest

• returns QueryCustomsDeclarationDigestResponse

• query_customs_declaration_tax_code(cdps_id="", resolution_id="", declaration_direction=DeclarationDirection.IMPORTER, request_body=None)

• endpoint path: /queryCustomsDeclarationTaxCode

• returns QueryCustomsDeclarationTaxCodeResponse

Attachments

• query_attachment_list(request_body=None)

• endpoint path: /queryAttachmentList

• returns list[AttachmentListItem]

• upload_attachment(file_path, request_body=None)

• endpoint path: /manageAttachmentUpload

• returns AttachmentUploadResult

• computes the request metadata in EVAT code and delegates file upload transport to qtx-nav-core

• purge_attachment(claim_check_id, request_body=None)

• endpoint path: /purgeAttachment

• returns True if the request completed without an exception

Declarations

• query_declaration_list(taxpoint_date_from=None, taxpoint_date_to=None, request_body=None)

• endpoint path: /queryDeclarationList

• returns list[DeclarationListItem]

• query_declaration_processing_status(declaration_processing_id="", declaration_schema=DeclarationSchema.VAT_DECLARATION, request_body=None)

• endpoint path: /queryDeclarationProcessingStatus

• returns QueryDeclarationProcessingStatusResponse

• query_declaration_data(declaration_processing_id="", declaration_schema=DeclarationSchema.VAT_DECLARATION, request_body=None)

• endpoint path: /queryDeclarationData

• returns DeclarationDataResponse

• query_vat_declaration_data(declaration_processing_id="", declaration_schema=DeclarationSchema.VAT_DECLARATION, request_body=None)

• endpoint path: /queryVatDeclarationData

• returns QueryVatDeclarationDataResponse with metadata and gzipped XML file bytes

• handles the multipart response internally; client.call() itself remains a simple XML-document entry point

• declaration_upload(file_path=..., declaration_schema=DeclarationSchema.VAT_DECLARATION, period_start=None, period_end=None)

• runs manageDeclarationUpload, manageDeclarationPartition, and manageDeclarationFinalize

• gzips and splits the XML file before partition upload

• uses period_start/period_end when provided; otherwise reads the VAT declaration period from the XML

• returns the resulting declarationProcessingId

• declaration_submission(declaration_processing_id="", declaration_schema=DeclarationSchema.VAT_DECLARATION, request_body=None)

• endpoint path: /manageDeclarationSubmission

• returns None on success; raises the underlying exception on error

declaration_schema accepts DeclarationSchema.VAT_DECLARATION ("VAT_DECLARATION") and DeclarationSchema.A60_DECLARATION ("A60"). Response parsers expose declaration schema, attachment status, and declaration processing status code fields as string enum values.

Multipart download example:

result = client.query_vat_declaration_data(
    declaration_processing_id="processing-id",
    declaration_schema=DeclarationSchema.VAT_DECLARATION,
)

print(result.declaration_schema)
print(result.original_request_version)

if result.has_file:
    result.save_file()
    result.save_xml("vat-declaration.xml")

query_vat_declaration_data() hides the multipart parsing. The returned file_content is the gzipped declaration XML file part as bytes. Use save_file() to persist the gzipped file, extract_xml() to get decompressed XML bytes, or save_xml(path) to write the decompressed XML. There is no public multipart_response switch on client.call(); use this high-level method for the VAT declaration data download.

Configuration

EvatConfig currently selects one of the built-in NAV EVAT base URLs:

• EvatEnvironment.TEST -> https://api-test.eafa.nav.gov.hu/analyticsService/v1
• EvatEnvironment.PRODUCTION -> https://api.eafa.nav.gov.hu/analyticsService/v1

from qtx_nav_evat import EvatConfig, EvatEnvironment

config = EvatConfig(environment=EvatEnvironment.TEST)

Local Demo Script

main.py is a local manual test runner configured through top-level constants. Fill in the credentials and select the operation before running it.

Common constants:

• ENVIRONMENT
• OPERATION
• USERNAME
• PASSWORD
• TAX_NUMBER
• SIGN_KEY
• TAXPOINT_DATE
• ATTACHMENT_FILE
• LOG_XML
• INCLUDE_SOFTWARE_INFO

PowerShell example:

.\.venv\Scripts\python.exe .\main.py

Documentation

• English usage guide: docs/usage.md
• API reference: docs/api.md
• Model and payload reference: docs/models.md
• Hungarian overview: README.hu.md

Development Notes

• the project uses a standard src layout
• packaging is configured in pyproject.toml
• tests currently include an import smoke test
• request and response XML can be inspected through on_request_xml and on_response_xml