# `VatchexGreece`
[🔗](https://github.com/waseigo/vatchex_greece/blob/main/lib/vatchex_greece.ex#L4)

Client for the Greek GSIS RgWsPublic2 SOAP service (VAT / ΑΦΜ registry lookup).

## Public API

```elixir
VatchexGreece.fetch(
  afm_called_for: "the_target_afm_to_query",
  username: "your_token_username",
  password: "your_special_access_code",
  afm_called_by: "your_own_afm_or_delegator"
)
```

See `fetch/1` for authentication instructions, automatic normalization of
VAT IDs (EL/GR prefix handling, 8→9 digit padding), and the exact shape
of the returned data map.

The implementation is internal; only `fetch/1` and `fetch!/1` are the
supported public API.

# `fetch`
*since 0.8.0* 

Pull information from the web service for the target VAT ID `:afm_called_for`, by the source VAT ID `:afm_called_by`, with authentication parameters `:username` and `:password`.

To create the authentication credentials:
1. Sign up to the ["wspublicreg" service](https://www1.aade.gr/webtax/wspublicreg/faces/pages/wspublicreg/menu.xhtml) using your TAXISnet credentials.
2. Create "special access codes" through the ["Διαχείριση Ειδικών Κωδικών" application on TAXISnet](https://www1.aade.gr/sgsisapps/tokenservices/protected/displayConsole.htm).

Regarding the target and source VAT IDs, you will typically pass a valid 9-digit VAT ID, with or without the "EL" prefix. The "EL" prefix will get stripped. Older VAT IDs only have 8 digits, and will get leading-zero-padded to 9 digits.

Note: the function minimizes and checks the source and target VAT IDs, and only sends the request to the API if both minimized VAT IDs are valid.

## Caching

Pass a `:cache` option to enable caching. The value must implement the `VatchexGreece.Cache` protocol.

```elixir
VatchexGreece.fetch(
  afm_called_for: "998144460",
  username: "user",
  password: "pass",
  afm_called_by: "123456789",
  cache: VatchexGreece.CachexCache
)
```

Successful results are cached; errors are never cached. When no `:cache` option is provided, caching is disabled.

## VIES fallback

If the `fetch_vies_fallback: true` option is passed and the GSIS lookup fails,
an additional lookup against the EU VIES API is attempted (requires the
`vatchex_vies` package).

```elixir
VatchexGreece.fetch(
  afm_called_for: "998144460",
  username: "user",
  password: "pass",
  afm_called_by: "123456789",
  fetch_vies_fallback: true
)
```

When the VIES fallback succeeds, the response map includes `source: :vies`
(instead of the full GSIS data structure).

# `fetch!`
*since 0.8.0* 

Same as `VatchexGreece.fetch/1`, but the resulting tuple is unwrapped.

Returns the resulting data if successful. Raises `VatchexGreece.FetchError` if there were errors, containing the errors list in the `errors` field of the exception.

---

*Consult [api-reference.md](api-reference.md) for complete listing*