ExSzamlazzHu

A very thin wrapper for the Szamlazz.hu API.

---

Purpose

The Szamlazz.hu 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 Szamlazz.hu API documentation. This hopefully makes the adoption easier, as one would need to familiarize oneself with the service's own API anyway.

Features

Szamlazz.hu function	Is 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	❌

Installation

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"}
  ]
end

Configuration

Szamlazz.hu

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

As Szamlazz.hu 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.

Tesla

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 Szamlazz.hu 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 Szamlazz.hu, the parameters follow the same shape as described in the Szamlazz.hu API documentation.

ExSzamlazzHu.create_invoice(%{
    beallitasok: %{
      szamlaagentkulcs: "your Szamlazz.hu 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: "[email protected]",
      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 Szamlazz.hu API.

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

%ExSzamlazzHu.CreateInvoice.Result{
  success: true,                # Indicates whether the invoice was created
  raw_response: nil,            # The raw response from the szamla.hu 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 Szamlazz.hu
  szlahu_error: nil,            # The error message, if any (and in Hungarian)
  szlahu_error_code: nil,       # The error code
  szlahu_down: false            # Indicates whether the Szamlazz.hu 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 Szamlazz.hu'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 Szamlazz.hu is successful, but Szamlazz.hu 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 Szamlazz.hu API documentation about error codes