Details of Operation
If you have configured the recipient system, identification key, and date(s) in your billing account, then Számlázz.hu "initiates" the transmission of invoice and/or receipt and/or transaction data to the recipient system.
🧠 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. Resending of invoices can be initiated by re-entering the identification key.
🌐 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.
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.
Example:
| addkeytourl | system URL | key | submission URL |
|---|---|---|---|
| false | https://ab.cd/ef/ | 3412syste | https://ab.cd/ef/ |
| true | https://ab.cd/ef/ | 3412syste | https://ab.cd/ef/3412syste |
Expected Response
Számlázz.hu needs to detect that the HTTP request it sent has been "received", interpreted, and processed by the recipient system. The invoice response must comply with the following XSD: https://www.szamlazz.hu/szamla/docs/xsds/szamla/szamlavalasz.xsd
This requires three things:
- The HTTP response status code must be
200 (OK). - The response must be correctly formatted XML.
- The response must contain the invoice receipt number assigned in the recipient system to the submitted invoice.
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.
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.