Hacker-Software
/
belege-import
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
belege-import/README.md

6.7 KiB
Raw Blame History

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
  • 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

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.