Belegimport

Automatischer Import von Belegen (Rechnungen, Gutschriften) aus verschiedenen Quellen und Weiterleitung per SMTP an Buchhaltungssoftware (z.B. Buchhaltungsbutler).

Features

• Scan-Upload: PDF hochladen, automatische Trennung per QR-Code-Trennseiten
• IMAP: Automatischer Abruf von Belegen aus Email-Postfachern
• SMB/Netzlaufwerk: Automatischer Abruf von Belegen aus Netzwerkordnern
• FTP / SFTP: Automatischer Abruf von Belegen via FTP (passiv, unverschluesselt) oder SFTP (SSH)
• Amazon Business: Automatischer Abruf von Amazon-Rechnungen per API
• Eingangs-/Ausgangsbelege: Getrennte Import-Adressen fur Einkauf und Verkauf
• Scheduler: Automatischer Abruf in konfigurierbaren Intervallen
• Verarbeitungslog: Ubersicht aller importierten Belege mit Status

Technologie

• Python 3.12, FastAPI, Jinja2, SQLite (aiosqlite)
• Docker / docker-compose
• Playwright (optional, fur Amazon Browser-Automation als Fallback)

Installation

Docker (empfohlen)

git clone <repository-url>
cd lex-office-belegimport-mail
sudo docker-compose up --build -d

Die Webanwendung ist erreichbar unter: http://localhost:8081

Konfiguration

Alle Einstellungen werden uber die Weboberflache vorgenommen:

1. Einstellungen (/settings): SMTP-Server, IMAP, SMB, Import-Emailadressen
2. Plattformen (/platforms): Amazon Business API-Zugangsdaten
3. Scan-Upload (/): Manueller PDF-Upload mit Belegart-Auswahl

---

Amazon Business API Einrichtung

Die Amazon-Integration nutzt die offizielle Amazon Business API (Reconciliation + Document API) um Rechnungen automatisch abzurufen. Kein Browser-Login, keine CAPTCHAs, vollautomatisch.

Voraussetzungen

• Amazon Business Konto (mit Business Prime)
• Zugang zum Amazon Solution Provider Portal

Schritt 1: Als Entwickler registrieren

1. Offne das Solution Provider Portal
2. Wahle "Private seller applications" (fur eigene Integrationen)
3. Wahle "Erstellen Sie Anwendungen, die SP-APIs verwenden"
4. Fulle die Unternehmensdaten aus (Name, Handelsregisternummer, Adresse)
5. Verifiziere per SMS

Schritt 2: Rollen auswahlen

Wahle folgende Rollen:

• Abgleichen von Business-Einkaufen (Reconciliation API)
• Amazon Business-Bestellung (Business Orders API)

Schritt 3: Sicherheitskontrollen

Beantworte alle Sicherheitsfragen mit "Ja".

Bei den Textfeldern:

• Externe Parteien: Keine. Die Daten werden ausschliesslich intern fur die eigene Buchhaltung verwendet.
• Externe Quellen: Keine.

Schritt 4: App registrieren

Nach der Freischaltung (kann einige Tage dauern):

1. Im Developer Central: "+ Neuen App-Client hinzufugen"

2. Einstellungen:

   • App-Name: Beleg import (oder eigener Name)
   • API-Typ: SP-API
   • App-Typ: Produktion
   • Amazon Business: angehakt
   • Verkaufer: nicht angehakt
   • Rollen: Abgleichen von Business-Einkaufen + Amazon Business-Bestellung
   • RDT: Nein
   • OAuth-Anmeldungs-URI: https://ihre-domain.de/api/amazon-oauth-callback
   • OAuth-Umleitungs-URI: https://ihre-domain.de/api/amazon-oauth-callback

3. Nach dem Speichern: "Anmeldedaten fur Login mit Amazon" -> "Anzeigen"

   • Notiere Client-ID (amzn1.application-oa2-client.xxxxx)
   • Notiere Client-Sicherheitsschluessel (amzn1.oa2-cs.v1.xxxxx)

4. Die App-ID (amzn1.sp.solution.xxxxx) steht in der App-Ubersicht unter dem App-Namen

Hinweis: Die OAuth-Umleitungs-URI muss eine echte Domain mit Top-Level-Domain sein. localhost und .local Domains werden von Amazon nicht akzeptiert. Die URI muss nicht offentlich erreichbar sein - Amazon leitet nur den Browser des Benutzers dorthin weiter.

Fehler SPSA0404: Falls beim Autorisieren der Fehler "Keine unterstuetzte Geschaeftseinheit" erscheint, muss die Autorisierung uber den OAuth-Flow (Website) statt uber Self-Authorization erfolgen. Der Belegimport unterstutzt dies automatisch.

Schritt 5: Im Belegimport konfigurieren

1. Offne die Plattformen-Seite im Belegimport
2. Setze Abruf-Modus auf "API (empfohlen)"
3. Trage ein:
   • App-ID: amzn1.sp.solution.xxxxx
   • Client-ID: amzn1.application-oa2-client.xxxxx
   • Client-Sicherheitsschluessel: Der Secret-Wert
4. Einstellungen speichern
5. Klicke "Bei Amazon autorisieren"
6. Melde dich bei Amazon an und erlaube den Zugriff
7. Kopiere den spapi_oauth_code (oder die ganze URL) aus der Browser-Adressleiste
8. Trage den Code im Belegimport ein und klicke "Token tauschen"
9. Status sollte auf "API autorisiert" wechseln

Schritt 6: Rechnungen abrufen

• Manuell: Klicke "Jetzt Rechnungen abrufen"
• Automatisch: Aktiviere den Scheduler unter Einstellungen (z.B. alle 60 Minuten)

Die Rechnungen werden als PDF per SMTP an die konfigurierte Eingangsbeleg-Adresse gesendet. Bereits abgerufene Rechnungen werden automatisch ubersprungen.

OAuth Redirect URI (lokale Installation)

Da Amazon keine localhost-URIs akzeptiert, gibt es zwei Optionen:

Option A: Eigene Domain verwenden (empfohlen)

Trage eine echte Domain ein (z.B. https://ihre-domain.de/api/amazon-oauth-callback). Nach der Amazon-Autorisierung leitet der Browser dorthin weiter - die Seite ladt nicht, aber der Auth-Code steht in der URL-Leiste. Diesen Code im Belegimport eintragen.

Option B: /etc/hosts Eintrag

Falls der Server lokal erreichbar sein soll:

# In /etc/hosts eintragen:
127.0.0.1  app.belegimport.de

Dann in der Amazon App als Redirect URI eintragen: https://app.belegimport.de/api/amazon-oauth-callback

Achtung: Amazon pruft ob die Domain eine Top-Level-Domain hat. .local funktioniert nicht, aber .de schon.

Umgebungsvariablen

In docker-compose.yml:

environment:
  - OAUTH_REDIRECT_BASE=https://ihre-domain.de  # Muss zur Amazon App passen

---

Eingangs- und Ausgangsbelege

Der Belegimport unterscheidet zwischen:

• Eingangsbelege (Einkauf): Rechnungen die Sie von Lieferanten erhalten
• Ausgangsbelege (Verkauf/Gutschrift): Rechnungen die Sie an Kunden senden

Fur beide Typen konnen separate Import-Emailadressen konfiguriert werden (z.B. fur Buchhaltungsbutler). Amazon-Rechnungen werden automatisch als Eingangsbelege klassifiziert.

Bei IMAP und SMB konnen jeweils getrennte Quell- und Verarbeitungsordner fur Eingangs- und Ausgangsbelege konfiguriert werden.

Beim Scan-Upload kann die Belegart per Radio-Button ausgewahlt werden.

---

Verarbeitungslog

Unter /log werden alle verarbeiteten Belege angezeigt mit:

• Zeitpunkt, Betreff, Absender
• Belegart (Eingang/Ausgang)
• Anzahl Anhange
• Status (OK/Fehler)
• Fehlermeldung (falls vorhanden)
• SMTP-Protokoll (anzeigbar)

---

Lizenz

Privates Projekt.