npm package: @martin_sol_95/n8n-nodes-buchhaltungsbutler
Description: n8n node for BuchhaltungsButler API integration - Brought to you by Mundschenk Nachrichtengesellschaft GmbH & Co. KG, Verlag der Böhme-Zeitung aus Soltau
Author: Mundschenk Nachrichtengesellschaft GmbH & Co. KG
Latest version: 0.7.0

# n8n-nodes-buchhaltungsbutler

This is an n8n community node that provides integration with [BuchhaltungsButler](https://www.buchhaltungsbutler.de/), a German accounting software for small businesses and freelancers.

[n8n](https://n8n.io/) is a workflow automation platform that allows you to automate tasks across different services.

---

**Brought to you by:**  
**Mundschenk Nachrichtengesellschaft GmbH & Co. KG**  
Verlag der [Böhme-Zeitung](https://www.boehme-zeitung.de/) aus Soltau

Wir lieben IT und geben der Community gerne etwas zurück. 💙

---

## ✨ Features

- 🧾 **Create Invoices** - Create invoices, e-invoices (ZUGFeRD/XRechnung), and invoice drafts
- 🔄 **Dynamic Invoice Items** - NEW in v0.6.0: Create invoices with dynamic line items from input data
- 👥 **Manage Contacts** - Add, update, and retrieve debtors and creditors
- 💰 **Handle Transactions** - Retrieve and manage transactions
- 📄 **Process Receipts** - Work with receipts and documents
- 🎨 **Improved UX** - Structured input with automatic validation
- 🇩🇪 **German UI** - Fully localized interface

## Installation

Follow the [installation guide](https://docs.n8n.io/integrations/community-nodes/installation/) in the n8n documentation.

### Community Nodes (recommended)

For users on n8n Cloud or self-hosted n8n:

1. Go to **Settings > Community Nodes**
2. Select **Install**
3. Enter `@martin_sol_95/n8n-nodes-buchhaltungsbutler` in **Enter npm package name**
4. Agree to the risks and click **Install**

After installing, you'll need to restart n8n to see the node.

### Manual installation

To get started, install the package in your n8n root directory:

```bash
npm install @martin_sol_95/n8n-nodes-buchhaltungsbutler
```

For Docker-based deployments, add the following line before the font installation command in your `n8n` Dockerfile:

```dockerfile
RUN cd /usr/local/lib/node_modules/n8n && npm install @martin_sol_95/n8n-nodes-buchhaltungsbutler
```

## Credentials

This node requires BuchhaltungsButler API credentials. You can obtain API credentials from your BuchhaltungsButler account settings.

### Credential setup

1. Open n8n
2. Go to **Credentials > New**
3. Search for **BuchhaltungsButler API**
4. Enter your credentials:
   - **API Client**: Your API client ID
   - **API Secret**: Your API secret key
   - **API Key**: Your API key for customer selection
5. Click **Save**

## Operations

The node currently supports the following resources and operations:

### 🧾 Invoices (Rechnungen)

#### Standard Operations (Manual Line Items)
- **Create Invoice**: Create invoices, credits, or offers with structured line items
- **Create E-Invoice**: Create e-invoices with ZUGFeRD/XRechnung format
- **Create Invoice Draft**: Create invoice drafts for preparation

**Key Features:**
- ✅ Structured line item input (no more comma-separated strings!)
- ✅ First item is mandatory and always visible
- ✅ Add unlimited additional items dynamically
- ✅ Automatic type validation for numbers and decimals
- ✅ Optional descriptions per line item
- ✅ Intelligent UI (e.g., tax rate only shown for standard VAT)
- ✅ Support for all API parameters

#### Dynamic Operations (Items from Input Data) - NEW in v0.6.0
- **Create Invoice (Dynamic Items)**: Process unlimited invoice items from previous nodes
- **Create E-Invoice (Dynamic Items)**: E-invoices with dynamic line items
- **Create Draft (Dynamic Items)**: Invoice drafts with dynamic line items

**Key Features:**
- 🔄 **Dynamic Item Processing**: Each input item becomes an invoice line item
- 📊 **Perfect for CSV/Excel Import**: Import product lists and create invoices
- 🎯 **Field Mapping**: Map your data fields to invoice fields
- ♾️ **Unlimited Items**: Process as many items as your input provides
- 🔗 **Workflow Integration**: Combine with filters, aggregations, transformations

**Use Cases:**
- Import invoice items from CSV/Excel files
- Create invoices from webhook data
- Aggregate multiple data sources into one invoice
- Batch invoice creation from databases

### Settings (Einstellungen)

- **Get Debtors**: Retrieve all debtors (customers)
- **Add Debtor**: Create a new debtor (customer)
- **Update Debtor**: Update an existing debtor (customer)
- **Get Creditors**: Retrieve all creditors (suppliers)
- **Add Creditor**: Create a new creditor (supplier)
- **Update Creditor**: Update an existing creditor (supplier)
- **Get Accounts**: Retrieve chart of accounts
- **Get Cost Centers**: Retrieve all cost centers
- **Get Tax Keys**: Retrieve all tax keys
- **Get Currencies**: Retrieve all currencies

### Transactions (Transaktionen)

- **Get Transactions**: Retrieve transactions
- Additional transaction operations

### Receipts (Belege)

- **Get Receipts**: Retrieve receipts (invoices)
- **Get Receipt By ID**: Retrieve a single receipt by ID with optional file download
  - 📎 **Binary File Support**: Files are automatically provided as binary data
  - Supported formats: PDF, ZUGFeRD, XRechnung XML
  - Files appear in the "Binary" tab in n8n
  - Ready for further processing (save, email, etc.)
- Additional receipt operations

## Usage

### Example: Create an invoice with multiple line items

1. Add a **Manual Trigger** node
2. Add a **BuchhaltungsButler** node
3. Select **Rechnungen** as the resource
4. Select **Rechnung Erstellen** as the operation
5. Fill in the basic information:
   - **Typ**: invoice (or credit/offer)
   - **Preisanzeige**: net (or gross)
   - **Firmenname**: Company name
   - **Datum**: 2025-01-15
6. Add line items in **Rechnungspositionen**:
   - **First item** (mandatory, always visible):
     - Name: Consulting
     - Quantity: 8
     - Unit: Hrs.
     - VAT %: 19
     - Unit Price: 100.00
     - Description: (optional)
   - Click **"Position hinzufügen"** to add more items
7. Optionally add more fields via **Zusätzliche Felder**
8. Execute the workflow

### Example: Create an e-invoice (ZUGFeRD/XRechnung)

1. Add a **BuchhaltungsButler** node
2. Select **Rechnungen** as the resource
3. Select **E-Rechnung Erstellen** as the operation
4. Fill in required fields including:
   - Basic information (type, company, date)
   - Complete address (mandatory for e-invoices)
   - E-Invoice ID (Leitweg-ID)
5. Add line items with **Tax Type**:
   - **S** - Standard VAT (requires tax rate %)
   - **Z** - 0% VAT
   - **AE** - Reverse Charge (§13b)
   - **K** - Intra-community supply
   - **G** - Third country supply
   - **E** - VAT exempt
6. Execute the workflow

### Example: Get all customers

1. Add a **Manual Trigger** node
2. Add a **BuchhaltungsButler** node
3. Select **Einstellungen** as the resource
4. Select **Debitoren Abrufen** as the operation
5. Configure additional options if needed:
   - **Nur Aktive**: Filter for active customers only
   - **Limit**: Limit the number of results
   - **Offset**: Skip a number of results (for pagination)
6. Execute the workflow

### Example: Create a new customer

1. Add a **Manual Trigger** node
2. Add a **BuchhaltungsButler** node
3. Select **Einstellungen** as the resource
4. Select **Debitor Hinzufügen** as the operation
5. Fill in the required fields:
   - **Name**: Customer name (required)
6. Optionally add more fields via **Zusätzliche Felder**:
   - **Debitorennummer**: Customer number (auto-generated if not provided)
   - **Email**: Customer email
   - **Address**: Street, ZIP, City, Country
   - And other optional fields
7. Execute the workflow

### Example: Get receipt with file as binary data (NEW in v0.5.3)

1. Add a **Manual Trigger** node
2. Add a **BuchhaltungsButler** node
3. Select **Belege** as the resource
4. Select **Beleg per ID Abrufen** as the operation
5. Enter the **Beleg-ID** (e.g., 26521)
6. Under **Zusätzliche Optionen**, enable **Datei Abrufen**
7. Execute the workflow
8. The file will appear in the **Binary** tab
9. You can now:
   - Save it using **Write Binary File** node
   - Send it via email using **Send Email** node
   - Process it with other nodes that accept binary data

## Compatibility

- Minimum n8n version: 1.0.0
- Tested with n8n version: 1.123.4+
- Node.js version: 20.x or higher

## Documentation

- [CHANGELOG.md](CHANGELOG.md) - Complete version history
- [RELEASE_NOTES_0.5.0.md](RELEASE_NOTES_0.5.0.md) - Detailed release notes for v0.5.0
- [INVOICES_V2_IMPLEMENTATION.md](INVOICES_V2_IMPLEMENTATION.md) - Invoice features documentation

## Resources

- [n8n documentation](https://docs.n8n.io/)
- [BuchhaltungsButler API documentation](https://app.buchhaltungsbutler.de/docs/api/v1/)
- [BuchhaltungsButler website](https://www.buchhaltungsbutler.de/)
- [npm package](https://www.npmjs.com/package/@martin_sol_95/n8n-nodes-buchhaltungsbutler)

## Version history

See [CHANGELOG.md](CHANGELOG.md) for detailed version history.

### [0.5.4] - 2025-12-16

**Code Quality**

#### Fixed
- ESLint warnings resolved - clean build process

### [0.5.3] - 2025-12-16

**Bug Fixes & Improvements**

#### Fixed
- **Get Receipt By ID Operation**: Binary file support
  - Files are now correctly provided as binary data in n8n
  - Automatic conversion from Base64 to binary format
  - MIME type detection (PDF, XML)
  - Files appear in the "Binary" tab
  - `file_content` removed from JSON to avoid duplication

### [0.5.2] - 2025-12-15

**Improvements**

#### Changed
- **Add Debtor Operation**: Debitorennummer ist jetzt optional
  - Wird automatisch von BuchhaltungsButler generiert, wenn nicht angegeben
  - Kann bei Bedarf manuell gesetzt werden

### [0.5.0] - 2025-12-10

**🎉 Major Release: Invoice Operations**

#### Added
- **Invoice Operations**: Complete implementation of invoice endpoints
  - Create Invoice (`/invoices/create`)
  - Create E-Invoice (`/invoices/create/e-invoice`) with ZUGFeRD/XRechnung support
  - Create Invoice Draft (`/invoices/create/draft`)
- **Improved UX**: Structured item input using fixedCollection
  - Individual line items can be added dynamically
  - First item is mandatory and always visible
  - Each item has its own validated fields (name, quantity, unit, VAT, price, description)
  - Automatic type validation for numeric fields
- **E-Invoice Support**: 
  - Tax types as dropdown (S, Z, AE, K, G, E)
  - Tax rate field only shown when tax type is "S" (intelligent UI)
  - Leitweg-ID support for public contracting authorities

#### Changed
- Invoice items are now structured objects instead of comma-separated strings
- Item descriptions moved from additional fields to individual items
- Improved error handling for invoice creation

#### Technical
- Added `fixedCollection` type for better UX
- Automatic transformation from item objects to API arrays
- Build size: ~211 KB
- No linter warnings

### [0.1.0] - 2025-12-09

**Initial Release**

- Settings operations (Debtors, Creditors, Accounts, Tax Keys, etc.)
- Transaction operations
- Receipt operations
- Support for additional options (filters, pagination)
- HTTP Basic Auth + API Key authentication
- Comprehensive error handling
- German UI translations

## License

[MIT](LICENSE)

## Support

For issues, questions, or contributions:

- Create an issue on the npm package page
- Visit the [n8n Community Forum](https://community.n8n.io/)
- Check the documentation files in this repository

## Contributing

Contributions are welcome! This is a community-maintained node.

See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines.

## Roadmap

Planned features for future versions:

- [ ] Get invoices (read operation)
- [ ] Update invoices
- [ ] Delete invoices
- [ ] Download invoice as PDF
- [ ] Send invoice via email
- [ ] List invoices with filters
- [ ] Invoice templates
- [ ] Bulk operations

## Disclaimer

This is an unofficial community node and is not affiliated with or endorsed by BuchhaltungsButler. Use at your own risk.

## Author & Organization

**Developed by:**  
**Mundschenk Nachrichtengesellschaft GmbH & Co. KG**  
Verlag der [Böhme-Zeitung](https://www.boehme-zeitung.de/)  
Soltau, Deutschland

**Maintainer:** Martin ([@martin_sol_95](https://www.npmjs.com/~martin_sol_95))

## Acknowledgments

Built with ❤️ for the n8n community.

Wir lieben IT und geben der Community gerne etwas zurück!

---

**About Mundschenk Nachrichtengesellschaft:**  
Als Verlag der Böhme-Zeitung aus Soltau sind wir tief in der regionalen Medienlandschaft verwurzelt. Neben unserem journalistischen Auftrag setzen wir auf moderne IT-Lösungen und Automatisierung. Mit diesem n8n Community Node möchten wir unsere Erfahrungen teilen und anderen Unternehmen helfen, ihre Buchhaltungsprozesse zu automatisieren.