Class: Ksef::Invoices

Inherits:
Object
  • Object
show all
Defined in:
lib/ksef/invoices.rb

Overview

Inbound-invoice retrieval. All operations require an open session (see Sessions#with_interactive).

Constant Summary collapse

SUBJECT_TYPE_MAP = 
{
  issuer:             "Subject1",
  seller:             "Subject1",
  recipient:          "Subject2",
  buyer:              "Subject2",
  third:              "Subject3",
  subject_authorized: "SubjectAuthorized"
}.freeze
DATE_TYPE_MAP = 
{
  issue:             "Issue",
  invoicing:         "Invoicing",
  permanent_storage: "PermanentStorage"
}.freeze
DEFAULT_PAGE_SIZE = 
100

Instance Method Summary collapse

Constructor Details

#initialize(client) ⇒ Invoices

Returns a new instance of Invoices.



24
25
26
 
# File 'lib/ksef/invoices.rb', line 24

def initialize(client)
  @client = client
end

Instance Method Details

#fetch_upo(_ksef_reference_number) ⇒ Object

Note:

Not implemented in v0.1.0.

UPO (Urzędowe Poświadczenie Odbioru) downloads are scoped to the sender sessions that produced them (see ‘GET /sessions/ref/upo/…`). Recipient-side UPO retrieval is not available in v0.1.0; outbound issuance is also stubbed.

Raises:

  • (NotImplementedError) 


101
102
103
104
105
 
# File 'lib/ksef/invoices.rb', line 101

def fetch_upo(_ksef_reference_number)
  raise NotImplementedError,
        "UPO download is not implemented in ksef-rb v#{Ksef::VERSION}. " \
        "Tracked alongside outbound invoice issuance."
end

#fetch_visualisation(_ksef_reference_number) ⇒ Object

Note:

Not implemented in v0.1.0.

KSeF 2.0 does not currently expose a server-rendered PDF/HTML visualisation of an invoice through the public API. The visualisation is produced client-side from the FA(3) XML using the official XSLT (‘wizualizacja-faktury_v3-0.xsl`) shipped with the ksef-docs repo, or by combining the XML with a PDF rendering library (e.g. WeasyPrint, Puppeteer + the official HTML preview).

Parameters:

  • _ksef_reference_number (String)

Raises:

  • (NotImplementedError) 


86
87
88
89
90
91
92
93
 
# File 'lib/ksef/invoices.rb', line 86

def fetch_visualisation(_ksef_reference_number)
  raise NotImplementedError, <<~MSG
    KSeF 2.0 has no public endpoint that returns a PDF visualisation of an
    invoice. Generate it client-side from the XML retrieved via #fetch_xml
    using the official XSLT (wizualizacja-faktury_v3-0.xsl) and your
    preferred renderer. Tracked for a future ksef-rb release.
  MSG
end

#fetch_xml(ksef_reference_number) ⇒ String

Fetches the raw FA(3) XML for the invoice identified by ‘ksef_reference_number`.

Returns:

  • (String) —

    XML document bytes

Raises:

  • (ArgumentError) 


64
65
66
67
68
69
70
71
72
73
74
 
# File 'lib/ksef/invoices.rb', line 64

def fetch_xml(ksef_reference_number)
  raise ArgumentError, "ksef_reference_number cannot be blank" if blank?(ksef_reference_number)

  response = require_session.connection.request(
    :get,
    "/invoices/ksef/#{ksef_reference_number}",
    headers:      { "Accept" => "application/xml" },
    bearer_token: current_access_token
  )
  response.body.to_s
end

#query(subject_type: :recipient, date_from:, date_to: nil, date_type: :permanent_storage, page_size: DEFAULT_PAGE_SIZE, page_offset: 0, sort_order: "Asc", extra_filters: {}) ⇒ Array<Ksef::InvoiceHeader>

Queries invoice metadata.

Parameters:

  • subject_type (Symbol) (defaults to: :recipient) —

    :recipient (default), :issuer, :third, :subject_authorized

  • date_from (Time, DateTime, String) —

    start of date range (inclusive)

  • date_to (Time, DateTime, String, nil) (defaults to: nil) —

    end of date range, defaults to “now”

  • date_type (Symbol) (defaults to: :permanent_storage) —

    :permanent_storage (default), :invoicing, :issue

  • page_size (Integer) (defaults to: DEFAULT_PAGE_SIZE) —

    10..250

  • page_offset (Integer) (defaults to: 0)
  • sort_order (String) (defaults to: "Asc") —

    “Asc” (default) or “Desc”

  • extra_filters (Hash) (defaults to: {}) —

    additional InvoiceQueryFilters fields, passed through verbatim

Returns:



39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
 
# File 'lib/ksef/invoices.rb', line 39

def query(subject_type: :recipient, date_from:, date_to: nil, date_type: :permanent_storage,
          page_size: DEFAULT_PAGE_SIZE, page_offset: 0, sort_order: "Asc", extra_filters: {})
  filters = {
    "subjectType" => translate_subject(subject_type),
    "dateRange"   => {
      "dateType" => translate_date_type(date_type),
      "from"     => to_iso8601(date_from)
    }
  }
  filters["dateRange"]["to"] = to_iso8601(date_to) if date_to
  filters.merge!(stringify_keys(extra_filters))

  response = require_session.connection.request(
    :post,
    "/invoices/query/metadata",
    body:         filters,
    query:        { "pageOffset" => page_offset, "pageSize" => page_size, "sortOrder" => sort_order },
    bearer_token: current_access_token
  )
  body = Internal::Connection.parse_json(response)
  Array(body["invoices"]).map { |raw| InvoiceHeader.new(raw) }
end