importzugferd/README.md

ZUGFeRD Import for Dolibarr ERP & CRM

Import ZUGFeRD/Factur-X electronic invoices as supplier invoices in Dolibarr.

Features

Core Functionality

• PDF Import: Upload ZUGFeRD/Factur-X PDF invoices with embedded XML data
• XML Parsing: Automatic extraction and parsing of invoice data from embedded XML
• Duplicate Detection: SHA256 hash-based detection prevents importing the same invoice twice
• Supplier Detection: Automatic supplier matching via VAT ID or customer reference number

Product Matching

• Multi-Method Matching: Products are matched via:
  • Article mapping (supplier article number → your product)
  • EAN/GTIN barcode
  • Product reference
  • Manufacturer reference
• Manual Assignment: Assign products manually when automatic matching fails
• Product Creation: Create new products directly from import data
• Product Templates: Duplicate existing products with ZUGFeRD data pre-filled
• EAN Auto-Update: Automatically updates product barcodes from invoice data

Workflow

• Persistent Import Records: Imports are saved to database immediately
• Status Tracking:
  • Imported - Ready for invoice creation
  • Pending - Manual intervention required (missing products/supplier)
  • Processed - Supplier invoice created
  • Error - Import failed
• Resume Anytime: Continue editing imports later
• Sum Validation: Validates totals between ZUGFeRD data and created invoice

Batch Import

• Folder Monitoring: Import from a local folder (watch folder)
• IMAP Import: Import from email mailbox
• Automatic Archiving: Successfully imported files are moved to archive

Unit Code Translation

• Translates UN/ECE unit codes (C62, MTR, LTR, etc.) to readable labels (Stk., m, l)

Requirements

• Dolibarr 19.0 or higher
• PHP 7.1 or higher
• PHP IMAP extension (for email import functionality)

Installation

1. Copy the importzugferd folder to your Dolibarr custom directory
2. Enable the module in Setup > Modules > ZUGFeRD Import
3. Configure settings in ZUGFeRD Import > Setup

Configuration

IMAP Settings (for email import)

• IMAP Server hostname
• Port (993 for SSL, 143 for STARTTLS)
• Username and password
• Mailbox folder to monitor
• Use Test Connection to verify settings and select folder

Folder Settings (for folder import)

• Watch Folder: Local path for incoming invoices
• Archive Folder: Local path for processed invoices
• IMAP Archive Folder: Email folder for processed emails

Import Settings

• Auto-create invoices: Automatically create supplier invoices during batch import

Usage

Manual Import

1. Go to ZUGFeRD Import > Import Invoice
2. Upload a ZUGFeRD/Factur-X PDF file
3. Review invoice data and line items
4. Assign missing products if needed
5. Select supplier (if not auto-detected)
6. Click Create Supplier Invoice

Batch Import

1. Go to ZUGFeRD Import > Batch Import
2. Select source (Folder or Email)
3. Click Start Import
4. Review results

Product Mapping

1. Go to ZUGFeRD Import > Product Mapping
2. Select supplier
3. Add mappings: Supplier article number → Your product

Extrafields

The module adds a custom field to third parties:

• Customer No. at Supplier: Your customer number at this supplier (used for automatic supplier detection via buyer reference)

Translations

Available in:

• German (de_DE)
• English (en_US)

Version History

See CHANGELOG.md for detailed version history.

5.5 (Current)

• Fixed copper surcharge scaling in mass update (different quantities between Dolibarr and Datanorm)
• Fixed VAT rate preservation when updating prices
• New filters for price direction (up/down) in mass update
• Alternative Datanorm prices inherit min quantity, packaging, VAT, and kaufmenge from existing prices
• Copper surcharge is NOT set by import - calculated by separate module

4.2

• PDF attachments properly linked to supplier invoices via ECM
• Most expensive item shown as invoice description

3.8

• Improved cable pricing for different supplier formats (Sonepar vs Kluxen/Witte)
• Automatic ring size detection from product names (Ri100, Tr500, etc.)
• EAN auto-update from ZUGFeRD invoices with automatic barcode type detection

3.7

• GlobalNotify integration for import notifications

3.5

• Automatic cron import from watch folder and IMAP

3.0

• Datanorm integration for article prices

1.0

• Initial release

License

GPLv3 or (at your option) any later version. See file COPYING for more information.

Author

Eduard Wisch - data IT solution