Module: Ksef::Environments

Defined in:
lib/ksef/environments.rb

Overview

The three public KSeF API 2.0 environments.

Every base URL here was read from that environment's own OpenAPI document (servers[0].url, served at https://<host>/docs/v2/openapi.json) on 2026-08-21, rather than inferred by analogy. See docs/REFERENCE.md §2. Do not edit a URL without re-verifying it against that source and updating the ledger.

Note the base URL already carries /v2; endpoint paths are appended bare. There is no /api segment (docs/REFERENCE.md §7.2).

Defined Under Namespace

Classes: Environment

Constant Summary collapse

TEST = 
Environment.new(
  name: :test,
  base_url: "https://api-test.ksef.mf.gov.pl/v2",
  supports_test_data: true
)
DEMO = 
Environment.new(
  name: :demo,
  base_url: "https://api-demo.ksef.mf.gov.pl/v2",
  supports_test_data: false
)
PROD = 
Environment.new(
  name: :prod,
  base_url: "https://api.ksef.mf.gov.pl/v2",
  supports_test_data: false
)
ALL = 
{ test: TEST, demo: DEMO, prod: PROD }.freeze
NAMES = 
ALL.keys.freeze

Class Method Summary collapse

Class Method Details

.custom(base_url:, name: :custom, supports_test_data: false) ⇒ Environment

Escape hatch for deployments not covered by the three published environments (DESIGN.md §6.1).

Parameters:

  • base_url (String) —

    must be HTTPS, and should include the /v2 suffix

Returns:



65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
 
# File 'lib/ksef/environments.rb', line 65

def custom(base_url:, name: :custom, supports_test_data: false)
  uri = begin
    URI.parse(base_url)
  rescue URI::InvalidURIError => e
    raise ConfigurationError, "Invalid base_url #{base_url.inspect}: #{e.message}"
  end

  unless uri.is_a?(URI::HTTPS)
    raise ConfigurationError,
          "base_url must be HTTPS, got #{base_url.inspect}. TLS is not optional (DESIGN.md §4.5)."
  end

  Environment.new(
    name: name.to_sym,
    base_url: base_url.chomp("/"),
    supports_test_data: supports_test_data
  )
end

.fetch(env) ⇒ Environment

Parameters:

Returns:

Raises:



49
50
51
52
53
54
55
56
57
58
 
# File 'lib/ksef/environments.rb', line 49

def fetch(env)
  return env if env.is_a?(Environment)

  key = env.respond_to?(:to_sym) ? env.to_sym : nil
  ALL.fetch(key) do
    raise ConfigurationError,
          "Unknown KSeF environment #{env.inspect}. Known: #{NAMES.map(&:inspect).join(", ")}. " \
          "For a non-public deployment, pass Ksef::Environments.custom(base_url: ...)."
  end
end