# Gusex

**Elixir client for Polish Business Registry Service (GUS BIR)**
Gusex is an Elixir library that provides access to the Polish Central
Statistical Office (GUS) BIR (Baza Internetowa Regon) service. It enables
developers to programmatically retrieve data about business entities from Polish
registries including CEIDG, KRS, and RSPO, which are synchronised into the BIR
database.

## Features

- All officially exposed BIR service methods supported
- Search businesses by REGON, NIP, or KRS identifiers
- Retrieve full business reports and aggregate data
- Elixir structs for many data types
- Support for both test and production environments
- Uses the required SOAP 1.2 protocol with handcrafted MTOM support
- Extensive error handling and validation

## Installation

If [available in Hex](https://hex.pm/docs/publish), the package can be installed
by adding `gusex` to your list of dependencies in `mix.exs`:

```elixir
def deps do
	[
		{:gusex, "~> 1.0"}
	]
end
```

Then run:
```bash
mix deps.get
```

## Configuration

```elixir
config :gusex,
	api_key: "your_production_api_key",
	environment: :production  # or :test
```

For testing, you can use the test environment:

```elixir
config :gusex,
	api_key: "abcde12345abcde12345",  # Test API key
	environment: :test
```

although it is default if not specified and in dev or test environment.

## Quick Start

```elixir
# Login to the service and obtain a session (uses test environment by default; configure with valid API key for production environment)
{:ok, session} = Gusex.zaloguj()

# Search for entities by REGON (using ParametryWyszukiwania struct)
search_params = %Gusex.Types.ParametryWyszukiwania{Regon: "000331501"}
{:ok, entities} = Gusex.dane_szukaj_podmioty(search_params, session)
# or (using simple map with atom keys - error will be returned for invalid or non-atom keys)
{:ok, entities} = Gusex.dane_szukaj_podmioty(%{Regon: "000331501"}, session)

# Get detailed report for an entity
{:ok, report} = Gusex.dane_pobierz_pelny_raport("000331501", "BIR12OsPrawna", session)

# Logout
{:ok, true} = Gusex.wyloguj(session)
```

## API Reference

### Authentication

#### `zaloguj/2`

Authenticates with the BIR service and establishes a session.

```elixir
# Using configured or default (for GUS test environment) credentials
{:ok, session} = Gusex.zaloguj()

# Using explicit credentials and environment (you shouldn't do this in production code)
{:ok, session} = Gusex.zaloguj("your_api_key", :production)
```

**Returns:** `{:ok, %Gusex.Types.Session{}}` or `{:error, reason}`

### Entity Search

#### `dane_szukaj_podmioty/2`

Searches for business entities using various identifier types.

```elixir
# Search by REGON (9 or 14 digits)
search_params = %Gusex.Types.ParametryWyszukiwania{Regon: "000331501"}
{:ok, entities} = Gusex.dane_szukaj_podmioty(search_params, session)

# Search by NIP (Tax ID)
search_params = %Gusex.Types.ParametryWyszukiwania{Nip: "5260001246"}
{:ok, entities} = Gusex.dane_szukaj_podmioty(search_params, session)

# Search by KRS (Court Register number)
search_params = %Gusex.Types.ParametryWyszukiwania{Krs: "0000028860"}
{:ok, entities} = Gusex.dane_szukaj_podmioty(search_params, session)

# Multiple search (up to 20 entities)
search_params = %Gusex.Types.ParametryWyszukiwania{
	Regony9zn: "000331501,123456789",
	Nipy: "5260001246,1234567890"
}
{:ok, entities} = Gusex.dane_szukaj_podmioty(search_params, session)
```

**Returns:** `{:ok, [%Gusex.Types.Podmiot{}]}` or `{:error, error_data}`

### Detailed Reports

#### `dane_pobierz_pelny_raport/3`

Retrieves detailed information about a specific entity.

```elixir
# Legal entities (companies)
{:ok, company_data} = Gusex.dane_pobierz_pelny_raport("000331501", "BIR12OsPrawna", session)

# Natural persons - general data
{:ok, person_data} = Gusex.dane_pobierz_pelny_raport("12345678901234", "BIR12OsFizycznaDaneOgolne", session)

# Natural persons - CEIDG business activity
{:ok, ceidg_data} = Gusex.dane_pobierz_pelny_raport("12345678901234", "BIR12OsFizycznaDzialalnoscCeidg", session)

# Local units of legal entities
{:ok, local_unit} = Gusex.dane_pobierz_pelny_raport("12345678901234", "BIR12JednLokalnaOsPrawnej", session)
```

**Available Report Types:**

- `BIR12JednLokalnaOsFizycznej`
- `BIR12JednLokalnaOsFizycznejPkd`
- `BIR12JednLokalnaOsPrawnej`
- `BIR12JednLokalnaOsPrawnejPkd`
- `BIR12OsFizycznaDaneOgolne`
- `BIR12OsFizycznaDzialalnoscCeidg`
- `BIR12OsFizycznaDzialalnoscPozostala`
- `BIR12OsFizycznaDzialalnoscRolnicza`
- `BIR12OsFizycznaDzialalnoscSkreslonaDo20141108`
- `BIR12OsFizycznaListaJednLokalnych`
- `BIR12OsFizycznaPkd`
- `BIR12OsPrawna`
- `BIR12OsPrawnaListaJednLokalnych`
- `BIR12OsPrawnaPkd`
- `BIR12OsPrawnaSpCywilnaWspolnicy`
- `BIR12TypPodmiotu`

### Aggregate Reports

#### `dane_pobierz_raport_zbiorczy/3`
Retrieves aggregate reports with lists of entities modified on a specific date.

```elixir
# New legal entities and individual business activities
{:ok, new_entities} = Gusex.dane_pobierz_raport_zbiorczy(
	"2014-01-15",
	"BIR11NowePodmiotyPrawneOrazDzialalnosciOsFizycznych",
	session
)
```

**Available Aggregate Reports:**

- `BIR11AktualizowaneJednostkiLokalne`
- `BIR11AktualizowanePodmiotyPrawneOrazDzialalnosciOsFizycznych`
- `BIR11NoweJednostkiLokalne`
- `BIR11NowePodmiotyPrawneOrazDzialalnosciOsFizycznych`
- `BIR11SkresloneJednostkiLokalne`
- `BIR11SkreslonePodmiotyPrawneOrazDzialalnosciOsFizycznych`

### Service Information

#### `get_value/2`

Retrieves service diagnostic information.

```elixir
# Get service status message (no session required)
{:ok, service_message} = Gusex.get_value("KomunikatUslugi")

# Get session status (requires active session)
{:ok, session_status} = Gusex.get_value("StatusSesji", session)
```

#### `wyloguj/1`

Terminates the active session.

```elixir
{:ok, true} = Gusex.wyloguj(session)
```

## Data Types and Structures

### Core Types

```elixir
# Session information
%Gusex.Types.Session{
	id: "abcdef1234567890abcd",
	environment: :test,
	endpoint_url: "https://wyszukiwarkaregontest.stat.gov.pl/wsBIR/UslugaBIRzewnPubl.svc"
}

# Search parameters
%Gusex.Types.ParametryWyszukiwania{
	Regon: "000331501",
	Nip: nil,
	Krs: nil,
	Regony9zn: nil,
	Regony14zn: nil,
	Nipy: nil,
	Krsy: nil
}

# Entity information
%Gusex.Types.Podmiot{
	Regon: "000331501",
	Nip: "5260001246",
	StatusNip: "",
	Nazwa: "GŁÓWNY URZĄD STATYSTYCZNY",
	Typ: "P",  # P = Legal entity, F = Natural person
	SilosID: "6"
}
```

### Entity Types

- **`P`** - Legal entity (Osoba prawna)
- **`F`** - Natural person conducting business activity
- **`LP`** - Local unit of legal entity
- **`LF`** - Local unit of natural person

### Activity Types (SilosID)

- **`1`** - CEIDG registered activity
- **`2`** - Agricultural activity
- **`3`** - Other business activity
- **`4`** - Activity deleted before 2014-11-08
- **`6`** - Legal entity activity

## Environment Setup

### Test Environment
- **Endpoint**: `https://wyszukiwarkaregontest.stat.gov.pl/wsBIR/UslugaBIRzewnPubl.svc`
- **WSDL**: `https://wyszukiwarkaregontest.stat.gov.pl/wsBIR/wsdl/UslugaBIRzewnPubl-ver11-test.wsdl`
- **API Key**: `abcde12345abcde12345` (public test key)
- **Data**: Partially anonymised data from November 8, 2014

### Production Environment

- **Registration**: Email `regon_bir@stat.gov.pl` with:

- Organisation name and REGON/NIP
- Contact person details
- Phone numbers
- Expected concurrent users
- IP addresses (if applicable)

- **Endpoint**: `https://wyszukiwarkaregon.stat.gov.pl/wsBIR/UslugaBIRzewnPubl.svc`

## Error Handling

The library provides comprehensive error handling for various scenarios:

```elixir
case Gusex.zaloguj("api_key", :production) do
	{:ok, session} ->
		# Success
		session
	{:error, :api_key_missing} ->
		# No API key provided or configured
		handle_missing_key()
	{:error, :login_failure} ->
		# Invalid credentials or service unavailable
		handle_login_failure()
	{:error, reason} ->
		# Other errors (network, parsing, etc.)
		handle_error(reason)
end
```

## Technical Notes

### Session Management

- Sessions automatically expire after 60 minutes
- Daily maintenance at 3:20 AM closes all active sessions

### Data Security

- Returned data may contain executable code (HTML/JavaScript/SQL)
- Always sanitise and validate data before displaying or storing
- Implement proper input filtering to prevent XSS/SQL injection

### Rate Limiting

- No automatic sequential ID scanning allowed
- Respect service limits and usage guidelines
- Maximum 20 entities per bulk search request

## Dependencies

- **httpoison** - HTTP client for SOAP requests
- **sweet_xml** - XML parsing and manipulation
- **exvcr** - HTTP request recording for tests (test only)
- **credo** - Static code analysis (dev/test only)
- **mock** - Mocking support for tests (test only)

## Documentation

Documentation can be generated with [ExDoc](https://github.com/elixir-lang/ex_doc)
and published on [HexDocs](https://hexdocs.pm). Once published, the docs can
be found at <https://hexdocs.pm/gusex>.

## Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes following the existing code style (do NOT run `mix format`)
4. Add tests for new functionality
5. Run tests and ensure they pass (`mix test`)
6. Run static analysis (`mix credo`)
7. Commit your changes
8. Push to the branch
9. Open a Pull Request

## License

This project is licensed under the MIT License - see the LICENCE file for details.

## Support

For issues, questions, or contributions, please visit the [BitBucket repository](https://bitbucket.org/silverdr/gusex/).

---

**Note**: This library provides access to official Polish government business registry data. Ensure compliance with applicable data protection regulations and service terms of use.