Skip to content

CII Reader / Writer ​

Read and write documents in UN/CEFACT Cross-Industry Invoice (CII) format, as used by ZUGFeRD and XRechnung.

Reader ​

ruby
reader = Zugpferd::CII::Reader.new
invoice = reader.read(xml_string)

read(xml_string) → BillingDocument ​

Parses a CII D16B XML string and returns the appropriate model class based on the type code (e.g. CreditNote for 381, CorrectedInvoice for 384). Falls back to Invoice for type code 380 and unknown codes.

Parameters:

  • xml_string (String) — Valid CII CrossIndustryInvoice XML

Returns: Zugpferd::Model::Invoice, Zugpferd::Model::CreditNote, or other BillingDocument subtype

Raises:

  • Nokogiri::XML::SyntaxError if the XML is malformed
  • Zugpferd::CII::Reader::MissingTaxTotalError if the invoice total VAT amount (BT-110) is missing and the VAT breakdown (BG-23) is empty or does not sum to 0

Writer ​

ruby
writer = Zugpferd::CII::Writer.new
xml_string = writer.write(invoice)

write(invoice) → String ​

Serializes a billing document to a CII CrossIndustryInvoice XML string.

Parameters:

  • invoice (Zugpferd::Model::BillingDocument) — The document to serialize

Returns: String — UTF-8 encoded XML

CII Namespaces ​

PrefixURI
rsmurn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100
ramurn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100
udturn:un:unece:uncefact:data:standard:UnqualifiedDataType:100
qdturn:un:unece:uncefact:data:standard:QualifiedDataType:100

CII-Specific Notes ​

  • Dates use format code 102 (YYYYMMDD), e.g. 20240115
  • The creditor reference identifier (BT-90) is at the settlement level as ram:CreditorReferenceID
  • The mandate reference (BT-89) is inside ram:SpecifiedTradePaymentTerms/ram:DirectDebitMandateID
  • Tax information on line items is in ram:SpecifiedLineTradeSettlement/ram:ApplicableTradeTax, not in ram:SpecifiedTradeProduct
  • The charge indicator uses udt:Indicator with string values "true" / "false"
  • CII may omit the invoice total VAT amount (BT-110) on invoices without VAT. The reader then sets it to 0 and takes the currency from the document currency (BT-5), so the writers output 0 for it