VatchexGreece, an Elixir library for retrieving Greek company info from the SOAP web service of GSIS

2023-03-06

3 minute read

software

VatchexGreece is an Elixir library to easily pull company information from the SOAP web service (WSDL definition) of the Greek General Secretariat of Information Systems for Public Administration (GSIS) using the VAT ID (Αριθμός Φορολογικού Μητρώου, abbreviated as “ΑΦΜ” or “Α.Φ.Μ.”).

The backstory; or, why does this exist?

In 2022 I developed vatcheck-api, my first “serious” web service for TECTRA Ltd. I wrote it in Python/FastAPI with Tortoise ORM backed by SQLite and utilized source code from arthurdejong/python-stdnum and in particular his vat.py for Greece to “clean” VAT IDs and make HTTP requests to the GSIS SOAP web service.

The original vatcheck-api (in daily productive use at TECTRA Ltd and not publicly available) provides views for:

fetching data for a company using a VAT ID,
showing the company’s data after storing it in a record (or showing the record if one exists for the VAT ID),
saving the web service response in the database,
amending a record’s JSONField with ancillary information specific to TECTRA Ltd for those records that represent customers,
listing all records,
live-searching across records using htmx and a /search POST endpoint, and
delivering a single record’s data in XML (using dict2xml so that it can be consumed from LibreOffice with the WEBSERVICE and FILTERXML functions.

The company-internal vatcheck-api is complemented by further microservices I have developed, all of them in Python. While further developing the microservices landscape of TECTRA Ltd over the past 10 months, I saw first-hand, again and again, the practical difficulties of deploying them and integrating them. Thus, I have started reimplementing parts of the landscape, piecemeal.

One of the things I found missing was the functionality that VatchexGreece now delivers (see above).

Personal caveats

This is my first open-source release and my first-ever Elixir project after dabbling in Elixir since January 2023 (“The Year of Elixir” as my New Year’s resolution) and in Ash Framework and Phoenix in particular. This means that it’s a learning platform, on which I have so far applied conventions I picked up by reading other Elixir libraries’ code. Moreover, you might notice a certain… fascination with the |> pipe operator, but I guess that’s to be expected for a long-time user of HP’s RPN calculators (HP 48G, HP 12c). I have also never written tests before, ever, so that’s on the TODO list for this project, and for my programming skillset in general.

Library caveats, and EEx to the rescue

Initially, I tried to submit the POST request using Soap, but quickly found out that it doesn’t support generating WS-Security headers; unfortunately, the GSIS web service requires UsernameToken headers for authentication. I am also uncertain that Soap was able to parse the WSDL definition correctly; plus, if I understood correctly from my short dabbling in XML, generating the proper request template from WSDL takes a lot of boilerplate.

Instead of wasting time on learning XML and Soap, and writing boilerplate to generate an XML request template that won’t likely change anytime soon from a WSDL definition that seems to have not changed in more than a decade, I saw the XML that suds was generating in my vatcheck-api project, and turned it into an EEx template (priv/request.xml.eex) to which I pipe the username, password, and VAT IDs you call from (afmCalledBy), and call for (afmCalledFor).

How to install

The package is available on Hex and can be installed by adding vatchex_greece to your list of dependencies in mix.exs:

def deps do
  [
    {:vatchex_greece, "~> 0.5.2"}
  ]
end

How to configure

Setup VatchexGreece in your config.exs, and define the username, password and afmCalledBy parameters:

config :vatchex_greece, :globals,
  gsis_wsdl_url: "https://www1.gsis.gr/webtax2/wsgsis/RgWsPublic/RgWsPublicPort?wsdl",
  xml_template: "priv/request.xml.eex",
  username: "",
  password: "",
  afmCalledBy: ""

Note: since neither gsis_wsdl_url nor xml_template are really user-configurable, I should better pull them out into a separate config block.

Documentation

The docs can be found at https://hexdocs.pm/vatchex_greece.