196 lines
6.7 KiB
Markdown
196 lines
6.7 KiB
Markdown
# 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)
|
|
|
|
```bash
|
|
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](https://solutionproviderportal.amazon.com/)
|
|
|
|
### Schritt 1: Als Entwickler registrieren
|
|
|
|
1. Offne das [Solution Provider Portal](https://solutionproviderportal.amazon.com/)
|
|
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:
|
|
|
|
```bash
|
|
# 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`:
|
|
|
|
```yaml
|
|
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.
|