Module: Ksef::FA3

Defined in:
lib/ksef/fa3.rb,
lib/ksef/fa3/nip.rb,
lib/ksef/fa3/line.rb,
lib/ksef/fa3/issue.rb,
lib/ksef/fa3/order.rb,
lib/ksef/fa3/parser.rb,
lib/ksef/fa3/totals.rb,
lib/ksef/fa3/address.rb,
lib/ksef/fa3/builder.rb,
lib/ksef/fa3/invoice.rb,
lib/ksef/fa3/subject.rb,
lib/ksef/fa3/vat_rate.rb,
lib/ksef/fa3/canonical.rb,
lib/ksef/fa3/summaries.rb,
lib/ksef/fa3/validator.rb,
lib/ksef/fa3/attachment.rb,
lib/ksef/fa3/correction.rb,
lib/ksef/fa3/data_block.rb,
lib/ksef/fa3/formatting.rb,
lib/ksef/fa3/meta_entry.rb,
lib/ksef/fa3/order_line.rb,
lib/ksef/fa3/provenance.rb,
lib/ksef/fa3/row_reader.rb,
lib/ksef/fa3/serializer.rb,
lib/ksef/fa3/node_reader.rb,
lib/ksef/fa3/element_tree.rb,
lib/ksef/fa3/field_checks.rb,
lib/ksef/fa3/table_column.rb,
lib/ksef/fa3/advance_checks.rb,
lib/ksef/fa3/advance_reader.rb,
lib/ksef/fa3/subject_checks.rb,
lib/ksef/fa3/subject_reader.rb,
lib/ksef/fa3/summary_checks.rb,
lib/ksef/fa3/advance_invoice.rb,
lib/ksef/fa3/generated/enums.rb,
lib/ksef/fa3/generated/types.rb,
lib/ksef/fa3/model_validator.rb,
lib/ksef/fa3/attachment_table.rb,
lib/ksef/fa3/builder/advances.rb,
lib/ksef/fa3/builder/subjects.rb,
lib/ksef/fa3/document_mapping.rb,
lib/ksef/fa3/attachment_checks.rb,
lib/ksef/fa3/attachment_reader.rb,
lib/ksef/fa3/corrected_invoice.rb,
lib/ksef/fa3/correction_checks.rb,
lib/ksef/fa3/correction_reader.rb,
lib/ksef/fa3/business_validator.rb,
lib/ksef/fa3/document_validator.rb,
lib/ksef/fa3/rounding_inference.rb,
lib/ksef/fa3/builder/corrections.rb

Overview

The FA(3) invoice builder. Has no HTTP dependency and is usable on its own (DESIGN.md §5.1) — the transport layer accepts anything responding to #to_xml.

Defined Under Namespace

Modules: AdvanceChecks, AdvanceReader, AttachmentChecks, AttachmentReader, BusinessValidator, Canonical, CorrectionChecks, CorrectionReader, DocumentMapping, DocumentValidator, ElementTree, FieldChecks, Formatting, Generated, ModelValidator, NIP, NodeReader, Parser, Provenance, RoundingInference, RowReader, SubjectChecks, SubjectReader, Summaries, SummaryChecks, Validator, VatRate Classes: Address, AdvanceInvoice, Attachment, AttachmentTable, Builder, CorrectedInvoice, Correction, DataBlock, Invoice, Issue, Line, MetaEntry, Order, OrderLine, Serializer, Subject, TableColumn, Totals

Class Method Summary collapse

Class Method Details

.build {|builder| ... } ⇒ Invoice

Build an Invoice through the keyword DSL of DESIGN.md §8.

The DSL is a thin, forgiving front end over the value objects: it accepts English shorthand (qty:, vat:), coerces a plain Hash into an Address, and reports a missing or misspelled field by name instead of letting it surface later as a schema rejection. Everything it produces could be constructed by hand; see the README for the same invoice written the long way.

Examples:

invoice = Ksef::FA3.build do |f|
  f.seller nip: "9999999999", name: "ACME sp. z o.o.",
           address: { street: "Prosta 1", city: "Warszawa", postal_code: "00-001" }
  f.buyer  nip: "1111111111", name: "Klient S.A.", address: "Długa 2, 30-001 Kraków"
  f.number "FV/2026/08/001"
  f.issue_date Date.today
  f.line name: "Consulting", qty: 10, unit: "godz.", net_unit_price: 150, vat: "23"
end

Yield Parameters:

Returns:

Raises:



29
30
31
32
33
34
35
 
# File 'lib/ksef/fa3.rb', line 29

def build
  raise ArgumentError, "Ksef::FA3.build requires a block; see DESIGN.md §8" unless block_given?

  builder = Builder.new
  yield builder
  builder.to_invoice
end

.parse(xml) ⇒ Invoice

Read an FA(3) document back into an Invoice (DESIGN.md §7.6).

The inverse of #build only as far as this model reaches. FA(3) is much larger than a plain VAT invoice, so the whole document is retained on Ksef::FA3::Invoice#raw_document and Ksef::FA3::Provenance#unmapped_elements names what #to_xml would drop. Check it before re-serialising anything you did not write yourself.

Examples:

round-tripping your own invoice

Ksef::FA3.parse(invoice.to_xml) == invoice   # => true

reading one KSeF sent back

parsed = Ksef::FA3.parse(client.download_invoice("5265877635-20250826-0100001AF629-AF"))
parsed.number                                # => "FA/2026/08/001"
parsed.unmapped_elements                     # => ["Faktura/Podmiot3", …]

Parameters:

  • xml (String, Nokogiri::XML::Document)

Returns:

Raises:

  • (Ksef::ValidationError) —

    if the input is not a parseable FA(3) invoice, or identifies a party by something other than a NIP



56
 
# File 'lib/ksef/fa3.rb', line 56

def parse(xml) = Parser.parse(xml)