qtx-nav-core

Python package for the NAV Online Szamla core client.

Install/package name: qtx-nav-core

Python import package: qtx_nav_core

Quick Start Map

If you open this package months later, start with this mental model:

• NavAuth: technical user credentials for NAV signing and authentication
• NavSoftwareInfo: software metadata block included in each request
• NavRequestContext: immutable container that carries auth, software info, and request ID prefix
• NavRequestBody: abstract extension point for a concrete NAV operation
• NavXmlRequestBuilder: creates the full NAV XML document from context plus request body
• NavApiClient: low-level HTTP client for XML requests, multipart uploads, and multipart responses
• NavApiResponse: HTTP status, headers, parsed XML document, and received multipart parts
• NavCallSpec: one request execution description, including path and optional file upload settings
• NavRequestRunner: high-level orchestrator that builds XML, sends the request, and validates NAV result status
• NavDocumentStatus: parsed summary of NAV's <result> block
• NavApiKind / NAV_XML_PROFILES: NAV API profile selection for OSA/eVAT namespaces and request versions
• NavUtils: shared helper methods for hashing, decoding, status parsing, and response formatting

Typical Usage Flow

1. Create a NavAuth instance.
2. Create a NavSoftwareInfo instance for the calling application.
3. Create a NavRequestContext from the auth object and software info.
4. Implement a concrete NavRequestBody subclass for the target NAV endpoint.
5. Create a NavApiClient with the NAV base URL.
6. Create a NavRequestRunner with the API client and request context.
7. Execute the call with NavCallSpec.
8. Read the returned NavApiResponse.document and, for multipart responses, NavApiResponse.parts.
9. Let NavValidationError surface NAV-side failures when enabled.

Response Handling

NavRequestRunner.call(...) returns the full NavApiResponse, not only the XML document. This keeps the HTTP status and headers available and also exposes multipart response parts returned by NAV.

For endpoints that can return multipart content, pass multipart_response=True to runner.call(...). The client sends an Accept header that allows multipart responses, parses the MIME parts, stores them in NavApiResponse.parts, and uses the first XML part as NavApiResponse.document when one is present.

response = runner.call(
    NavCallSpec(path="/query", request_body=request_body),
    multipart_response=True,
)

xml_document = response.document
for part in response.iter_parts():
    print(part.name, part.filename, part.content_type, len(part.content))

API Kind Detection

NavApiClient.api_kind is derived from the configured base URL. URLs containing .eafa. use NavApiKind.EVAT; URLs containing .onlineszamla. use NavApiKind.OSA. NavRequestRunner passes this value to NavXmlRequestBuilder, which then selects the matching XML namespaces and request version from NAV_XML_PROFILES.

This version supports the eVAT 2.0 XSD schema set through the eVAT XML profile. For eVAT URLs, generated requests use the EAR 2.0 API/base/data namespaces together with the NAV common namespace.

Software Info

NavSoftwareInfo is required for every request. Create and pass a populated instance into NavRequestContext; otherwise XML generation raises ValueError before the NAV call is sent.

The current model defaults are empty development placeholders only. Real callers must set the software identifier, name, version, developer contact, developer country code, and developer tax number explicitly.

software = NavSoftwareInfo(
    software_id="MOCK-EVAT-12345678",
    software_name="Mock eVAT Client",
    software_operation="LOCAL_SOFTWARE",
    software_main_version="1.0",
    software_dev_name="Mock Developer",
    software_dev_contact="mock.dev@example.com",
    software_dev_country_code="HU",
    software_dev_tax_number="12345678",
)

context = NavRequestContext(auth=auth, software=software)

Release Notes

0.2.4

This release only changes generated NAV request IDs: NavXmlRequestBuilder now uses request_id_prefix + UTC timestamp with microseconds and validates the generated requestId against NAV's 30 character limit and allowed character set. No public API or request/response model behavior was intentionally changed.

Package Reference

For a longer in-package reminder that is shipped with the installed distribution, see qtx_nav_core/docs/package_map.md.

Scope

This package currently contains:

• package layout matching the Dart core library
• public exports for auth, request building, request running, API responses, and multipart parts
• models, services, and utils for NAV XML and HTTP calls
• tests and tooling configuration

Package layout

qtx_nav_core/
  models/
  services/
  utils/
tests/

Development

pip install -e .[dev]
pytest
ruff check .