Class: Ksef::Client::Session

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

Overview

The handle #session yields — one open session, for sending several invoices through deliberately.

Why batching is opt-in rather than the default

Ksef::Client#send_invoice opens a fresh session per call (docs/REFERENCE.md §11.2a, decided 2026-08-23). That is the safe default, not the efficient one: a session lives twelve hours and takes ten thousand invoices, so opening one per invoice spends POST /sessions/online's budget of 30/min where a batch would spend one.

So this exists for anyone sending more than a handful — and it is a block, not a returned object, because the session must be closed. Closing is what triggers generation of the collective UPO (§11); a session merely abandoned closes itself at validUntil up to twelve hours later, and the proof of receipt waits that long with it.

client.session do |batch|
  invoices.each { |invoice| batch.send_invoice(invoice) }
end   # ← closed here, whatever happened inside

The whole session shares one symmetric key, which is exactly why Sessions::Online binds the encryptor to the session rather than taking one per send.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(client, opened) ⇒ Session

Returns a new instance of Session.



30
31
32
33
34
 
# File 'lib/ksef/client/session.rb', line 30

def initialize(client, opened)
  @client = client
  @opened = opened
  @receipts = []
end

Instance Attribute Details

#opened ⇒ Ksef::Sessions::Online::Session (readonly)

Returns the open session, key and all.

Returns:



28
29
30
 
# File 'lib/ksef/client/session.rb', line 28

def opened
  @opened
end

Instance Method Details

#receipts ⇒ Array<Receipt>

Every receipt from this session, in the order they were submitted.

Worth keeping: after Ksef::Client#session returns, the collective UPO covers exactly these invoices, and a caller that discarded the receipts has no way to ask about any of them individually.

Returns:



61
 
# File 'lib/ksef/client/session.rb', line 61

def receipts = @receipts.dup

#reference_number ⇒ Object 



63
 
# File 'lib/ksef/client/session.rb', line 63

def reference_number = @opened.reference_number

#send_invoice(invoice, validate: true) ⇒ Receipt

Validates, encrypts and submits one invoice into this session.

Parameters:

  • invoice (#to_xml, String)
  • validate (Boolean) (defaults to: true) —

    run the FA(3) validator first. On by default: a document KSeF will reject costs a round trip and a slot in the session, and the local validator is free (DESIGN.md §7.7).

Returns:



43
44
45
46
47
48
49
50
51
52
 
# File 'lib/ksef/client/session.rb', line 43

def send_invoice(invoice, validate: true)
  @client.validate_invoice!(invoice) if validate
  submission = @client.sessions.send_invoice(@opened, invoice)

  Receipt.new(
    session_reference: @opened.reference_number,
    invoice_reference: submission.reference_number,
    session_valid_until: @opened.valid_until
  ).tap { |receipt| @receipts << receipt }
end

#to_s ⇒ Object 



65
 
# File 'lib/ksef/client/session.rb', line 65

def to_s = reference_number.to_s