zugferd-generator
Version:
A lightweight Node.js module for creating ZUGFeRD-compliant invoices.
165 lines (130 loc) • 4.34 kB
Markdown
<div>
<img src="https://badgen.now.sh/npm/v/zugferd-generator" alt="Version" />
<img src="https://badgen.now.sh/npm/license/zugferd-generator" alt="MIT License" />
<img src="https://badgen.now.sh/npm/dt/zugferd-generator" alt="Total downloads" />
<img src="https://badgen.now.sh/npm/types/zugferd-generator" alt="Types included" />
</div>
ZUGFeRD (short for **"Zentraler User Guide des Forums elektronische Rechnung Deutschland"**) is a standard for electronic invoicing in Germany. It combines structured invoice data (in XML format) with a visual representation (typically a PDF), allowing businesses to automate invoice processing while maintaining a human-readable version.
A lightweight Node.js module for creating ZUGFeRD-compliant invoices.
## Installation
Install the module via npm:
```bash
npm install zugferd-generator
```
## Usage
### Import the Module
```javascript
import ZUGFeRDGenerator from 'zugferd-generator'
```
### Example: Using the Functions
```javascript
const invoiceData = {
id: 'INV-001',
issueDate: '2024-01-01',
currency: 'EUR',
supplier: { name: 'Supplier Ltd.', country: 'DE' },
customer: { name: 'Customer Ltd.', country: 'DE' },
taxTotal: { taxAmount: 19, taxPercentage: 19 },
lineItems: [
{
id: 'ITEM-001',
description: 'Product A',
quantity: 1,
unitPrice: 100,
lineTotal: 100,
},
],
};
// Create a new invoice
const zugferd = new ZUGFeRDGenerator(invoiceData);
const invoicePdf = await fs.readFile('invoice.pdf');
const pdfWithEmbeddedEInvoice = await zugferd.embedInPDF(invoicePdf);
```
```javascript
const zugferd = new ZUGFeRDGenerator(invoiceData);
```
- **`invoiceData` (InvoiceData)**: The invoice to convert (see example above).
```typescript
interface InvoiceData {
id: string;
issueDate: string;
dueDate?: string; // optional
currency: string;
totalAmount: number;
supplier: {
name: string;
country: string;
street?: string; // optional
postalCode?: string; // optional
city?: string; // optional
taxNumber?: string; // optional
legalEntityID?: string; // optional
};
customer: {
name: string;
country: string;
street?: string; // optional
postalCode?: string; // optional
city?: string; // optional
taxNumber?: string; // optional
};
taxTotal: {
taxAmount: number;
taxPercentage: number;
};
paymentDetails?: { // optional
paymentMeansCode?: string; // optional
paymentID?: string; // optional
bankDetails?: {
accountName?: string; // optional
iban?: string; // optional
bic?: string; // optional
bankName?: string; // optional
}
};
notes?: string[]; // optional
lineItems: {
id: string;
description: string;
quantity: number;
unitPrice: number;
lineTotal: number;
}[];
}
```
1. **`toXMLString()`**
- Returns the XML representation of the invoice as a string.
```javascript
const xmlString = zugferd.toXMLString();
```
2. **`toBuffer()`**
- Returns the XML representation as a `Buffer` object.
```javascript
const buffer = zugferd.toBuffer();
```
3. **`toBlob()`**
- Returns the XML representation as a `Blob` object (useful for browser environments).
```javascript
const blob = zugferd.toBlob();
console.log(blob.content);
```
4. **`embedInPDF(pdfBuffer)`**
- Embeds the ZUGFeRD XML invoice into a given PDF file.
- **Parameters**:
- `pdfBuffer` (Buffer): The pdf file that the e-invoice should be attached to
- Returns a `Promise<Buffer>`.
```javascript
const invoicePdf = await fs.readFile('invoice.pdf');
const pdfWithEmbeddedEInvoice = await zugferd.embedInPDF(invoicePdf);
```
Contributions in the form of bug reports, feature requests, or pull requests are welcome! Please ensure you run the tests and cover new functionality when contributing.
This project is licensed under the [MIT License](LICENSE).
Looking for a developer with expertise in **Node.js**? Feel free to reach out to me for freelance projects, collaborations, or full-time opportunities!
Contact me [hello@pixelpal.io](mailto:hello@pixelpal.io)