Gusex

Copy Markdown View Source

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
  • Optional session cache with TTL and transparent retry on expiry, plus a convenience lookup API on top of it

Installation

Gusex requires Elixir 1.18 or later and Erlang/OTP 27 or later.

If available in Hex, the package can be installed by adding gusex to your list of dependencies in mix.exs:

def deps do
	[
		{:gusex, "~> 1.3"}
	]
end

Then run:

mix deps.get

Configuration

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

For testing, you can use the test environment:

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

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

Optional: session cache

The convenience API (see Convenience Lookups) relies on Gusex.SessionCache, a GenServer-backed cache that holds authenticated sessions and reuses them across calls. It is opt-in — add it to your application's supervision tree:

defmodule MyApp.Application do
	use Application

	def start(_type, _args) do
		children = [
			Gusex.SessionCache,
			# ... other children
		]

		Supervisor.start_link(children, strategy: :one_for_one)
	end
end

The cache reads credentials from the same :gusex application config and accepts one tunable — :session_ttl in seconds, default 3000 (50 minutes, a safe margin below the service's 60-minute hard session limit):

config :gusex,
	api_key: "your_production_api_key",
	environment: :production,
	session_ttl: 3000

The low-level API (zaloguj/2, dane_szukaj_podmioty/2, etc.) does not require the cache and can be used directly with manually managed sessions.

Quick Start

Convenience API (requires Gusex.SessionCache in the supervision tree)

# One-shot lookup by NIP - session is obtained from the cache, validated,
# and transparently refreshed if the server has invalidated it.
{:ok, entities} = Gusex.find_by_nip("5261040828")

Low-level API (manual session management)

# 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.

# 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}

dane_szukaj_podmioty/2

Searches for business entities using various identifier types.

# 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.

# 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
  • BIR121JednLokalnaOsPrawnej (extends BIR12JednLokalnaOsPrawnej with NIP and NIP status fields)
  • BIR12JednLokalnaOsPrawnejPkd
  • BIR12OsFizycznaDaneOgolne
  • BIR12OsFizycznaDzialalnoscCeidg
  • BIR12OsFizycznaDzialalnoscPozostala
  • BIR12OsFizycznaDzialalnoscRolnicza
  • BIR12OsFizycznaDzialalnoscSkreslonaDo20141108
  • BIR12OsFizycznaListaJednLokalnych
  • BIR12OsFizycznaPkd
  • BIR12OsPrawna
  • BIR12OsPrawnaListaJednLokalnych
  • BIR12OsPrawnaPkd
  • BIR12OsPrawnaSpCywilnaWspolnicy

Aggregate Reports

dane_pobierz_raport_zbiorczy/3

Retrieves aggregate reports with lists of entities modified on a specific date.

# 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.

# 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.

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

Convenience Lookups

Higher-level helpers that obtain, cache, and refresh sessions automatically. They require Gusex.SessionCache in the application's supervision tree — see Optional: session cache for setup.

find_by_nip/1

Finds a business entity by NIP using a cached session. Validates and normalises the input (accepts common separators such as spaces and hyphens), obtains a session from the cache (logging in if needed), and transparently retries once if the call returns a retriable failure (:empty_response or an HTTP-level error).

# Clean 10-digit NIP
{:ok, entities} = Gusex.find_by_nip("5261040828")

# Separators are tolerated
{:ok, entities} = Gusex.find_by_nip("526-10-40-828")

Returns:

  • {:ok, [%Gusex.Types.Podmiot{}]} - List of matching entities (typically one)
  • {:error, :invalid_nip} - Input failed NIP checksum or format validation
  • {:error, :session_cache_not_started} - Gusex.SessionCache is not in the supervision tree
  • {:error, reason} - Login, search, or other failure

Gusex.SessionCache.run_with_session/1

Runs an arbitrary one-argument function with a cached session, handling acquisition, TTL expiry, and a single retry on retriable errors. Use this as a building block for additional cached-session operations beyond find_by_nip/1:

Gusex.SessionCache.run_with_session(fn session ->
	Gusex.dane_pobierz_pelny_raport("000331501", "BIR12OsPrawna", session)
end)

Retriable errors (one automatic retry with a fresh login):

  • :empty_response - The empirical signal that the server has killed the session (GUS returns HTTP 200 with an empty body in that case)
  • {:http_error, _, _} - Possibly transient, possibly session-related

All other errors are returned unchanged.

Data Types and Structures

Core Types

# 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:

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
  • When using Gusex.SessionCache, both cases are handled transparently: the TTL defaults to 50 minutes (a safe margin below the server's 60-minute hard limit), and run_with_session/1 evicts the stale entry and re-authenticates on the next call when the server has invalidated a session mid-TTL (signalled by an empty response)

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

Upgrading from 1.1.x

Version 1.2 tightens the success return contract of dane_pobierz_pelny_raport/3: it now returns {:ok, [struct()]} instead of {:ok, [map()]}. The struct type depends on report_name (e.g. "BIR12OsPrawna" -> %Gusex.Types.OsPrawna{}). Code that matched raw maps with a non-struct guard (e.g. when not is_struct(entry)) must be updated.

See CHANGELOG for the full list including the new BIR121JednLokalnaOsPrawnej report support.

Dependencies

  • hackney - 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 and published on HexDocs. 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.

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