XrechnungKit
Table of Contents
Interfaces
- LoggerInterface
- PSR-3 compatible subset used by the core pipeline.
- NotificationChannelInterface
- A delivery mechanism for notifications. Implementations should swallow
transient delivery errors rather than propagating them; the pipeline must
not crash because Slack is down.
- NotificationDispatcherInterface
Classes
- AtomicWriter
- Atomic write with quarantine sibling.
- XRechnungBuilder
- Bridges the typed MappingData value-object graph to the lifted L3
XRechnungEntity so the existing Generator pipeline can consume MappingData
without rewriting the placeholder substitution layer.
- MappingDataException
- Thrown at MappingData (or any of its component value objects) construction
when an invariant is violated: invalid country code, negative quantity,
malformed Leitweg-ID, currency mismatch, etc.
- XRechnungKitException
- Root of the kit's exception hierarchy. Per architecture section 11 the kit
surfaces three exception families, all extending this base: Mapping
DataException (thrown at value-object construction), GenerationException
(thrown by the Generator), and ValidationException (thrown only when
validateOrThrow is used).
- NullLogger
- Address
- A postal address. Maps to the UBL <cac:PostalAddress> structure used in
both AccountingSupplierParty and AccountingCustomerParty.
- Attachment
- A binary attachment to be embedded as base64 in the XRechnung XML
(BG-24, EmbeddedDocumentBinaryObject).
- BillingReference
- Reference to a prior invoice. Required on credit notes per BR-DE-22 and on
deposit-cancellation documents. Maps to the UBL <cac:BillingReference>
structure carrying BG-3 / BT-25.
- Contact
- A point-of-contact at a Party. Maps to the UBL <cac:Contact> element.
- DocumentMeta
- Document-level header fields. Maps to the UBL <cbc:ID>, <cbc:IssueDate>,
<cbc:InvoiceTypeCode>, <cbc:DocumentCurrencyCode>, <cbc:DueDate>,
<cbc:BuyerReference>, and <cbc:Note> elements.
- DocumentPeriod
- A delivery / billing period. Maps to UBL <cac:InvoicePeriod> (BG-14 at the
document level, BG-26 at the line-item level).
- DocumentTotals
- Document-level monetary totals. Maps to UBL <cac:LegalMonetaryTotal>
and <cac:TaxTotal>.
- LineItem
- One line on the invoice. Maps to UBL <cac:InvoiceLine>.
- MappingData
- Root of the typed value-object graph that flows from the consumer's mapper
into the generator pipeline. Once constructed, MappingData is structurally
trusted; downstream stages (Builder, Generator, Validator, Writer) do not
re-validate the shape.
- Money
- A monetary amount paired with its ISO 4217 currency.
- Note
- A free-text note attached to the document. Maps to UBL <cbc:Note> (BT-22).
- Party
- A party on the invoice: seller (AccountingSupplierParty) or buyer
(AccountingCustomerParty). One VO covers both roles; the role-aware
named constructors enforce the role-specific invariants:
- PaymentMeans
- One payment-means record. Maps to the UBL <cac:PaymentMeans> structure
(BG-16). The named constructors enforce the per-code invariants:
- TaxBreakdown
- One row of the document-level tax subtotal. Maps to UBL
<cac:TaxSubtotal> inside <cac:TaxTotal>.
- TaxId
- A tax identifier: VAT registration number, local company-registration
number, or other scheme. Maps to the UBL <cac:PartyTaxScheme> structure.
- CallableChannel
- Wraps any callable as a notification channel. Use this for one-off integrations
(a closure that pushes to a queue, posts to PagerDuty, opens a Linear issue, etc.)
without writing a dedicated channel class.
- EmailChannel
- Sends notifications via email.
- LogChannel
- Routes a notification through the configured LoggerInterface. The logger
method is chosen from the notification severity.
- NullChannel
- SlackChannel
- Posts to a Slack incoming webhook URL.
- WebhookChannel
- Generic JSON HTTP POST. Works with Discord, Microsoft Teams, custom webhooks,
and most pull-style monitoring endpoints.
- ChannelDispatcher
- Fans out one notification to every registered channel. An empty dispatcher
is a valid no-op and is the default the pipeline uses when the consumer has
not configured any notification channels.
- DeduplicatingDispatcher
- Decorator that drops repeated notifications with the same signature within a
configurable TTL window. Cache is in-process; horizontally-scaled deployments
should swap this for a Redis-backed equivalent (adapter packages may provide one).
- Notification
- Operator-facing notification dispatched when the pipeline detects a condition
that needs human attention (typically: invalid generated XML).
- XRechnungConstant
- XRechnungEntity
- XRechnungGenerator
- XRechnungGenerator is responsible for generating XRechnung XML files
using the data provided by the XRechnungEntity.
- XRechnungInvoiceLineItem
- XRechnungTemplate
- XRechnungTemplate class provides functionalities to handle XRechnung template files.
- XRechnungValidator
- Validates XRechnung XML against the bundled UBL XSD schema. Both an
in-memory entry point (validateContent) and a file-path entry point
(validate) are provided; the file-path variant is a thin convenience
wrapper around the in-memory one.
Enums
- PaymentMeansCode
- UNTDID 4461 payment means codes the kit emits at v1.0. Subset chosen by
the architecture (section 5.1) to cover the cases real consumers ship: SEPA
(CT and DD), card payments (credit and bank), cash, and non-SEPA bank
transfers.
- Severity
- XRechnungInvoiceTypeCode
- UNTDID 1001 invoice type codes used by XRechnung. Backed-int enum so cases
substitute directly into the placeholder pipeline as their numeric value.
- XRechnungTaxCategory
- EN 16931 BG-23 tax category codes. Backed-string enum so cases substitute
directly into the placeholder pipeline as their letter code.