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.

Push-Type Operation

The 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.

Protocol and Format

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

Transferred Document Types

The following types of (outgoing) documents are transferred from Számlázz.hu to the recipient system:

• invoices
• reversal invoices
• corrective invoices
• advance invoices
• final invoices
• payment requests
• delivery notes

If the recipient system does not need any of the document types, filtering can be done based on the <type> tag within the <base> tag.

Events Triggering Invoice Transmission

Számlázz.hu can resend an issued invoice multiple times to the recipient system. Each time, it transfers all (current) data of the invoice (in XML format). The following events trigger the transmission (for the first time or repeatedly) of the invoice to the recipient system:

• invoice issuance
• change in payment status of the invoice
• change in editable data of the invoice retroactively, namely:
• posting date
• customer ledger number
• customer ledger identifier
• invoice "continuous performance" status
• revenue account number of any invoice item
• VAT account number of any invoice item
• economic event of any invoice item
• VAT economic event of any invoice item
• start date of the accounting period of any invoice item
• end date of the accounting period of any invoice item

These data can be modified on the invoice details page.

Outgoing Invoice Submission

Outgoing invoices are submitted in XML format and comply with the following XSD: https://www.szamlazz.hu/szamla/docs/xsds/szamla/szamla.xsd

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:

1. The HTTP response status code must be 200 (OK).
2. The response must be correctly formatted XML.
3. The response must contain the invoice receipt number assigned in the recipient system to the submitted invoice.

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.

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.

Handling Payment Methods

In Számlázz.hu, during manual invoice creation or administration of credits, payment method can be selected from a fixed set of values. However, invoices created with Számla Agent can have an arbitrary string passed as the payment method by the sending system. Therefore, when submitting invoices online, the payment method is sent in XML in two ways:

• The <fizmod> tag contains the arbitrarily valued string stored as the payment method (essentially this appears as the payment method on the invoice).
• The <fizmodunified> tag represents the normalized value of this. The value set includes: bank transfer, cash, credit card, check, cash on delivery, gift voucher, Barion, barter, group collection, OTP Simple, compensation, coupon, PayPal, PayU, SZÉP card, voucher, other. If the value of <fizmod> cannot be clearly assigned to any of these, then the value will be "other". These values can also be found in the XSD.
• The value of <keszpenz> is true if the payment is in cash, otherwise false.

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 <base> cluster under <invoice>. This is the unique data with which the received (accepted) invoice can be clearly identified in the recipient system.

What Happens When Invoice Issuance Is Based on a Payment Request?

1. In this case, the newly issued invoice is sent to the recipient system, but the payment request is not resent.
2. The newly issued invoice contains the payment request number in the <base><paymentrequestnumber> tag. However, it does not contain the payment request receipt number.
3. The deletion of the payment request depends on what is included in the settings (Settings/Account Settings).
4. Számlázz.hu does not send any message to the recipient system about the deletion of the payment request.