Invoices with Számlázz.hu
On this page
WorkSmartHub can issue invoices for work tickets through Számlázz.hu, the Hungarian online invoicing service. The invoices are created in your Számlázz.hu account; WorkSmartHub keeps a copy of their status and PDF, and keeps the status in sync. Invoicing is off by default.
The screenshots on this page come from an installation connected to a Számlázz.hu test account. They follow one example: a coffee machine repair service and its clients Minta Kávézó Kft., Minta Péter, Muster Gastro GmbH and Beispiel Café AG. The clients, items and addresses are invented.
Setting it up#
Open App Konfiguráció → Számlázz.hu (Super Admin). The page shows the setup progress in six steps (Beállítás folyamata):
- Regisztráció: register at szamlazz.hu if you have no account yet.
- API kulcs: enter the Számlázz.hu API kulcs (the agent key generated in your Számlázz.hu account) and, recommended for production, the HMAC aláíró kulcs (signing key that protects the invoices' financial data against tampering). Both are write-only: they are never shown again after saving, and leaving the field empty keeps the stored value.
- Cégadatok: fill in the company details, including bank name and account number (Ugrás a Cégadatokhoz → jumps there).
- Számlázási beállítások: default payment method (Átutalás transfer, Készpénz cash, Bankkártya card, Utánvét cash on delivery), payment deadline in days (default 8), invoice language (Hungarian, English, German, Italian, Romanian, Slovak, Croatian, French, Spanish, Czech or Polish; a client can have its own), delivery of the invoice (Nincs none, Számlázz.hu (közvetlen) sent by Számlázz.hu, WorkSmartHub értesítés), invoice prefix (required while invoicing is on), an invoice comment and the optional Árfolyam forrása (the source of the exchange rates the company uses, printed on foreign-currency invoices).
- Kapcsolat teszt: Konfiguráció ellenőrzése checks the connection, the prefix and the bank details.
- Funkció engedélyezése: tick Számlázás engedélyezése (Enable invoicing) and save.
While invoicing is on, the company details have four more optional fields for invoices in foreign currency: Euro bankszámlaszám, USD bankszámlaszám, IBAN and SWIFT/BIC (see Currency and exchange rate). While invoicing is off, these fields are hidden. The IBAN checksum and the SWIFT/BIC length (8 or 11 characters) are checked at save.
Konfiguráció ellenőrzése logs in to Számlázz.hu with the stored key and checks the prefix and the bank details. When everything is in order, it shows Minden beállítás rendben, API kapcsolat sikeres! and step 5 of the tracker turns green. A wrong key gives Sikertelen bejelentkezés. Ellenőrizze az API kulcsot.; no connection gives Nem sikerült csatlakozni a Számlázz.hu-hoz.
The check also uses the endpoint POST /api/invoicing/validate-tax-number, which queries taxpayer data from NAV through Számlázz.hu (Client admin permission). It checks Hungarian tax numbers only; for a foreign client it answers without querying NAV.
The default VAT rate comes from Általános forgalmi adó. A rate of 0 % can be combined with an exemption code: AAM (Alanyi adómentes, subject exempt) or TAM (Tárgyi adómentes, transaction exempt); the code is sent instead of the rate. The code counts only while the default rate is 0; at any other rate it is ignored.
While invoicing is on, the VAT rate must be 27, 18, 5 or 0, and Valuta megjelenítés (the price currency) must name HUF (Ft, forint), EUR (€, euro) or USD ($, dollar); any other value gets a field error at save, and nothing is saved.
VAT rate per item#
Acting works, components and deliveries have an optional ÁFA kulcs (üres = alapértelmezett) field. Empty means the default rate above; prices and checks then work as without the field. With a rate set, the item's gross price is checked against its own rate, ticket lines with that item use it, and the invoice line is sent with it.
- While invoicing is on, the field offers 27, 18, 5 and 0 %. At 0 % the item can be marked TAM (tárgyi adómentes), for example an exempt activity. AAM stays an installation-wide setting, because it describes the seller.
- While invoicing is off, any rate from 0 to 100 % can be saved. Turning invoicing on later does not check existing items; issuing an invoice refuses a line whose rate is not 27, 18, 5 or 0 and names the item.
- The component Excel file has an optional ÁFA kulcs (%) column. Files without it can be imported too; the stored rates are kept.
- An invoice keeps the rates it was issued with, even if an item's rate changes later.
- When a ticket has lines with different rates, the ticket summary and the invoice show the totals per rate, and the delivery e-mail shows only the net and gross totals.
Foreign clients#
While invoicing is on, the client dialog (Clients) has three more fields: Ország (country, empty = Hungary), Közösségi adószám (EU VAT number, shown when the chosen country is in the EU, Hungary included) and Számla nyelve (invoice language, empty = the setting above).
- The EU VAT number is checked offline for its country prefix and format (Greece uses EL). There is no VIES query.
- A foreign client's Adószám is free text: the client's own tax ID. The Hungarian format and the NAV check apply only to Hungarian clients.
- What the invoice sends: the country in English (left out for Hungary), the EU VAT number, and the buyer type Számlázz.hu needs. An EU business (EU VAT number) is sent as an EU taxpayer. A business outside the EU is sent as a non-EU taxpayer with its own tax ID, because Számlázz.hu requires a tax number for that type. Anyone else (for example a foreign private person) is sent without a buyer type.
- An invoice keeps the client's country, EU VAT number and language as they were at issue; credit notes and corrections use these.
VAT treatment#
The issue dialog has an Áfakezelés select. The default comes from the client and the ticket's items:
| Treatment | VAT key on every line | Default for |
|---|---|---|
| Belföldi (domestic) | the line's own rate | Hungarian clients, private persons |
| Belföldi fordított adózás (domestic reverse charge) | F.AFA | never the default |
| Közösségen belüli termékértékesítés (intra-EU supply of goods) | KBAET | EU business, components and deliveries only |
| Közösségen belüli szolgáltatás (intra-EU service, reverse charge) | EUFAD37 | EU business, the ticket has acting work |
| Termékexport (export of goods) | EAM | client outside the EU, components and deliveries only |
| Szolgáltatás harmadik országba (service to a third country) | HO | business outside the EU with a tax ID, the ticket has acting work |
- Every treatment other than domestic puts its key on every line with 0 % VAT. A repair with parts counts as one service, so a ticket with acting work uses the service treatment for its parts too.
- The issue is refused, with the reason, before anything is sent to Számlázz.hu when the client does not fit: the EU treatments need a client in another EU country with a valid EU VAT number for that country, export and third-country service need a client outside the EU (the service also its tax ID), domestic reverse charge needs a Hungarian client with a Hungarian tax number, a goods treatment cannot be used with acting work and a service treatment needs it. An installation with a default rate of 0 and AAM or TAM set can issue domestic invoices only.
- Legal note: for KBAET, EAM and HO the invoice comment gets a fixed note in the invoice language, for example Közösségen belüli adómentes termékértékesítés (Áfa tv. 89. §). For EUFAD37 and F.AFA Számlázz.hu prints its own note.
- The dialog warns when an EU or non-EU business is invoiced as domestic.
- Automatic invoicing does not issue invoices for foreign clients (country other than Hungary): the treatment has to be chosen by hand. The skip is recorded on Hiba Események.
Currency and exchange rate#
The issue dialog has a Pénznem select: HUF, EUR or USD, by default the price currency, and an Árfolyam field: how many forints one euro or dollar is worth (1 EUR = … HUF).
- Enter the rate your company uses for the invoice's fulfilment date. Under the VAT Act (Áfa tv. 80. §) the company chooses the source: by default a Hungarian bank's selling rate; the MNB or ECB rate if it notified NAV of that choice. WorkSmartHub does not fetch rates, so it needs no outbound access other than Számlázz.hu.
- An invoice in another currency than the price currency is converted with the rate entered, which is then required. Conversion works between forint and euro or dollar; euro to dollar is not supported. Unit prices are converted and rounded to two decimals first, then every line is rounded in the invoice currency (HUF to whole forints, EUR and USD to cents); the totals are the sums of the lines.
- On a euro or dollar invoice in the price currency the rate is optional. With a rate, it is sent to Számlázz.hu and stored, so the HUF VAT printed on the invoice matches the stored amounts. Without one, Számlázz.hu applies its own rate.
- Számlázz.hu prints the rate in the HUF summary of the invoice. With a rate of 1 EUR = 400 HUF it reads árfolyam 400 HUF; if the optional Árfolyam forrása setting is filled in (for example OTP), it is printed in front: OTP árfolyam 400 HUF.
- The preview shows the rate and the converted amounts. If the ticket changes between the preview and the issue, the issue is refused because the totals changed, and the dialog loads the preview again.
- Bank account on the invoice: the main account for HUF; for EUR and USD the Euro bankszámlaszám or USD bankszámlaszám, otherwise the IBAN, otherwise the main account. On EUR and USD invoices the IBAN and SWIFT/BIC are printed in the comment.
- Credit notes and corrections use the original invoice's rate. A correction of a euro or dollar invoice that stored no rate asks for the rate printed on the original invoice (see the correction below). Automatic invoicing issues invoices in the price currency without a rate.
- The Számlák page shows the summary cards per currency; amounts in different currencies are never added together.
Automatic invoicing#
With Automatikus számlázás státuszváltáskor (Automatic invoicing on status change) on, the final invoice of a ticket is issued automatically when a ticket admin saves the ticket with the status changed to Számlázandó (To be invoiced):
- It works exactly like Számla kiállítása with the configured defaults (final invoice, default payment method and deadline), with the same checks, the same stored result and the same later status sync.
- At most one invoice per ticket: nothing is issued if the ticket already has an invoice that is not cancelled. A failed invoice counts too; delete or retry it by hand.
- A technician's status change does not issue an invoice (issuing needs the ticket admin role); the refusal is logged and recorded on Hiba Események.
- The status change is always saved, whatever happens to the invoice. A refused check (for example missing company or client data) is written to the log and the error audit; if Számlázz.hu refuses the invoice, a Sikertelen (failed) invoice is stored, as with the manual action.
- It works only while invoicing is enabled. Two saves at the same time, also on different servers, issue only one invoice.
- It skips foreign clients (the VAT treatment has to be chosen by hand) and tickets with an advance invoice; the skip is recorded on Hiba Események.
- It issues the invoice in the price currency.
Who can work with invoices#
- The Számlák (Invoices) menu item appears when invoicing is enabled. The page opens for Super Admins and for ticket admins of at least one workspace.
- Every invoice action (issue, including advance invoices, cancel, convert, credit note, correction, mark as paid, retry payment, sync, refetch PDF) needs the ticket admin role in the ticket's workspace. Ticket admins see the invoices of other workspaces read-only.
- Reading an invoice and its PDF needs access to its ticket; users who are not ticket admins see only the invoices of the tickets assigned to them.
Invoices of a ticket#
On the ticket editor, Számlák opens the invoices dialog of the ticket. Before the first invoice it shows a checklist: API key, company details, invoice prefix, client name, address and city, the tax number (not required for private persons), and invoiceable items (acting works, components or delivery).
Számla kiállítása (Issue invoice) asks for the type, VAT treatment, currency, payment method, deadline and a comment:
- Végszámla (final invoice);
- Díjbekérő (pro forma request for payment, issued as a Számlázz.hu díjbekérő with a
D-number; it is not an invoice); - Előlegszámla (advance invoice, see below).
The payment method and the deadline start at the configured defaults (Fizetési határidő (nap) shows the configured number of days). Before issuing, the dialog shows a preview from the server: the buyer, the lines with their VAT rate or key, the totals per rate, the totals, the exchange rate and the legal note, plus warnings and the reasons why the invoice cannot be issued. Számla kiállítása is enabled only while the preview has no such reason. If the ticket, the client or the rate changed since the preview, the issue is refused and the dialog loads the preview again.
Kiállításkor kifizetve (paid at issue) is offered for a final invoice paid in cash or by card. The invoice is issued as paid at Számlázz.hu and shows as Fizetve at once; no separate payment is recorded.
A ticket can have one open document of each type: while a final invoice is neither paid, cancelled nor failed, a second final is refused, and the same holds for a díjbekérő. If the ticket already has an invoice, the dialog warns before you issue another. A new document within 5 minutes of the ticket's previous one (a double click, a second tab) is refused too. If two people issue for the same ticket at the same moment, one document is issued and the other request is refused with the message that the ticket already has such a document (A munkalaphoz már tartozik ilyen típusú érvényes vagy kiállítás alatt álló bizonylat.).
Actions on an invoice row, depending on its type and status: open the client's invoice portal, download the PDF, Sztornó PDF letöltése (the PDF of the storno invoice, on a cancelled invoice), E-mail újraküldése (send the invoice e-mail again, with WorkSmartHub értesítés delivery), Számla sztornózása (cancel with a storno invoice) or Díjbekérő törlése (delete a pro forma), Fizetettnek jelölés (mark as paid), Fizetés rögzítése újra (retry recording the payment), Díjbekérő végszámlává alakítása (convert a pro forma into a final invoice), Jóváírás létrehozása (credit note), Helyesbítés (correction), ÁFA bontás (VAT breakdown), Állapot szinkronizálás a Számlázz.hu-val (sync the status), and deleting a failed invoice. A disabled action shows the reason when you point at it.
Advance invoice (előlegszámla)
- It is issued when the advance is received: Előleg összege (bruttó) (at most the ticket's gross total), one VAT rate (default the installation rate), an optional name, and Befizetés dátuma (the day the money arrived, which is the fulfilment date). It is issued as paid.
- It is domestic and in the price currency. A ticket can have one valid advance, and not next to a díjbekérő.
- The final invoice of the ticket deducts it automatically with the line Előleg levonása (number); Számlázz.hu issues it as a final invoice settling the advance. The deduction cannot make the total negative. A final whose total becomes 0 is settled at issue.
- While a final invoice deducts the advance, the advance cannot be cancelled or credited; cancel the final first, then the advance can be deducted again or cancelled.
- A díjbekérő cannot be converted to a final invoice on a ticket with an advance, and automatic invoicing skips such tickets.
Correction (helyesbítő számla)
- Helyesbítés on an issued final invoice opens the correction dialog. Each line shows its current quantity and unit price; enter a Mennyiség eltérés (quantity difference) or Egységár eltérés (unit price difference). A line cannot go below zero, and the deduction line of an advance cannot be corrected.
- The correction is a separate document that refers to the original. A quantity change is printed as one line with the difference; a unit price change as the reversal of the line and the line with the new values. The lines keep the original's VAT rate or key, currency and exchange rate.
- Before the correction is issued, WorkSmartHub refreshes the invoice's payment state from Számlázz.hu. If Számlázz.hu cannot be reached, or holds another document under the invoice's number, the correction is not issued and the reason is shown.
- An invoice can have several corrections; each starts from the result of the previous ones.
- What is due after corrections: a lowering correction reduces what is still due on the invoice. When the invoice was paid before it was lowered, the difference shows as owed back to the client (Visszajár). A raising correction adds to what is due until it is paid. The row of a corrected invoice shows this one figure, Helyesbítésekkel együtt fizetendő or Visszajár, in place of the outstanding amount (Kintlévőség).
- A correction that lowers the amount is settled at issue (Rendezve); one that raises it is paid like an invoice.
- An invoice that has a correction cannot be cancelled or credited (Számlázz.hu refuses it too), and a correction itself cannot be cancelled: issue another correction instead.
A euro or dollar invoice issued with the rate field empty, or by an earlier version, has no stored rate. For such an invoice the correction dialog asks for the rate (1 EUR = … HUF), and the correction cannot be issued without it: type the rate printed on the original invoice. An invoice with a stored rate keeps that rate, and the dialog shows no rate field.
Lost answers. Every invoice, advance invoice, correction and díjbekérő is sent to Számlázz.hu with WorkSmartHub's own identifier. If the answer is lost (timeout, dropped connection, unreadable answer), the invoice is marked failed with an unknown outcome, and for 5 minutes a new attempt is refused, because the document may still be created. After those 5 minutes a retry first asks Számlázz.hu for a document with that identifier and stores it if it exists, instead of issuing a second one. The status sync job does the same lookup on its next run after the 5 minutes, without anyone acting. An invoice found this way is stored with its PDF and, with WorkSmartHub értesítés delivery, e-mailed to the client. When Számlázz.hu has no such document, a díjbekérő held by the lost conversion can be converted again.
PDFs and delivery#
- The PDF of every final invoice, pro forma, advance invoice, correction, credit note and storno invoice is fetched from Számlázz.hu when it is issued and kept in a file storage, never in the database: in the ticket's file storage, under
workspace_<id>/ticket_<id>/invoices. - A ticket without a file storage uses the application-level server disk storage Számlák (automatikus), which WorkSmartHub creates the first time it needs it. Its files go under the server disk storage root (the
FileStoragefolder next to the application; with Docker and Kubernetes on the data volume), so it works on IIS, Linux, Docker and Kubernetes without setup. With several application servers, set a cloud storage on the tickets or share the data volume. - A file storage that holds invoice PDFs cannot be deleted.
- If a stored PDF is missing, the download fetches it from Számlázz.hu again.
- Delivery Számlázz.hu (közvetlen): Számlázz.hu e-mails the invoice to the client.
- Delivery WorkSmartHub értesítés: WorkSmartHub e-mails the PDF as an attachment to the ticket's client, through the SMTP server of the default e-mail settings, with the English InvoiceDelivery template (editable like the other e-mail templates). The invoice row shows E-mail elküldve, E-mail sikertelen with the reason (for example no client e-mail address or no SMTP server), or E-mail nincs elküldve. A failed e-mail does not affect the invoice. The e-mails are listed on Ügyfél Email Események as Számla.
- A final invoice converted from a pro forma keeps the pro forma's delivery method.
E-mail újraküldése on the invoice row sends the e-mail again after a confirmation.
The Számlák page#
Summary cards show the number of documents and the paid, unpaid and overdue amounts, one row per currency when invoices exist in more than one. Fizetve is the money paid on invoices and advance invoices: a final invoice counts with its amount after its lowering corrections, and a díjbekérő counts only when it was paid and no final invoice was made from it; credit notes and lowering corrections are not payments. Fizetetlen is what is still due on the open documents with their corrections, the same amount their rows show, and Lejárt is that amount for the overdue ones. Filters: Csak lejárt (overdue only), search by client, ticket or invoice number, status, type (including Előlegszámla and Helyesbítő számla), and a date range. The statuses are Piszkozat (draft), Függőben (pending), Kiállítva (issued), Fizetve (paid), Sztornózva (cancelled), Sikertelen (failed), plus the markers Lejárt (overdue), Rendezve (a correction settled at issue), Törölve (deleted pro forma), Lezárva a Számlázz.hu-ban and Sztornózva a Számlázz.hu-ban. Rows of foreign-currency invoices show the exchange rate, and rows of foreign clients the country, EU VAT number and invoice language.
How the operations work#
Pro forma (díjbekérő)
- Deleting it deletes the díjbekérő at Számlázz.hu as well.
- It can be converted to a final invoice from the Issued and the Paid status, once. The final invoice refers to the díjbekérő, so a payment already recorded on it carries over and the client is billed once. After the conversion, what is due shows on the final invoice; the díjbekérő shows no outstanding amount.
- The final invoice keeps the díjbekérő's currency, amounts, payment method and delivery method. For a euro or dollar díjbekérő the conversion dialog asks for the rate of the final invoice's own fulfilment date (Árfolyam: 1 EUR = … HUF). The rate is optional; left empty, Számlázz.hu applies its own rate.
- A paid díjbekérő is converted only when its payment is confirmed at Számlázz.hu. While a payment is being recorded, and for 2 minutes after, conversion is refused: try again a few minutes later. If recording the payment failed, use Fizetés rögzítése újra first.
- Advance invoices issued as pro formas by older versions appear as Előlegszámla (korábbi díjbekérő). They can be cancelled with a storno invoice but not converted or deducted; issue their final invoice in Számlázz.hu.
Mark as paid
- Records the payment at Számlázz.hu too, and never twice. It first queries the invoice there and sends the payment only if the invoice is open there with no payment on it.
- If it is already fully paid there (for example from a bank import), it is only marked as recorded.
- If it is partly paid there, cancelled there, or the query fails, the invoice becomes paid in WorkSmartHub, but no payment is sent; Fizetés rögzítése újra shows why. That retry also never records a payment twice.
- A HUF invoice counts as fully paid when less than 1 Ft is open at Számlázz.hu (Számlázz.hu keeps whole forints); other currencies must be paid exactly.
Cancellation (sztornó) and credit note (jóváírás)
- Cancelling a final invoice issues a storno invoice at Számlázz.hu. If Számlázz.hu refuses, the invoice stays issued and the error is shown.
- If the outcome is unknown (timeout, dropped connection, unreadable answer), the invoice stays cancelled without a storno number, and for 5 minutes no new cancellation or credit note is accepted. Check in Számlázz.hu whether the storno exists.
- A credit note is the storno of the whole invoice; an invoice has at most one. A cancelled or credit-noted invoice has no outstanding amount. Concurrent requests produce only one storno. After an unknown outcome, the retried credit note first checks Számlázz.hu and sends the storno only if it does not exist there yet.
Status sync
- The background job Számla státusz szinkronizálás runs every 30 minutes by default (20 invoices per run, 1 second between calls), only while invoicing is enabled. A manual sync is also available.
- A payment made in Számlázz.hu marks the invoice as paid.
- An invoice cancelled in Számlázz.hu becomes Sztornózva a Számlázz.hu-ban.
- A díjbekérő deleted there, or settled there by an invoice issued outside WorkSmartHub, becomes Lezárva a Számlázz.hu-ban.
- Closed invoices are not queried again and never become overdue.
Overdue invoices
- An invoice is overdue from the first day, in Hungarian time, after its payment deadline, and only while something is left to pay on it (corrections included).
- The status sync job sets the Lejárt mark and sends the notification, which states the amount still due. Before that, it checks the invoice at Számlázz.hu, so an invoice paid or cancelled there is not reported as overdue.
- Each invoice is notified once, also when several servers run the job.
- The notification goes out on the notification channels set on the ticket, to the users assigned to the ticket and to the workspace's admins and ticket admins. A ticket without a notification channel gets the Lejárt mark and no notification.
- A manual sync never sets the mark; it can only clear it, for example after a payment.
Account check
- Számlázz.hu numbers documents per account, so another account (for example a test account with the same prefix) may have a different document with the same number.
- WorkSmartHub uses a document found at Számlázz.hu only if its type (final invoice, final invoice settling an advance, advance invoice, correction, credit note or díjbekérő), gross total, currency and issue date match. Otherwise it changes nothing and writes a warning to the log and an audit entry.
- If that happens, check the configured API key.
Typical error messages and what to do about them are on the Troubleshooting page.