VatchexGreece

An Elixir library to easily pull company information from the RgWsPublic2 SOAP web service (new since 2023-04-20) of the Greek General Secretariat of Information Systems for Public Administration (GSIS) using the Tax Identification Number (Αριθμός Φορολογικού Μητρώου, abbreviated as "ΑΦΜ" or "Α.Φ.Μ.").

Note: this project is a volunteer effort and not in any way affiliated with GSIS or the data service providers of the Greek Ministry of Finance.

Installation

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, "~> 1.1"},  # or "~> 1.1.1" for the latest patch
  ]
end

Usage

{:ok, data} = VatchexGreece.fetch(
  afm_called_for: "998144460",
  username: "your_token_username",
  password: "your_special_access_code",
  afm_called_by: "your_own_afm"
)

Returns a map with company information (onomasia, address, registration date, NACE activities, etc.) or {:error, errors} with validation/service error details.

Error shape

fetch/1 and fetch!/1 always return errors as {:error, map} with a consistent shape:

{:error, %{code: <atom | string>, descr: <string>}}

Internal errors use atoms for :code. GSIS service errors use the string code returned by the API.

Refer to the documentation on HexDocs for the full API reference.

Usage with caching

Optional caching is available via Cachex v4.x. Successful lookups are cached for a configurable TTL; errors are never cached.

Setup

1. Add cachex to your dependencies:

# mix.exs
{:cachex, "~> 4.1"}

1. Start a Cachex instance in your supervision tree:

# application.ex
children = [
  {Cachex, name: :vatchex_greece, limit: 10_000},
  ...
]

1. Pass the cache adapter to fetch/1 or fetch!/1:

VatchexGreece.fetch(
  afm_called_for: "998144460",
  username: "your_token_username",
  password: "your_special_access_code",
  afm_called_by: "your_own_afm",
  cache: VatchexGreece.CachexCache
)

Configuration

# config/config.exs
config :vatchex_greece, :cache_name, :vatchex_greece  # Cachex cache name (default: :vatchex_greece)
config :vatchex_greece, :cache_ttl, 3_600_000       # TTL in milliseconds (default: 1 hour)

Behavior

• Only successful results ({:ok, data}) are cached. Validation failures, HTTP errors, and service errors always hit the API.
• Cache keys are based on the target and source VAT IDs, not credentials.
• If Cachex is not started or not in the dependency list, the :cache option is silently ignored.
• You can provide your own cache adapter by implementing the VatchexGreece.Cache protocol.

Testing

mix test

86 unit tests, no external dependencies or live service calls. Covers VAT ID validation, XML response parsing, SOAP envelope generation, pipeline error handling, caching behavior, pretty result reshaping, address_collapsed, is_active, and VIES fallback.

What's new

v1.2.0 — is_active boolean in the response map — true when stop_date is nil, false when stop_date has a date.

v1.1.1 — address_collapsed field in the response map — single-line single-string version of the postal address.

v1.1.0 — Optional pretty: true mode, Cachex caching, VIES fallback, Req.Test adapters, truly optional Cachex, vatchex_vies from Hex, llms.txt, coverage threshold 80%.

See CHANGELOG.md for the full release history.

llms.txt

This project includes an llms.txt file at the project root — a self-contained summary of the library's API surface for AI assistants and code generation tools. See the llmstxt.org specification for details.

Support

If this library saves you time or helps your project, consider saying thanks by purchasing a copy of Northwind Elixir Traders, an exploratory-learning book that teaches Elixir, Ecto, and SQLite all in one hands-on project, with its source code released under the Apache-2.0 License.

See what readers are saying on the book's ElixirForum thread.

Documentation

The docs can be found at https://hexdocs.pm/vatchex_greece. There's also an Elixir Forum thread.