{"id":44737038,"url":"https://github.com/alexzeitler/zugpferd","last_synced_at":"2026-02-21T14:00:52.624Z","repository":{"id":338536329,"uuid":"1158134343","full_name":"AlexZeitler/zugpferd","owner":"AlexZeitler","description":"ZUGFeRD / XRECHNUNG / DIN EN 16931 E-Invoicing for Ruby","archived":false,"fork":false,"pushed_at":"2026-02-19T11:23:16.000Z","size":9631,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-02-19T15:22:30.448Z","etag":null,"topics":["invoicing","ruby","ruby-gem","xrechnung","zugferd"],"latest_commit_sha":null,"homepage":"https://alexzeitler.github.io/zugpferd/","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AlexZeitler.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-14T21:13:57.000Z","updated_at":"2026-02-19T11:23:20.000Z","dependencies_parsed_at":null,"dependency_job_id":"434395a6-a70e-4c2c-b700-7730f6a6d038","html_url":"https://github.com/AlexZeitler/zugpferd","commit_stats":null,"previous_names":["alexzeitler/zugpferd"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/AlexZeitler/zugpferd","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexZeitler%2Fzugpferd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexZeitler%2Fzugpferd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexZeitler%2Fzugpferd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexZeitler%2Fzugpferd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AlexZeitler","download_url":"https://codeload.github.com/AlexZeitler/zugpferd/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexZeitler%2Fzugpferd/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29651964,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-20T09:27:29.698Z","status":"ssl_error","status_checked_at":"2026-02-20T09:26:12.373Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["invoicing","ruby","ruby-gem","xrechnung","zugferd"],"created_at":"2026-02-15T20:06:16.986Z","updated_at":"2026-02-20T13:00:52.813Z","avatar_url":"https://github.com/AlexZeitler.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Zugpferd\n\nA Ruby library for reading and writing **XRechnung** and **ZUGFeRD** electronic invoices (e-Rechnung) according to **EN 16931**, supporting both **UBL 2.1** and **UN/CEFACT CII** syntaxes.\n\nBuilt for Ruby developers integrating XRechnung or ZUGFeRD e-invoicing into their applications.\n\n## Features\n\n- Syntax-agnostic data model based on EN 16931 Business Terms (BTs)\n- UBL 2.1 Reader \u0026 Writer (Invoice and Credit Note)\n- UN/CEFACT CII Reader \u0026 Writer\n- PDF/A-3 embedding via Ghostscript — create ZUGFeRD / Factur-X hybrid invoices\n- XSD and Schematron validation (EN 16931 + XRechnung) — optional, requires Java + Saxon\n- Supported document types:\n  - `380` — Commercial Invoice\n  - `381` — Credit Note (UBL: separate `\u003cCreditNote\u003e` root element)\n  - `384` — Corrected Invoice\n  - `389` — Self-billed Invoice\n  - `326` — Partial Invoice\n  - `386` — Prepayment Invoice\n- No Rails dependency\n- BigDecimal for all monetary amounts\n\n## Installation\n\n```ruby\n# Gemfile\ngem \"zugpferd\"\n```\n\n```bash\nbundle install\n```\n\nOr install directly:\n\n```bash\ngem install zugpferd\n```\n\n## Usage\n\n### Reading a UBL invoice\n\n```ruby\nrequire \"zugpferd\"\n\nxml = File.read(\"invoice_ubl.xml\")\ninvoice = Zugpferd::UBL::Reader.new.read(xml)\n\nputs invoice.number          # BT-1\nputs invoice.seller.name     # BG-4\nputs invoice.type_code       # \"380\", \"381\", etc.\n\ninvoice.line_items.each do |line|\n  puts \"#{line.item.name}: #{line.line_extension_amount}\"\nend\n```\n\n### Reading a CII invoice\n\n```ruby\nxml = File.read(\"invoice_cii.xml\")\ninvoice = Zugpferd::CII::Reader.new.read(xml)\n```\n\nThe data model is identical regardless of whether UBL or CII is used.\n\n### Writing a UBL invoice\n\n```ruby\ninvoice = Zugpferd::Model::Invoice.new(\n  number: \"INV-2024-001\",\n  issue_date: Date.today,\n  type_code: \"380\",\n  currency_code: \"EUR\",\n)\n\ninvoice.seller = Zugpferd::Model::TradeParty.new(name: \"Seller GmbH\")\ninvoice.buyer  = Zugpferd::Model::TradeParty.new(name: \"Buyer AG\")\n\n# ... set line items, tax, totals, payment ...\n\nxml = Zugpferd::UBL::Writer.new.write(invoice)\nFile.write(\"output.xml\", xml)\n```\n\n### Writing a Credit Note\n\n```ruby\ncredit_note = Zugpferd::Model::CreditNote.new(\n  number: \"CN-2024-001\",\n  issue_date: Date.today,\n)\n\n# The writer automatically generates \u003cCreditNote\u003e instead of \u003cInvoice\u003e\nxml = Zugpferd::UBL::Writer.new.write(credit_note)\n```\n\n### Converting between syntaxes\n\n```ruby\n# Read CII, write as UBL\ninvoice = Zugpferd::CII::Reader.new.read(cii_xml)\nubl_xml = Zugpferd::UBL::Writer.new.write(invoice)\n```\n\n### Creating a ZUGFeRD / Factur-X PDF\n\nRequires [Ghostscript](https://ghostscript.com/) installed on the system.\n\n```ruby\nrequire \"zugpferd\"\nrequire \"zugpferd/pdf\"  # explicit opt-in\n\nxml = Zugpferd::CII::Writer.new.write(invoice)\n\nembedder = Zugpferd::PDF::Embedder.new\nembedder.embed(\n  pdf_path: \"rechnung.pdf\",\n  xml: xml,\n  output_path: \"rechnung_zugferd.pdf\",\n  version: \"2p1\",\n  conformance_level: \"XRECHNUNG\"  # use \"EN 16931\" for non-XRechnung invoices\n)\n```\n\n### Validating an invoice\n\nRequires Java and Saxon HE. Install via `bin/setup-schemas`.\n\n```ruby\nrequire \"zugpferd\"\nrequire \"zugpferd/validation\"  # explicit opt-in, requires Java + Saxon\n\nxml = Zugpferd::CII::Writer.new.write(invoice)\n\nvalidator = Zugpferd::Validation::SchematronValidator.new(schemas_path: \"vendor/schemas\")\nerrors = validator.validate(xml, rule_set: :xrechnung_cii)\nfatals = errors.select { |e| e.flag == \"fatal\" }\n\nif fatals.any?\n  fatals.each { |e| puts \"[#{e.id}] #{e.text}\" }\nend\n```\n\n## Data Model\n\nThe model maps to the Business Groups of EN 16931:\n\n| Class | Business Group | Description |\n|-------|---------------|-------------|\n| `Model::Invoice` | BG-0 | Commercial Invoice (380) |\n| `Model::CreditNote` | BG-0 | Credit Note (381) |\n| `Model::CorrectedInvoice` | BG-0 | Corrected Invoice (384) |\n| `Model::SelfBilledInvoice` | BG-0 | Self-billed Invoice (389) |\n| `Model::PartialInvoice` | BG-0 | Partial Invoice (326) |\n| `Model::PrepaymentInvoice` | BG-0 | Prepayment Invoice (386) |\n| `Model::TradeParty` | BG-4 / BG-7 | Seller / Buyer |\n| `Model::PostalAddress` | BG-5 / BG-8 | Postal address |\n| `Model::Contact` | BG-6 / BG-9 | Contact information |\n| `Model::LineItem` | BG-25 | Invoice line |\n| `Model::Item` | BG-31 | Item information |\n| `Model::Price` | BG-29 | Price details |\n| `Model::MonetaryTotals` | BG-22 | Document totals |\n| `Model::TaxBreakdown` | BG-23 | VAT breakdown |\n| `Model::PaymentInstructions` | BG-16 | Payment information |\n| `Model::AllowanceCharge` | BG-20 / BG-21 | Allowances and charges |\n\n## Requirements\n\n- Ruby \u003e= 3.2\n- nokogiri ~\u003e 1.16\n- bigdecimal ~\u003e 3.1\n\n## Development\n\n```bash\nbundle install\nbin/setup-schemas    # Downloads XSD schemas, CEN Schematron, XRechnung test suite\nbundle exec rake test\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexzeitler%2Fzugpferd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falexzeitler%2Fzugpferd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexzeitler%2Fzugpferd/lists"}