Skip to main content

How It Works

The connection can be set up in two ways:​

For public connections: In the billing account, under the Account Settings > Online Financial Data Connection menu, you can select the financial data connection to be established from the dropdown menu and configure it. Once you have configured the recipient system, the identification key, and the dates, Számlázz.hu will initiate the transmission of invoice and/or receipt and/or transaction data to the recipient system.

For private connections: After registration, our IT Support team will set up the requested connection for you.

🧠 Data sending operation​

Transmission is push-type, meaning when an invoice is issued, a bank transaction is created, or a receipt is generated in Számlázz.hu, a message is sent to the recipient system. There is no option for the recipient system to "query" the invoice data.

The data is transmitted asynchronously. Számlázz.hu performs the data transmission within 15 minutes after invoice issuance. Bank transactions are batched and transmitted periodically. Receipts are batched and sent once daily.

🔑 Identification Key​

The identification key identifies the customer in the recipient system. Only the administrator of the recipient system can provide a valid identification key to customers, who can set this key in their invoice issuing account. When setting the key, we check the system-specific postfix, which in practice is the last 5 characters of the key. This 5-digit identifier is configured during registration in the Számlázz.hu system, and we only allow the customer to set a key that matches this.

The maximum length of the identification key is 40 characters, and it is also transmitted with each data packet to the recipient system.

In case of an identification key error, the recipient system can notify Számlázz.hu through the response message. In response, we terminate the registration and send an email to the user. To resend invoices, the identification key must be changed.

The connection can be modified in the billing account under Settings > Account settings > Online financial data connection > Connections, by clicking the “Modify” button (you can also change the identification key there).

🌐 Communication protocol​

Data is sent over HTTP or HTTPS protocol, and along with the HTTP/HTTPS request, an XML file is sent to Számlázz.hu.

This XML file contains all invoice/receipt/transaction data. Each XML file contains the data of one invoice/receipt/transaction, so for each submitted data, the recipient system receives one HTTP request containing the detailed data of one invoice/transaction within one XML file. Essentially, we send all available invoice and/or transaction data in XML, and if necessary, the invoice PDF itself is also included in base64 encoding. PDF transmission is optional and must be configured in Számlázz.hu during system registration to determine if the invoice image needs to be included in the XML during online submission.

It is the responsibility of the recipient system to receive, interpret, and process the XML file (invoice data) received in the HTTP request. The HTTP request is a POST request with a content-type of application/xml and UTF-8 character encoding.

The header of the HTTP request contains the X-Szamlazzhu-Key key, which contains the identification key set by the invoice issuer in the invoice issuing account (when selecting the recipient system and activating the invoice data transfer service). This is the key that the recipient system uses to identify which customer's data is coming from the invoice issuer account.

Identifier key is always sent

Important: We always send the identifier key with every data package in the X-Szamlazzhu-Key HTTP header. This is a default function, no separate configuration is needed. Key concatenation (addkeytourl) is a separate, optional function that appends the key to the end of the URL.

Further parameterization allows Számlázz.hu to append the recipient URL with the key. That is, if the recipient system expects it, it is possible to append the company-level key value to the system-level configured URL.

🔗 URL and Key Management​

How does data transmission work?​

Számlázz.hu sends all partner data to the receiving system through a single URL. This solution is simpler and more efficient for both parties.

What do you need to know?​

  • You can receive all client data on one URL - no need for separate URLs for each company
  • The key helps distinguish - every data package contains the client identifier key
  • Distribution happens in your system - you decide how to handle different clients' data

Key appending option​

If you want, we can append the key to the end of the URL (addkeytourl setting). This can help distinguish different clients on the receiving side.

Example:

addkeytourlsystem URLkeysubmission URL
falsehttps://ab.cd/ef/3412systehttps://ab.cd/ef/
truehttps://ab.cd/ef/3412systehttps://ab.cd/ef/3412syste
Why is this solution simpler?
  • You only need to maintain one endpoint on the receiving side
  • No need for separate URLs for each client
  • The key is in every data package for identification
  • Flexible distribution in your own system

Expected Response​

Receiving endpoint requirements

We can only work reliably with endpoints that return HTTP 200 (OK) and the correct response XML in a single HTTP response body. We do not support endpoints that answer only with HTTP 302 (redirect) when receiving the request, for example Google Apps Script (or similar web apps). See Registration for details.

Számlázz.hu needs to detect that the HTTP request it sent has been "received", interpreted, and processed by the recipient system. The response must comply with the XSD corresponding to the data type:

This requires four things:

  1. The HTTP response status code must be 200 (OK).
  2. The response must be correctly formatted XML.
  3. For outgoing and incoming invoices: The response must include the <id> value and it must match the <id> received in the invoice XML (outgoing & incoming: <alap><id>...</id></alap>). If the <id> in the response does not match, the response will be rejected. See Outgoing invoices – Expected response and Incoming invoices – Expected response for details.
  4. The response may contain the invoice receipt number (registration number / iktatószám) assigned in the recipient system to the submitted invoice (for invoices).

About the Invoice Receipt Number​

Számlázz.hu allows the recipient system to assign a unique receipt number to the freshly received invoice. This receipt number must be sent back to Számlázz.hu as a response when the invoice is first received. If an invoice receipt number is received in the response:

  • Számlázz.hu stores it among the invoice data (it does not appear on the invoice PDF!)
  • When resending the invoice, this receipt number is sent along with the rest of the invoice data.

As detailed above, Számlázz.hu always transmits all invoice data to the recipient system in full and invoice data can be resent multiple times (Events Triggering Invoice Transmission). When the invoice data is first sent, the receipt number is always empty. When the invoice data is sent for the second (or subsequent) time, the receipt number field may contain data depending on whether Számlázz.hu received a receipt number from the recipient system in response to the previous transmission.

Key error handling​

In the case of a faulty key, the response has the option to send two special parameters within the hibakodTipus:

KEY_ERR: faulty key. The transmitted key is not found in the receiving system, in this case the invoice will not be resubmitted until the next change.

KEY_DEL: key to be deleted. Delete the information required for online dispatch from the billing account. This response will notify the account holder by email that the online connection to the receiving system has been disabled in their account. As the sending is asynchronous, vouchers already marked for dispatch can be transferred even after the fact of cancellation has been registered.

Receiving Initial or Resubmitted Invoice Data​

When receiving invoice data, the recipient system must accurately determine whether the received invoice data:

  • is a new invoice, arriving in the recipient system for the first time (insert)
  • or if this invoice has previously been stored in the recipient system, and since this is a repeated (resubmitted) data transmission, the data of the already stored invoice must be updated (update)

For this determination, we do not recommend using the receipt number field. Experience has shown that the most appropriate data for this determination is the <id> data within the <alap> cluster under <szamla>. This is the unique data with which the received (accepted) invoice can be clearly identified in the recipient system.

Details of Faulty Operation​

Szamlazz.hu detects if the data it sends (HTTP/HTTPS request) cannot be received by the target system or if the correct XML response is not received. In this case, it tries to send the data in question to the receiving system again and again (at given intervals). If the given invoice/receipt/transaction cannot be received by the external system within 72 hours, the invoice/receipt/transaction is "dropped" from the send queue and will not be retried. It will be parked.

warning

If a receiving system gives an incorrect response for an extended period of time, or no response at all, or a particularly slow response, your receiving system will be disabled. We do not disconnect the data connection in the billing accounts that are set up, but we stop the background process that is performing the transfer.

The activation is done manually, the receiving system's data administrator must notify us when the error has been corrected and the data flow can start again.