feat(invoice): add e-invoice support with XRechnung/ZUGFeRD and advanced export features

2025-08-12 12:37:01 +00:00
parent 08d7803be2
commit 73b46f7857
19 changed files with 6211 additions and 20 deletions
--- a/readme.md
+++ b/readme.md
@@ -1,7 +1,7 @@
 # @fin.cx/skr 📊

 > **Enterprise-grade German accounting standards implementation for SKR03 and SKR04**  
-> Rock-solid double-entry bookkeeping with MongoDB persistence and full TypeScript support
+> Rock-solid double-entry bookkeeping with MongoDB persistence, e-invoice integration, and full TypeScript support

 ## 🚀 Why @fin.cx/skr?

@@ -17,6 +17,9 @@ Building compliant German accounting software? You've come to the right place! T
 - **🔄 Transaction Safety**: Built-in double-entry validation and automatic reversals
 - **✅ Battle-Tested**: 65+ comprehensive tests covering all edge cases
 - **🛡️ SKR Validation**: Automatic validation against official SKR standards
+- **🧾 E-Invoice Support**: Full XRechnung/ZUGFeRD integration for modern invoice processing
+- **🔐 Cryptographic Security**: Merkle tree and digital signature support for audit trails
+- **📑 PDF Export**: Professional PDF report generation with customizable templates

 ## 📦 Installation

@@ -76,6 +79,47 @@ const journalEntry = await api.postJournalEntry({
 });
 ```

+### 🧾 E-Invoice Integration
+
+```typescript
+// Import electronic invoices (XRechnung/ZUGFeRD)
+const invoiceData = await api.importInvoice(xmlContent, {
+  format: 'xrechnung',
+  validateSchema: true,
+  checkDuplicates: true
+});
+
+// Automatically book invoice to accounting
+const booking = await api.bookInvoice(invoiceData.invoiceId, {
+  autoDetectAccounts: true,
+  splitVAT: true,
+  createPaymentSchedule: true
+});
+
+// Export invoice in various formats
+const xRechnung = await api.exportInvoice(invoiceId, {
+  format: 'xrechnung',
+  version: '3.0',
+  includeAttachments: true
+});
+
+// Search and filter invoices
+const invoices = await api.searchInvoices({
+  dateFrom: new Date('2024-01-01'),
+  dateTo: new Date('2024-12-31'),
+  status: 'booked',
+  minAmount: 100,
+  customerVATId: 'DE123456789'
+});
+
+// Generate compliance reports
+const complianceReport = await api.createInvoiceComplianceReport({
+  period: '2024-Q1',
+  includeValidation: true,
+  includeStatistics: true
+});
+```
+
 ### 📊 Generating Financial Reports

 ```typescript
@@ -109,6 +153,71 @@ const cashFlow = await api.generateCashFlowStatement({
 });
 ```

+### 📑 Advanced Export Features
+
+```typescript
+// Export complete annual closing package (Jahresabschluss)
+const jahresabschluss = await api.exportJahresabschluss({
+  year: 2024,
+  includeReports: ['balance_sheet', 'income_statement', 'cash_flow'],
+  format: 'structured', // 'structured' | 'pdf' | 'csv'
+  language: 'de',
+  signatureRequired: true
+});
+
+// Generate PDF reports with professional formatting
+const pdfReports = await api.generatePdfReports({
+  reports: ['trial_balance', 'income_statement', 'balance_sheet'],
+  dateFrom: new Date('2024-01-01'),
+  dateTo: new Date('2024-12-31'),
+  companyInfo: {
+    name: 'Mustermann GmbH',
+    address: 'Hauptstraße 1, 10115 Berlin',
+    taxNumber: 'DE123456789',
+    registrationNumber: 'HRB 12345'
+  },
+  outputPath: './reports/',
+  template: 'professional' // Custom templates available
+});
+
+// Export with cryptographic signatures for audit trail
+const signedExport = await api.signExport({
+  data: jahresabschluss,
+  privateKey: privateKeyPEM,
+  certificate: certificatePEM,
+  includeTimestamp: true,
+  hashAlgorithm: 'SHA256'
+});
+
+// Detailed account data export
+const accountExport = await api.exportAccountData({
+  dateFrom: new Date('2024-01-01'),
+  dateTo: new Date('2024-12-31'),
+  format: 'detailed', // 'summary' | 'detailed' | 'tree'
+  includeTransactions: true,
+  includeBalances: true
+});
+
+// Balance history export for analysis
+const balanceHistory = await api.exportBalanceData({
+  accounts: ['1200', '1000', '8400'],
+  interval: 'monthly', // 'daily' | 'weekly' | 'monthly' | 'quarterly'
+  dateFrom: new Date('2024-01-01'),
+  dateTo: new Date('2024-12-31'),
+  includeRunningTotals: true
+});
+
+// Ledger export with filtering options
+const ledgerExport = await api.exportLedgerData({
+  accounts: ['1000-1999'], // Range support
+  dateFrom: new Date('2024-01-01'),
+  dateTo: new Date('2024-12-31'),
+  includeReversals: false,
+  groupByAccount: true,
+  format: 'journal' // 'journal' | 'T-account' | 'chronological'
+});
+```
+
 ## 🏗️ Core Features

 ### Account Management
@@ -316,6 +425,50 @@ try {
 }
 ```

+### Invoice Processing & Compliance
+
+```typescript
+// Get invoice statistics and analytics
+const stats = await api.getInvoiceStatistics({
+  dateFrom: new Date('2024-01-01'),
+  dateTo: new Date('2024-12-31'),
+  groupBy: 'month',
+  includeVATAnalysis: true
+});
+
+// Generate invoices programmatically
+const invoice = await api.generateInvoice({
+  invoiceNumber: 'INV-2024-001',
+  date: new Date(),
+  dueDate: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000),
+  seller: {
+    name: 'Your Company GmbH',
+    vatId: 'DE123456789',
+    address: 'Hauptstraße 1, 10115 Berlin'
+  },
+  buyer: {
+    name: 'Customer AG',
+    vatId: 'DE987654321',
+    address: 'Kundenweg 5, 80331 München'
+  },
+  lines: [
+    {
+      description: 'Consulting Services',
+      quantity: 10,
+      unitPrice: 100,
+      vatRate: 19
+    }
+  ]
+});
+
+// Validate invoice compliance
+const validation = await api.validateInvoice(invoice, {
+  standard: 'xrechnung',
+  checkBusinessRules: true,
+  checkVATRules: true
+});
+```
+
 ### Utility Functions

 ```typescript
@@ -346,7 +499,12 @@ import type {
  IPaginationParams,
  IAccountBalance,
  ICashFlowStatement,
-  IGeneralLedger
+  IGeneralLedger,
+  IInvoice,
+  IInvoiceLine,
+  IInvoiceParty,
+  IBookingRules,
+  IValidationResult
 } from '@fin.cx/skr';

 // All operations are fully typed
@@ -413,7 +571,22 @@ async function performJahresabschluss() {
    ]
  });
  
-  // 2. Generate financial statements
+  // 2. Generate comprehensive annual closing package
+  const jahresabschluss = await api.exportJahresabschluss({
+    year: 2024,
+    includeReports: ['balance_sheet', 'income_statement', 'cash_flow', 'trial_balance'],
+    format: 'pdf',
+    language: 'de',
+    signatureRequired: true,
+    companyInfo: {
+      name: 'Mustermann GmbH',
+      address: 'Hauptstraße 1, 10115 Berlin',
+      taxNumber: 'DE123456789',
+      registrationNumber: 'HRB 12345'
+    }
+  });
+  
+  // 3. Generate individual reports for analysis
  const incomeStatement = await api.generateIncomeStatement({
    dateFrom: new Date('2024-01-01'),
    dateTo: new Date('2024-12-31')
@@ -423,34 +596,37 @@ async function performJahresabschluss() {
    date: new Date('2024-12-31')
  });
  
-  const trialBalance = await api.generateTrialBalance({
-    dateFrom: new Date('2024-01-01'),
-    dateTo: new Date('2024-12-31')
-  });
-  
  const cashFlow = await api.generateCashFlowStatement({
    dateFrom: new Date('2024-01-01'),
    dateTo: new Date('2024-12-31')
  });
  
-  // 3. Export for tax advisor
+  // 4. Export for tax advisor in DATEV format
  const datevExport = await api.exportToDATEV({
    dateFrom: new Date('2024-01-01'),
    dateTo: new Date('2024-12-31')
  });
  
-  // 4. Close the period
+  // 5. Create signed export for audit trail
+  const signedExport = await api.signExport({
+    data: jahresabschluss,
+    privateKey: process.env.PRIVATE_KEY!,
+    certificate: process.env.CERTIFICATE!,
+    includeTimestamp: true
+  });
+  
+  // 6. Close the period
  await api.closePeriod('2024-12', {
    performYearEndAdjustments: true,
    generateReports: true
  });
  
-  console.log('=== Jahresabschluss 2024 ===');
-  console.log(`Umsatz: €${incomeStatement.totalRevenue}`);
-  console.log(`Aufwendungen: €${incomeStatement.totalExpenses}`);
-  console.log(`Jahresergebnis: €${incomeStatement.netIncome}`);
-  console.log(`Bilanzsumme: €${balanceSheet.assets.totalAssets}`);
-  console.log(`Cash Flow: €${cashFlow.netCashFlow}`);
+  console.log('🎊 Jahresabschluss 2024 Complete!');
+  console.log(`📈 Umsatz: €${incomeStatement.totalRevenue.toLocaleString('de-DE')}`);
+  console.log(`💰 Aufwendungen: €${incomeStatement.totalExpenses.toLocaleString('de-DE')}`);
+  console.log(`📊 Jahresergebnis: €${incomeStatement.netIncome.toLocaleString('de-DE')}`);
+  console.log(`💼 Bilanzsumme: €${balanceSheet.assets.totalAssets.toLocaleString('de-DE')}`);
+  console.log(`💵 Cash Flow: €${cashFlow.netCashFlow.toLocaleString('de-DE')}`);
  console.log(incomeStatement.netIncome > 0 ? '✅ Gewinn!' : '📉 Verlust');
  
  await api.close();
@@ -472,6 +648,9 @@ performJahresabschluss().catch(console.error);
 | **`Account`** | Account model with balance tracking |
 | **`Transaction`** | Double-entry transaction model |
 | **`JournalEntry`** | Complex multi-line journal entries |
+| **`InvoiceAdapter`** | XRechnung/ZUGFeRD invoice processing |
+| **`InvoiceBookingEngine`** | Automatic invoice to accounting booking |
+| **`InvoiceStorage`** | Invoice persistence and search |

 ### Key Methods

@@ -489,6 +668,13 @@ performJahresabschluss().catch(console.error);
 | `generateCashFlowStatement(params)` | Generate cash flow statement |
 | `generateGeneralLedger(params)` | Generate complete general ledger |
 | `exportToDATEV(params)` | Export DATEV-compatible data |
+| `exportJahresabschluss(params)` | Export complete annual closing package |
+| `generatePdfReports(params)` | Generate professional PDF reports |
+| `signExport(data)` | Create cryptographically signed exports |
+| `importInvoice(data, options)` | Import XRechnung/ZUGFeRD invoices |
+| `bookInvoice(invoiceId, rules)` | Book invoice to accounting |
+| `exportInvoice(id, options)` | Export invoice in various formats |
+| `searchInvoices(filter)` | Search and filter invoices |
 | `closePeriod(period, options)` | Close accounting period |
 | `recalculateBalances()` | Recalculate all account balances |
 | `validateDoubleEntry(data)` | Validate transaction before posting |
@@ -505,6 +691,9 @@ performJahresabschluss().catch(console.error);
 - **📚 German Compliance**: Full HGB/GoBD compliance built-in
 - **🤝 Type Safety**: Complete TypeScript definitions prevent runtime errors
 - **🔍 Smart Validation**: Warns about non-standard accounts and type mismatches
+- **🧾 E-Invoice Ready**: Native XRechnung/ZUGFeRD support for modern workflows
+- **🔐 Audit-Proof**: Cryptographic signatures and Merkle trees for tamper-proof records
+- **📑 Professional Reports**: Generate PDF reports that impress auditors and stakeholders

 ## 📋 Requirements

@@ -525,6 +714,8 @@ pnpm test test/test.skr03.ts         # SKR03 functionality
 pnpm test test/test.skr04.ts         # SKR04 functionality
 pnpm test test/test.jahresabschluss.skr03.ts  # Annual closing SKR03
 pnpm test test/test.jahresabschluss.skr04.ts  # Annual closing SKR04
+pnpm test test/test.invoice.ts       # Invoice processing
+pnpm test test/test.export.ts        # Export functionality
 ```

 ## License and Legal Information