Gusex (gusex v1.3.0)

Copy Markdown View Source

Elixir client for Polish GUS BIR (Baza Internetowa Regon) service.

Gusex enables searching and retrieving business entity data from Polish registries including CEIDG, KRS, and RSPO, which are synchronised into the BIR database.

Installation

Add gusex to your list of dependencies in mix.exs:

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

Configuration

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

For testing, the default test environment and key are used automatically.

Session cache (optional)

The convenience API (e.g. find_by_nip/1) relies on Gusex.SessionCache, a GenServer-backed ETS cache that holds authenticated sessions and reuses them across calls, avoiding redundant logins against the BIR service.

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 (:api_key, :environment) and exposes a single tunable:

config :gusex,
  session_ttl: 3000  # seconds; default 3000 (50 min, below the 60 min hard limit)

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

# Low-level API with manual session management
{:ok, session} = Gusex.zaloguj()
{:ok, entities} = Gusex.dane_szukaj_podmioty(%{Nip: "5260001246"}, session)
{:ok, report}   = Gusex.dane_pobierz_pelny_raport("000331501", "BIR12OsPrawna", session)
{:ok, true}     = Gusex.wyloguj(session)

# Convenience API (requires Gusex.SessionCache in the supervision tree)
{:ok, entities} = Gusex.find_by_nip("5261040828")

Main Functions

Both Polish (original API names) and English function names are provided.

Summary

Functions

dane_pobierz_pelny_raport(regon, report_name, session)

Retrieves a full report for a specific entity identified by REGON.

dane_pobierz_raport_zbiorczy(report_date, report_name, session)

Retrieves an aggregate report for a specific date.

dane_szukaj_podmioty(search_params, session)

Searches for entities in the BIR registry based on provided search parameters.

find_by_nip(nip)

Finds a business entity by NIP using a cached session.

get_aggregate_report(report_date, report_name, session)

Alias for dane_pobierz_raport_zbiorczy/3. Retrieves an aggregate report for a specific date.

get_full_report(regon, report_name, session)

Alias for dane_pobierz_pelny_raport/3. Retrieves a full report for a specific entity.

get_value(param_name, session \\ nil)

Retrieves a system parameter value from the BIR service.

login(user_key \\ nil, environment \\ nil)

Alias for zaloguj/2. Logs in to the BIR (Business Information Registry) service.

logout(session)

Alias for wyloguj/1. Logs out from the BIR service.

search_entities(search_params, session)

Alias for dane_szukaj_podmioty/2. Searches for entities in the BIR registry.

wyloguj(session)

Logs out from the BIR service and terminates the session.

zaloguj(user_key \\ nil, environment \\ nil)

Logs in to the BIR (Business Information Registry) service.

Functions

dane_pobierz_pelny_raport(regon, report_name, session)

Retrieves a full report for a specific entity identified by REGON.

This function fetches various, detailed information sets about a business entity from the BIR registry using its REGON number.

Parameters

  • regon - The REGON number of the entity (9 or 14 digits)
  • report_name - The type of report to retrieve. Common types include:
    • "BIR12OsPrawna" - Legal entity data
    • "BIR12OsFizycznaDaneOgolne" - Natural person general data
    • "BIR12OsFizycznaDzialalnoscCeidg" - Natural person CEIDG activity
    • "BIR12OsPrawnaListaJednLokalnych" - Legal entity's local units list
    • And many others (see BIR documentation for full list)
  • session - A valid Session struct obtained from zaloguj/2

Returns

  • {:ok, [struct()]} - List of typed report entries. The struct type depends on report_name (e.g. "BIR12OsPrawna" -> Gusex.Types.OsPrawna).
  • {:error, map()} - Raw error map from the BIR service

Examples

  {:ok, session} = Gusex.zaloguj()

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

  # Get natural person general data
  {:ok, report} = Gusex.dane_pobierz_pelny_raport("123456789", "BIR12OsFizycznaDaneOgolne", session)

dane_pobierz_raport_zbiorczy(report_date, report_name, session)

Retrieves an aggregate report for a specific date.

This function fetches collective/aggregate reports from the BIR registry that contain information about multiple entities that changed on a specific date (new, updated, or deleted).

Parameters

  • report_date - The date for the report in "YYYY-MM-DD" format
  • report_name - The type of aggregate report to retrieve. Types include:
    • "BIR11NoweJednostkiLokalne" - New local units
    • "BIR11NowePodmiotyPrawneOrazDzialalnosciOsFizycznych" - New legal entities and natural person activities
    • "BIR11AktualizowaneJednostkiLokalne" - Updated local units
    • "BIR11AktualizowanePodmiotyPrawneOrazDzialalnosciOsFizycznych" - Updated legal entities and natural person activities
    • "BIR11SkresloneJednostkiLokalne" - Deleted local units
    • "BIR11SkreslonePodmiotyPrawneOrazDzialalnosciOsFizycznych" - Deleted legal entities and natural person activities
  • session - A valid Session struct obtained from zaloguj/2

Returns

  • {:ok, [struct()]} - List of typed aggregate entries. The struct type depends on report_name (e.g. "BIR11NoweJednostkiLokalne" -> Gusex.Types.NoweJednostkiLokalne).
  • {:error, map()} - Raw error map from the BIR service

Examples

  {:ok, session} = Gusex.zaloguj()

  # Get new entities for a specific date
  {:ok, report} = Gusex.dane_pobierz_raport_zbiorczy("2024-01-15", "BIR11NowePodmiotyPrawneOrazDzialalnosciOsFizycznych", session)

  # Get deleted local units for a specific date
  {:ok, report} = Gusex.dane_pobierz_raport_zbiorczy("2024-01-15", "BIR11SkresloneJednostkiLokalne", session)

dane_szukaj_podmioty(search_params, session)

Searches for entities in the BIR registry based on provided search parameters.

This function allows searching for business entities in the Polish business registry using various identifiers like NIP, REGON, or KRS numbers.

Parameters

  • search_params - Search criteria as either a ParametryWyszukiwania struct or a map. At least one search key must be provided. If multiple keys are provided, only the first one (in the alphabetic order) will be used for the search. Available keys:
    • :Krs - Single 10-digit Court Register number
    • :Krsy - String of 10-digit KRS identifiers, separated by any non-digit separator or without separators, max 20 identifiers
    • :Nip - Single 10-digit Tax Identification Number
    • :Nipy - String of 10-digit NIP identifiers, separated by any non-digit separator or without separators, max 20 identifiers
    • :Regon - Single REGON number (9 or 14 digits)
    • :Regony14zn - String of 14-digit REGON identifiers, separated by any non-digit separator or without separators, max 20 identifiers
    • :Regony9zn - String of 9-digit REGON identifiers, separated by any non-digit separator or without separators, max 20 identifiers
  • session - A valid Session struct obtained from zaloguj/2

Returns

  • {:ok, [Podmiot.t()]} - List of found entities
  • {:error, map()} - Raw error map from the BIR service (e.g. %{ErrorCode: "4", ...})
  • {:error, {:invalid_search_params, String.t()}} - Invalid map keys provided

Examples

  # Search by single NIP
  {:ok, session} = Gusex.zaloguj()
  search_params = %{Nip: "5261040828"}
  {:ok, entities} = Gusex.dane_szukaj_podmioty(search_params, session)

  # Search by multiple REGONs
  search_params = %{Regony9zn: "000331501 016128070"}
  {:ok, entities} = Gusex.dane_szukaj_podmioty(search_params, session)

find_by_nip(nip)

@spec find_by_nip(String.t()) :: {:ok, [Gusex.Types.Podmiot.t()]} | {:error, term()}

Finds a business entity by NIP using a cached session.

This is a convenience function that handles session management automatically via Gusex.SessionCache. It obtains a cached session (or logs in if needed), performs the search, and transparently retries once if the call fails with a retriable error (an empty response or an HTTP-level failure).

Requires Gusex.SessionCache to be running in the supervision tree.

Parameters

  • nip - A 10-digit Polish Tax Identification Number (NIP) as a string

Returns

  • {:ok, [%Gusex.Types.Podmiot{}]} - List of matching entities (typically one)
  • {:error, :invalid_nip} - The provided NIP failed validation
  • {:error, reason} - Search failed, session could not be obtained, or cache not running

Examples

{:ok, entities} = Gusex.find_by_nip("5261040828")

get_aggregate_report(report_date, report_name, session)

Alias for dane_pobierz_raport_zbiorczy/3. Retrieves an aggregate report for a specific date.

See dane_pobierz_raport_zbiorczy/3 for full documentation.

get_full_report(regon, report_name, session)

Alias for dane_pobierz_pelny_raport/3. Retrieves a full report for a specific entity.

See dane_pobierz_pelny_raport/3 for full documentation.

get_value(param_name, session \\ nil)

Retrieves a system parameter value from the BIR service.

This function allows querying various system parameters and service status information from the BIR registry. Some parameters can be retrieved without authentication.

Parameters

  • param_name - The name of the parameter to retrieve. Common parameters:
    • "KomunikatUslugi" - Service message (can be retrieved without session)
    • "StatusSesji" - Session status
    • "KomunikatKod" - Message code
    • "KomunikatTresc" - Message content
    • "StanDanych" - Data state
  • session - A valid Session struct or nil for parameters that don't require authentication (currently only "KomunikatUslugi")

Returns

  • {:ok, String.t()} - The parameter value
  • {:error, any()} - Error details if retrieval fails

Examples

  # Get service message without authentication
  {:ok, message} = Gusex.get_value("KomunikatUslugi")

  # Get session status with authentication
  {:ok, session} = Gusex.zaloguj()
  {:ok, status} = Gusex.get_value("StatusSesji", session)

login(user_key \\ nil, environment \\ nil)

Alias for zaloguj/2. Logs in to the BIR (Business Information Registry) service.

See zaloguj/2 for full documentation.

logout(session)

Alias for wyloguj/1. Logs out from the BIR service.

See wyloguj/1 for full documentation.

search_entities(search_params, session)

Alias for dane_szukaj_podmioty/2. Searches for entities in the BIR registry.

See dane_szukaj_podmioty/2 for full documentation.

wyloguj(session)

Logs out from the BIR service and terminates the session.

This function ends the authenticated session with the BIR registry service, freeing up resources on the server side.

Parameters

  • session - A valid Session struct obtained from zaloguj/2

Returns

  • {:ok, true} - Logout was successful
  • {:ok, false} - Logout was unsuccessful (but no error occurred)
  • {:error, :invalid_session} - Invalid session provided
  • {:error, reason} - Other logout failures

Examples

  {:ok, session} = Gusex.zaloguj()

  # Do some operations...

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

zaloguj(user_key \\ nil, environment \\ nil)

Logs in to the BIR (Business Information Registry) service.

This function authenticates with the Polish GUS BIR service using the provided credentials. If parameters are not provided, they will be read from the application configuration.

Parameters

  • user_key - The API key for authentication (optional). If not provided, reads from :gusex, :api_key config.
  • environment - The environment to connect to (optional). Can be :test or :production. If not provided, reads from :gusex, :environment config, defaults to :test.

Returns

  • {:ok, session} - A Session struct containing the session ID, environment, and endpoint URL
  • {:error, :api_key_missing} - When no API key is provided or configured
  • {:error, :login_failure} - When authentication fails
  • {:error, reason} - Other errors with specific reason

Examples

  # Using explicit parameters
  {:ok, session} = Gusex.zaloguj("your_api_key", :production)

  # Using test environment with test key
  {:ok, session} = Gusex.zaloguj("abcde12345abcde12345", :test)

  # Using application configuration
  # In config/config.exs:
  # config :gusex,
  #   api_key: "your_api_key",
  #   environment: :production

  {:ok, session} = Gusex.zaloguj()