en16931 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 68e50271df60f58d073c6fa0d95500a97b97619c524e7d678d44f2e3fb4860ac
+  data.tar.gz: dee874aede98b65b9a4e9e99ed4c63a2e4a62978260bd469d41aea340621c7a5
+SHA512:
+  metadata.gz: aee3a214e1ee51743bd4783c3021dd5fc0fcf6c7e68162dfcbaa5a61be926f93294e8b98b67ba10cb2b8130bc1e384de244edc4421bf148b5c50c70fbe1314cf
+  data.tar.gz: 938665eec90c4c06e64f999b830b659669af1c9f68168cc45ecb6d96bb9968b78e9f3ab078a8f697b7fb099d896cfad79e0224e39d9c95c3b0f5e15c2db24766

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-10-20
+
+- Invoice model with parties, lines, allowances and charges, payment details, periods and corrections.
+- XRechnung 3.0 (CII) and plain EN 16931 XML through zugpferd, with seller tax number, BIC, account name, invoicing period and preceding invoice added.
+- ZUGFeRD / Factur-X hybrid PDF/A-3b on Prawn in pure Ruby: XMP with the Factur-X extension schema, sRGB output intent, associated file.
+- Reference invoice layout in German and English: a letter with return-address line and recipient in the DIN 5008 window position.
+- Branding for the reference layout: logo (PNG/JPEG with alpha; CMYK and interlaced refused), position, accent colour, own TrueType font, intro and closing texts.
+- GiroCode (EPC QR code, version 002) next to the bank details, drawn as vectors; on by default for euro invoices with an IBAN and an amount due.
+- German VAT presets: standard, reduced, Kleinunternehmer, reverse charge, not taxable abroad, intra-community supply, export.
+- KoSIT and veraPDF wrappers, `rake validate`, a fixture matrix of ten invoice shapes that pass both.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Markus Schwed
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,144 @@
+# en16931
+
+EN 16931 e-invoices for Ruby, in pure Ruby.
+
+- A small invoice model: parties, lines, a VAT treatment, payment details.
+- **XRechnung** XML (UN/CEFACT CII, the German CIUS of EN 16931) through [zugpferd](https://github.com/alexzeitler/zugpferd).
+- **ZUGFeRD / Factur-X hybrid PDF/A-3b** with the XML embedded, built on [Prawn](https://prawnpdf.org) without Ghostscript, Java or hexapdf.
+- A **letter layout with branding**: logo, accent colour, own typeface, opening and closing lines, and the GiroCode (EPC QR code) next to the bank details.
+- **German VAT presets**: Regelbesteuerung, ermäßigter Satz, Kleinunternehmer (§ 19 UStG), Reverse Charge (§ 13b UStG), nicht im Inland steuerbar, innergemeinschaftliche Lieferung, Ausfuhr.
+- Wrappers for the official validators, [KoSIT](https://github.com/itplr-kosit/validator) and [veraPDF](https://verapdf.org), so CI proves every invoice shape you ship.
+
+Every fixture in `test/fixtures/invoices.rb` passes both validators; see `rake validate`.
+
+## Install
+
+```ruby
+gem "en16931"
+```
+
+Ruby 3.2 to 4.0 (CI runs every one). No system dependencies at run time. The validators need Java 11+ (KoSIT) and the `verapdf` command or Docker (veraPDF); they are for CI, not for production.
+
+## Usage
+
+```ruby
+require "en16931"
+
+seller = EN16931::Party.new(
+  name: "Lena Beispiel", street: "Musterstraße 12", postal_code: "10115", city: "Berlin", country: "DE",
+  vat_id: "DE123456789", tax_number: "30/123/45678",
+  email: "lena@example.com", phone: "+49 30 1234567", contact_name: "Lena Beispiel"
+)
+buyer = EN16931::Party.new(
+  name: "GlowCo Cosmetics GmbH", street: "Industriestraße 5", postal_code: "20457", city: "Hamburg", country: "DE",
+  vat_id: "DE987654321", email: "invoices@glowco.example"
+)
+
+invoice = EN16931::Invoice.new(
+  number: "2026-0001", issue_date: Date.new(2026, 10, 20), due_date: Date.new(2026, 11, 3),
+  seller: seller, buyer: buyer, buyer_reference: "PO-4711",
+  tax: EN16931::DE.standard,
+  lines: [EN16931::Line.new(description: "Produktvideo TikTok, 60 Sekunden", unit_price: "1500.00")],
+  payment: EN16931::Payment.new(iban: "DE89 3704 0044 0532 0130 00", bic: "COBADEFFXXX", holder: "Lena Beispiel",
+                                terms: "Zahlbar innerhalb von 14 Tagen ohne Abzug.")
+)
+
+xml = EN16931::XML.cii(invoice)                 # XRechnung 3.0 (CII)
+pdf = EN16931::PDF.render(invoice)              # ZUGFeRD hybrid PDF/A-3b, profile XRECHNUNG
+File.binwrite("2026-0001.pdf", pdf)
+```
+
+### Tax cases
+
+| Preset | Category | Use |
+|---|---|---|
+| `EN16931::DE.standard` | S 19 % | Regelbesteuerung |
+| `EN16931::DE.reduced` | S 7 % | ermäßigter Satz |
+| `EN16931::DE.small_business` | E | Kleinunternehmer nach § 19 UStG; the note is printed and carried in BT-120 |
+| `EN16931::DE.reverse_charge` | AE | business customer in another EU state; both VAT ids required |
+| `EN16931::DE.not_taxable_abroad` | O | service to a business outside the EU; no VAT ids on the invoice, the seller is identified by tax number |
+| `EN16931::DE.intra_community_supply` | K | goods to an EU business |
+| `EN16931::DE.export_supply` | G | goods exported outside the EU |
+
+A line or a document-level allowance/charge can carry its own `tax:`; otherwise the invoice's applies. `EN16931::Tax` builds any other treatment.
+
+### Branding
+
+The reference layout is a letter: letterhead, return-address line and recipient in the window position, title, details, lines, totals, payment block, footer with the tax ids. A `Branding` dresses it:
+
+```ruby
+branding = EN16931::Branding.new(
+  logo: "logo.png",                      # PNG or JPEG (RGB; alpha is fine); a path, the bytes or an IO
+  logo_position: :left,                  # or :right; the seller's name takes the other side
+  logo_height: 40,                       # points; width follows, capped by logo_max_width (180)
+  accent: "FF5A1F",                      # title and rules
+  font: { normal: "Inter-Regular.ttf", bold: "Inter-Bold.ttf" },   # TrueType, embedded; DejaVu Sans otherwise
+  intro: "vielen Dank für den Auftrag. Für die vereinbarte Leistung berechne ich wie folgt:",
+  closing: "Vielen Dank für die gute Zusammenarbeit.\n\nLena Beispiel",
+  giro_code: true                        # default: EPC QR code for euro invoices with an IBAN and an amount due
+)
+pdf = EN16931::PDF.render(invoice, branding:, locale: :de)
+```
+
+`Branding.new` rejects what would break PDF/A at construction time: CMYK JPEGs, interlaced PNGs, unknown image data. The GiroCode is drawn as vectors, so it adds no raster image; it carries the holder, IBAN, BIC, the amount due and the payment reference (or the invoice title) and is left out when the invoice is not in euro, has no IBAN or nothing is due.
+
+### Your own layout
+
+Draw the invoice with Prawn as you like, using embedded TrueType fonts (PDF/A forbids the unembedded base-14 fonts), then attach the XML:
+
+```ruby
+doc = Prawn::Document.new
+doc.font_families.update("Inter" => { normal: "fonts/Inter-Regular.ttf", bold: "fonts/Inter-Bold.ttf" })
+doc.font("Inter")
+# ... your layout ...
+EN16931::PDF::A3.attach(doc, EN16931::XML.cii(invoice), profile: :xrechnung, title: "Rechnung 2026-0001", author: seller.name)
+pdf = doc.render
+```
+
+`profile:` is `:xrechnung` (file `xrechnung.xml`, conformance `XRECHNUNG`), `:en16931`, `:extended` or `:basic` (file `factur-x.xml`).
+
+### Document types, periods, corrections
+
+```ruby
+EN16931::Invoice.new(type: :corrected, preceding: { number: "2026-0001", issue_date: Date.new(2026, 10, 20) }, ...)
+EN16931::Invoice.new(type: :credit_note, ...)
+EN16931::Invoice.new(type: :self_billed, ...)                     # Gutschrift im Sinne von § 14 Abs. 2 UStG
+EN16931::Invoice.new(period: Date.new(2026, 10, 1)..Date.new(2026, 10, 31), ...)   # BG-14, e.g. a retainer month
+EN16931::Invoice.new(prepaid: "200.00", allowances: [EN16931::AllowanceCharge.new(amount: "100.00", reason: "Treuerabatt", reason_code: "95")], ...)
+```
+
+### Validation
+
+```ruby
+kosit = EN16931::Validation::KoSIT.new.install!   # downloads the validator and the XRechnung configuration into tmp/kosit
+report = kosit.validate(xml)
+report.valid?      # => true
+report.errors      # => [] (Message#code, #text)
+
+vera = EN16931::Validation::VeraPDF.new            # `verapdf` command or the ghcr.io/verapdf/cli image
+vera.validate(pdf).valid?
+```
+
+`rake validate` runs both over every fixture and prints the matrix; `rake examples` writes the fixtures to `examples/` as XML and PDF.
+
+## What the fixtures cover
+
+Standard 19 %, mixed rates with a discount, Kleinunternehmer, reverse charge to an EU agency, a service to a US company in USD, a retainer with an invoicing period, hours with a prepayment and a charge, a corrected invoice, a credit note, a self-billed payout statement.
+
+## Legal notes
+
+The presets reproduce the customary German invoice notes. Which treatment applies to a transaction, and whether an e-invoice is required at all (since 2025 every German business must be able to receive one; issuing becomes mandatory in stages until 2028, Kleinunternehmer are exempt from issuing), is a question for a tax adviser. The library validates form, not facts.
+
+## Releasing
+
+Bump `lib/en16931/version.rb`, move the changelog entries under the new version, commit, then tag and push:
+
+```
+git tag v0.2.0 && git push origin v0.2.0
+```
+
+`.github/workflows/release.yml` runs the tests and both validators again and publishes through [Trusted Publishing](https://guides.rubygems.org/trusted-publishing/); no API key is stored anywhere.
+
+## Licences
+
+MIT. Bundled: DejaVu Sans (Bitstream Vera licence, `fonts/LICENSE-DejaVu.txt`) and the sRGB profile from [Compact ICC Profiles](https://github.com/saucecontrol/Compact-ICC-Profiles) (CC0).

data/Rakefile

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+require "rubocop/rake_task"
+
+Minitest::TestTask.create
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]
+
+desc "Render every fixture invoice to examples/ as XML and hybrid PDF"
+task :examples do
+  $LOAD_PATH.unshift File.expand_path("lib", __dir__)
+  require "en16931"
+  require_relative "test/fixtures/invoices"
+  FileUtils.mkdir_p("examples")
+  Fixtures.each { |name, invoice| File.write("examples/#{name}.xml", EN16931::XML.cii(invoice)) }
+  Fixtures.renders.each do |name, (invoice, options)|
+    File.binwrite("examples/#{name}.pdf", EN16931::PDF.render(invoice, created_at: Time.utc(2026, 10, 20, 12), **options))
+    puts "examples/#{name}.pdf"
+  end
+end
+
+desc "Run the official validators (KoSIT for the XML, veraPDF for the PDF) over every fixture"
+task :validate do
+  $LOAD_PATH.unshift File.expand_path("lib", __dir__)
+  require "en16931"
+  require_relative "test/fixtures/invoices"
+  kosit = EN16931::Validation::KoSIT.new.install!
+  vera = EN16931::Validation::VeraPDF.new
+  failed = false
+  puts "render                       KoSIT      veraPDF   "
+  Fixtures.renders.each do |name, (invoice, options)|
+    xml_report = kosit.validate(EN16931::XML.cii(invoice))
+    pdf_report = vera.validate(EN16931::PDF.render(invoice, **options))
+    puts format("%<name>-28s %<xml>-10s %<pdf>-10s", name: name, xml: xml_report.valid? ? "valid" : "INVALID", pdf: pdf_report.valid? ? "valid" : "INVALID")
+    [xml_report, pdf_report].reject(&:valid?).each { |r| puts r.to_s.lines.map { |l| "    #{l}" }.join }
+    failed ||= !(xml_report.valid? && pdf_report.valid?)
+  end
+  abort "validation failed" if failed
+end

data/fonts/LICENSE-DejaVu.txt

@@ -0,0 +1,187 @@
+Fonts are (c) Bitstream (see below). DejaVu changes are in public domain.
+Glyphs imported from Arev fonts are (c) Tavmjong Bah (see below)
+
+
+Bitstream Vera Fonts Copyright
+------------------------------
+
+Copyright (c) 2003 by Bitstream, Inc. All Rights Reserved. Bitstream Vera is
+a trademark of Bitstream, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of the fonts accompanying this license ("Fonts") and associated
+documentation files (the "Font Software"), to reproduce and distribute the
+Font Software, including without limitation the rights to use, copy, merge,
+publish, distribute, and/or sell copies of the Font Software, and to permit
+persons to whom the Font Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright and trademark notices and this permission notice shall
+be included in all copies of one or more of the Font Software typefaces.
+
+The Font Software may be modified, altered, or added to, and in particular
+the designs of glyphs or characters in the Fonts may be modified and
+additional glyphs or characters may be added to the Fonts, only if the fonts
+are renamed to names not containing either the words "Bitstream" or the word
+"Vera".
+
+This License becomes null and void to the extent applicable to Fonts or Font
+Software that has been modified and is distributed under the "Bitstream
+Vera" names.
+
+The Font Software may be sold as part of a larger software package but no
+copy of one or more of the Font Software typefaces may be sold by itself.
+
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF COPYRIGHT, PATENT,
+TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL BITSTREAM OR THE GNOME
+FOUNDATION BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, INCLUDING
+ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF
+THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM OTHER DEALINGS IN THE
+FONT SOFTWARE.
+
+Except as contained in this notice, the names of Gnome, the Gnome
+Foundation, and Bitstream Inc., shall not be used in advertising or
+otherwise to promote the sale, use or other dealings in this Font Software
+without prior written authorization from the Gnome Foundation or Bitstream
+Inc., respectively. For further information, contact: fonts at gnome dot
+org.
+
+Arev Fonts Copyright
+------------------------------
+
+Copyright (c) 2006 by Tavmjong Bah. All Rights Reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the fonts accompanying this license ("Fonts") and
+associated documentation files (the "Font Software"), to reproduce
+and distribute the modifications to the Bitstream Vera Font Software,
+including without limitation the rights to use, copy, merge, publish,
+distribute, and/or sell copies of the Font Software, and to permit
+persons to whom the Font Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright and trademark notices and this permission notice
+shall be included in all copies of one or more of the Font Software
+typefaces.
+
+The Font Software may be modified, altered, or added to, and in
+particular the designs of glyphs or characters in the Fonts may be
+modified and additional glyphs or characters may be added to the
+Fonts, only if the fonts are renamed to names not containing either
+the words "Tavmjong Bah" or the word "Arev".
+
+This License becomes null and void to the extent applicable to Fonts
+or Font Software that has been modified and is distributed under the 
+"Tavmjong Bah Arev" names.
+
+The Font Software may be sold as part of a larger software package but
+no copy of one or more of the Font Software typefaces may be sold by
+itself.
+
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL
+TAVMJONG BAH BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.
+
+Except as contained in this notice, the name of Tavmjong Bah shall not
+be used in advertising or otherwise to promote the sale, use or other
+dealings in this Font Software without prior written authorization
+from Tavmjong Bah. For further information, contact: tavmjong @ free
+. fr.
+
+TeX Gyre DJV Math
+-----------------
+Fonts are (c) Bitstream (see below). DejaVu changes are in public domain.
+
+Math extensions done by B. Jackowski, P. Strzelczyk and P. Pianowski
+(on behalf of TeX users groups) are in public domain.
+
+Letters imported from Euler Fraktur from AMSfonts are (c) American
+Mathematical Society (see below).
+Bitstream Vera Fonts Copyright
+Copyright (c) 2003 by Bitstream, Inc. All Rights Reserved. Bitstream Vera
+is a trademark of Bitstream, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of the fonts accompanying this license (“Fonts”) and associated
+documentation
+files (the “Font Software”), to reproduce and distribute the Font Software,
+including without limitation the rights to use, copy, merge, publish,
+distribute,
+and/or sell copies of the Font Software, and to permit persons  to whom
+the Font Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright and trademark notices and this permission notice
+shall be
+included in all copies of one or more of the Font Software typefaces.
+
+The Font Software may be modified, altered, or added to, and in particular
+the designs of glyphs or characters in the Fonts may be modified and
+additional
+glyphs or characters may be added to the Fonts, only if the fonts are
+renamed
+to names not containing either the words “Bitstream” or the word “Vera”.
+
+This License becomes null and void to the extent applicable to Fonts or
+Font Software
+that has been modified and is distributed under the “Bitstream Vera”
+names.
+
+The Font Software may be sold as part of a larger software package but
+no copy
+of one or more of the Font Software typefaces may be sold by itself.
+
+THE FONT SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF COPYRIGHT, PATENT,
+TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL BITSTREAM OR THE GNOME
+FOUNDATION
+BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, INCLUDING ANY GENERAL,
+SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, WHETHER IN AN
+ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF THE USE OR
+INABILITY TO USE
+THE FONT SOFTWARE OR FROM OTHER DEALINGS IN THE FONT SOFTWARE.
+Except as contained in this notice, the names of GNOME, the GNOME
+Foundation,
+and Bitstream Inc., shall not be used in advertising or otherwise to promote
+the sale, use or other dealings in this Font Software without prior written
+authorization from the GNOME Foundation or Bitstream Inc., respectively.
+For further information, contact: fonts at gnome dot org.
+
+AMSFonts (v. 2.2) copyright
+
+The PostScript Type 1 implementation of the AMSFonts produced by and
+previously distributed by Blue Sky Research and Y&Y, Inc. are now freely
+available for general use. This has been accomplished through the
+cooperation
+of a consortium of scientific publishers with Blue Sky Research and Y&Y.
+Members of this consortium include:
+
+Elsevier Science IBM Corporation Society for Industrial and Applied
+Mathematics (SIAM) Springer-Verlag American Mathematical Society (AMS)
+
+In order to assure the authenticity of these fonts, copyright will be
+held by
+the American Mathematical Society. This is not meant to restrict in any way
+the legitimate use of the fonts, such as (but not limited to) electronic
+distribution of documents containing these fonts, inclusion of these fonts
+into other public domain or commercial font collections or computer
+applications, use of the outline data to create derivative fonts and/or
+faces, etc. However, the AMS does require that the AMS copyright notice be
+removed from any derivative versions of the fonts which have been altered in
+any way. In addition, to ensure the fidelity of TeX documents using Computer
+Modern fonts, Professor Donald Knuth, creator of the Computer Modern faces,
+has requested that any alterations which yield different font metrics be
+given a different name.
+
+$Id$