Open Source
VatchexGreece is the authority for Greek VAT numbers, and it is also a single point of failure. When GSIS has a bad afternoon, a checkout page that only knows how to ask GSIS stops working.
VIES is the European Commission’s check. It answers a narrower question — is this number valid, and for most countries, what is the registered name and address — and covers the whole EU with less detail. For a cross-border invoice, that narrower question is the one the law asks.
This is the client for it, and the fallback for the Greek one.
Using the pair
- Greek customer: VatchexGreece. Full local record, activity codes, cessation date.
- Anywhere else in the EU: VatchexVies.
- GSIS unavailable: VatchexGreece delegates to VatchexVies instead of failing the page.
Cache both, with different TTLs. A VAT number does not change between two page loads, and neither service enjoys being asked the same question in a loop. VIES caching defaults to a day, which is about as long as a registration office takes to update anything.
The response, and why the codes matter
lookup/3 returns {:ok, map} with country_code, afm, onomasia, commer_title, the raw
address, an address_collapsed for single-line display, and source: :vies.
Failures return {:error, %{code, descr}}, and the code is the useful part:
| code | what happened |
|---|---|
:invalid_vat |
the number failed validation, or was blank (no API call made) |
:vies_http_error |
VIES returned a non-2xx response |
:vies_too_many_requests |
HTTP 429: back off, do not retry immediately |
:vies_request_failed |
transport failure: DNS, timeout, connection refused |
:vies_status_unavailable |
the status endpoint itself could not be reached |
That distinction is the difference between “fix your data” and “back off and retry”. Getting it wrong means either retrying a number that will never be valid, or telling a customer their company does not exist because a server was busy.
Cachex caching is optional and not a hard dependency: if you do not start it, the option is ignored. Errors are never cached.
Installation
def deps do
[
{:vatchex_vies, "~> 1.0"}
]
end
Documentation on HexDocs, code on GitHub.
A volunteer effort, not affiliated with the European Commission or the VIES service.
