View Source ExSzamlazzHu

A very thin wrapper for the API.



The API relies on multipart/form-data requests with an attached XML file, and the API's response is either text/plain or application/xml.

This wrapper intends to abstract away the aforementioned aspects of the communication with the API by providing an interface which can be called with standard Elixir maps, and the result is also presented with an Elixir struct.

{:ok, %ExSzamlazzHu.CreateInvoice.Result{} = result} = ExSzamlazzHu.create_invoice(params)

Even though the package provides its interface in English (i.e. with functions like create_invoice), but as a thin wrapper, the expected parameters follow the same shape as described in the API documentation. This hopefully makes the adoption easier, as one would need to familiarize oneself with the service's own API anyway.


Features functionIs it implemented?
Create invoice
Reverse invoice
Register credit entry
Query invoice pdf
Query invoice xml
Delete pro forma invoice
Create receipt
Reverse receipt
Query receipt
Send receipt
Query taxpayers
Create supplier account



The package can be installed by adding ex_szamlazz_hu to your list of dependencies in mix.exs:

def deps do
    {:ex_szamlazz_hu, "~> 0.1.1"}



The authentication for services are done using the so called "agent key" or the username/password pair.

As expects the credentials in the request payload, this package also works the same way. You will need to provide your credentials inside the request parameters.


ExSzamlazzHu uses Tesla as a HTTP client. This means that you should configure Tesla to use the library your project is using. E.g. in your config/config.exs:

config :tesla, :adapter, Tesla.Adapter.Hackney

See more in the Tesla documentation.


Usage notes

The wrapper does no validation of the input parameters. The validation of the input parameters is done by API.

The XML for the request is built using the xml_builder package and thus the provided values are escaped when the XML is built.


Usage example

To create an invoice via, the parameters follow the same shape as described in the API documentation.

    beallitasok: %{
      szamlaagentkulcs: "your agent key",
      eszamla: true,
      szamlaLetoltes: false,
      valaszVerzio: 1,
    fejlec: %{
      teljesitesDatum: "2023-11-12",
      fizetesiHataridoDatum: "2023-11-12",
      fizmod: "Stripe",
      penznem: "EUR",
      szamlaNyelve: "en",
      megjegyzes: "",
      rendelesSzam: "Skynet-O129A22",
      dijbekero: false,
      fizetve: true
    elado: %{},
    vevo: %{
      nev: "Sarah Connor",
      orszag: "USA",
      irsz: 32456,
      telepules: "Los Angeles",
      cim: "Engineering Drive",
      email: "",
      sendEmail: true
    tetelek: [
        megnevezes: "T-101 disassembly kit",
        mennyiseg: 2,
        mennyisegiEgyseg: "db",
        nettoEgysegar: 100,
        afakulcs: 27,
        nettoErtek: 200,
        afaErtek: 54,
        bruttoErtek: 254,

The result of the call is a struct, which - among other things - contains the original response from the API.

{:ok, %ExSzamlazzHu.CreateInvoice.Result{}} = ExSzamlazzHu.create_invoice(params)

  success: true,                # Indicates whether the invoice was created
  raw_response: nil,            # The raw response from the API
  path_to_pdf_invoice: nil,     # The path to the created invoice, if the PDF file was requested
  szlahu_id: nil,               # The (internal) ID of the created invoice
  szlahu_szamlaszam: nil,       # The invoice number
  szlahu_nettovegosszeg: nil,   # The net amount of the created invoice
  szlahu_bruttovegosszeg: nil,  # The gross amount of the created invoice
  szlahu_kintlevoseg: nil,      # The amount not yet paid
  szlahu_vevoifiokurl: nil,     # The URL of the invoice - ExSzamlazzHu decodes the percent-escaped string sent by
  szlahu_error: nil,            # The error message, if any (and in Hungarian)
  szlahu_error_code: nil,       # The error code
  szlahu_down: false            # Indicates whether the API is not available

The properties with the szlahu prefix are not arbitrary, these are fields returned by the API.

The raw_response contains the entire response of the API as a %Tesla.Env{} struct.

If the params.beallitasok.szamlaLetoltes is true, then's response will contain the invoice PDF. In this case, the wrapper will attempt to save the file locally (in the temp dir), and set the path_to_pdf_invoice to point to the saved file. You will still be able to access the file in the response via the raw_response property.

If the call to is successful, but returns an error, the error will be described in szlahu_error (in Hungarian) and szlahu_error_code (as a string). To learn more about the error codes, check out the API documentation about error codes