NRA HFRG - Flat XML Import Format

Simplified XML for feeding declaration data into the hub. "Flat" means all single-value fields sit at one level under the root (e.g. CarrierName instead of carrier/reprfirm/name). Only the repeating collections - counterparties, addresses, goods - are nested.

Two entry points consume this format:

• SAP input folder - the hub watches the configured input folder, converts each file into NRA declaration XML and places the result in the regular input folder, where it is signed and submitted.
• Import XML button on each declaration form - fills the form in the browser instead of submitting directly.

Both paths use the same element names. Where their behaviour differs, it is called out below.

Files in this folder

Schema

flat-import.xsd describes all three input roots, so one schema covers every input file. Validation is optional - the hub does not require it and never asks for a schema reference - but a file can be checked against it before being sent, by pointing the document at it:

<HFRGBULGARIA xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
              xsi:noNamespaceSchemaLocation="flat-import.xsd">

Every length, pattern and enumeration in it is copied from the NRA schema for the element it converts into, so nothing in it is stricter than the corresponding NRA rule. Where the NRA schemas differ between a person and a firm - the carrier identifier and its type - the schema accepts the union of both, because XSD 1.0 cannot switch on the value of another element.

It checks values, not completeness: which elements are required depends on OperationType, which XSD 1.0 cannot express, so nearly everything is optional and the tables below remain the reference. Element order is not enforced either, and empty elements are valid everywhere, both matching how the converter reads the file.

Declaration types

HFRGAnnul and HFRGConfirm are routed by their root element name; their OperationType is not read.

Header

InternalReference is more than a label: it becomes the job folder name (invalid file name characters and spaces are stripped) and is echoed back as INTERNALREFEREN in the result file. When it is empty a GUID is used instead, and the result can no longer be matched to the source document.

What the hub does with the file

• A file whose root element is already a native NRA declaration (decHfrImport, decHfrExport, decHfrAnnul, decHfrConfirm, decHfrInternal, decHfrThirdcountry) is passed through unchanged - no conversion is attempted.
• The converted declaration is written as <prefix>_<yyyyMMdd_HHmmss>.xml in Windows-1251, and the source file is deleted.
• If conversion fails, the source is renamed to <file>.convert-error so it is not retried in a loop.
• A UTF-8 BOM and an encoding="..." declaration are honoured. A prolog version= other than 1.0 is rewritten to 1.0 before parsing.
• Booleans accept true (any case) or 1; anything else counts as false.
• Decimals accept both . and , as the decimal separator.
• Identifier type elements fall back to 1 when missing or non-numeric.
• Once the NRA returns a UIN, the hub writes <ResultsFolder>/sap/<reference>_<yyyyMMdd_HHmmss>.xml - see flat-import-result.xml.

Fields the hub fills in itself

Address codes: postal code, not EKATTE

Every *Ekatte element expects a 4-digit postal code. The hub resolves it to an EKATTE code through wwwroot/data/postal-to-ekatte.json.

A value that is not a known postal code is left blank on purpose, so the declaration fails validation instead of being submitted with a wrong EKATTE. Passing an EKATTE code directly (68134) therefore drops the field.

The browser importer is more forgiving: when the lookup fails it leaves the raw value in the form field. The SAP folder path does not.

Affects LoadEkatte, TranshipmentEkatte, TransferEkatte and Address/Ekatte.

1. Flat XML element reference by declaration type

auto = optional in the file; filled from the signer settings and rewritten per signer at signing time.

The transhipment block is ignored unless IsTranshipment is true; the transfer block unless IsTransfer is true; carrier and organizer unless the matching Has... flag is true and the corresponding ...Ident is non-empty. The transfer carrier is skipped when TransCarrierIdent is empty.

2. Counterparties (Import, Internal, ThirdCountry)

These declaration types have no Country element - it exists only under Buyer in Export.

3. Buyers (Export only)

4. Goods (all types)

Quantity type

Any other value is passed through unchanged and will fail validation.

Purpose codes by type

5. Identifier types

Main identifier (recipient/shipper)

Person identifier (carrier/organizer/transfer carrier as person)

Firm identifier (carrier/organizer/transfer carrier as firm, counterparty, buyer)

6. Annul (OperationType 11) - separate format

7. Confirm (OperationType 12) - separate format