rechnungsapi.de Dokumentation

Ihre Ordner

Sie legen Dateien nur in In/ ab. Die anderen drei Ordner füllen sich automatisch.

Wie verbinde ich mich? Über den Nextcloud-Client oder per SFTP – siehe Verbindung zu Ihrem Ordner.

So funktioniert es

1. Legen Sie eine Rechnung in In/ ab – als PDF oder als PNG-, JPEG- oder TIFF-Bild.
2. Die Datei verschwindet aus In/ und wird mit Zeitstempel im Namen nach Processed/ verschoben (z. B. 2026-09-23_09-41-12_IhrOrdner_Rechnung-1234.pdf). Das bedeutet: Sie wird gerade verarbeitet.
3. Die Rechnungsdaten werden ausgelesen und geprüft – Beträge, Steuersätze und Summen werden mit Ihrem Dokument abgeglichen.
4. Bei Erfolg: Die ZUGFeRD-Rechnung erscheint in Archive/, mit -zugferd im Namen (Rechnung-1234.pdf → Rechnung-1234-zugferd.pdf). Das Ergebnis ist immer ein PDF, auch wenn Sie ein Bild abgelegt haben.
5. Bei einem Problem: Die Datei wird nach Error/ verschoben und Sie erhalten eine E-Mail mit der Begründung.

Wir löschen Ihr Original nie – es bleibt bei Erfolg in Processed/, bei einem Fehler in Error/.

Was verarbeitet wird

• PDF-Dateien sowie Bilder im Format PNG, JPEG oder TIFF (.pdf, .png, .jpg, .jpeg, .tif, .tiff). Andere Dateien – z. B. Word-Dateien, HEIC-Fotos, ZIP-Archive – und Unterordner werden ignoriert: Sie bleiben in In/ liegen, und Sie erhalten dazu keine Fehlermeldung.
• Bilder müssen eine sehr gute Qualität haben. Der Rechnungstext muss scharf und gut lesbar sein – gut ausgeleuchtet, gerade ausgerichtet, nicht abgeschnitten und in hoher Auflösung. Handschriftliche Rechnungen werden nicht empfohlen, da sie oft nicht zuverlässig gelesen werden können. Verwenden Sie nach Möglichkeit das Original-PDF aus Ihrer Rechnungssoftware.
• Eine Datei ergibt eine E-Rechnung. Eine Datei mit mehreren Rechnungen wird als eine einzige Rechnung behandelt.
• Älteste Datei zuerst. Mehrere Dateien werden nacheinander verarbeitet, in der Reihenfolge, in der Sie sie abgelegt haben.

Wenn eine Rechnung nicht konvertiert werden kann

Die Datei wird nach Error/ verschoben, Sie erhalten eine E-Mail, und es gibt keinen automatischen neuen Versuch. Die E-Mail nennt das Problem und die Details – fehlende Pflichtangaben werden einzeln mit ihrer Norm-Nummer aufgeführt, z. B. „BT-31 — USt-IdNr. des Verkäufers“. Außerdem enthält sie eine Referenz wie ZAPI-151431; geben Sie diese bei Rückfragen an den Support an.

Für einen neuen Versuch legen Sie die korrigierte Datei wieder in In/ ab. Kopieren Sie sie dazu aus Error/, statt Dateien zwischen den Ordnern zu verschieben.

Datenschutz

Alle Ihre Rechnungsdaten werden ausschließlich auf unseren Servern in Deutschland gespeichert und verarbeitet – nichts verlässt sie. Ihre Dateien liegen in Ihrem eigenen Ordner, auf den Sie selbst Zugriff haben: das Original in Processed/, das Ergebnis in Archive/ bzw. Error/. Sie können Ihre Dateien jederzeit über Nextcloud löschen oder den Support mit der Löschung beauftragen. Per SFTP ist Löschen bewusst gesperrt, damit keine Software fertige Rechnungen versehentlich entfernt.

FAQ

Fragen? Antworten Sie auf die Fehler-E-Mail oder schreiben Sie an support@rechnungsapi.de – idealerweise mit der Referenz aus der E-Mail.

Verbindungsdaten

Schlüssel oder Passwort?

Wir empfehlen einen SSH-Schlüssel: Er lässt sich nicht erraten, und der Teil, den Sie uns senden, ist unkritisch, falls er verloren geht. Unterstützt Ihre Software nur Passwörter, fordern Sie beim Support ein Passwort an – Sie erhalten es getrennt vom Benutzernamen. Der rechnungsapi Sync-Agent verwendet immer einen Schlüssel.

ssh-keygen -t ed25519 -f ~/.ssh/rechnungsapi

New-Item -ItemType Directory -Force "$env:USERPROFILE\.ssh" | Out-Null

ssh-keygen -t ed25519 -f "$env:USERPROFILE\.ssh\rechnungsapi"

cat ~/.ssh/rechnungsapi.pub

Was Sie in welchem Ordner dürfen

Per SFTP lassen sich Dateien nicht löschen, überschreiben oder umbenennen, und in In/ werden nur PDF-, PNG-, JPEG- und TIFF-Dateien angenommen. Liegt in In/ bereits eine Datei mit demselben Namen, laden Sie sie unter einem anderen Namen hoch.

So arbeitet der Sync-Agent

• Er läuft dauerhaft von selbst. Nach der Einrichtung startet Ihr Rechner ihn bei jeder Anmeldung im Hintergrund (als macOS-Launch-Agent) und startet ihn nach einem Absturz neu. Es gibt kein Fenster und nichts, was Sie von Hand starten müssen.
• Ihr Rechner muss eingeschaltet und angemeldet sein. Dateien, die Sie ablegen, während er aus ist oder schläft, werden übertragen, sobald er wieder läuft.
• Er verbindet sich nur mit unserem Server: Bei jeder Verbindung prüft er den Server-Fingerprint und verweigert die Verbindung, falls er sich geändert hat. Alles, was er tut, steht in agent.log.

Was Sie von uns erhalten

Sobald Ihr Schlüssel eingerichtet ist, sendet Ihnen der Support per E-Mail eine ZIP-Datei, die für Ihr Konto vorbereitet ist:

Es enthält keinen Schlüssel und kein Passwort – Ihr privater Schlüssel liegt nur auf Ihrem Rechner.

Einrichtung auf dem Mac

Unter Windows? Nutzen Sie vorerst einen SFTP-Client oder Ihre eigene Software.

Sie benötigen: einen Mac, Ihren Benutzernamen und die ZIP-Datei vom Support. Öffnen Sie das Terminal (⌘ + Leertaste → „Terminal“), fügen Sie jeden Befehl ein, drücken Sie Enter und warten Sie, bis er fertig ist.

nc -vz sftp.prod.finbc.com 2022

python3 --version

mv ~/Downloads/rechnungsapi-agent ~/Rechnungsapi-Agent

ls ~/Rechnungsapi-Agent

python3 ~/Rechnungsapi-Agent/rechnungsapi_sync.py --config ~/Rechnungsapi-Agent/agent.ini --once

python3 -c "import plistlib,os;h=os.path.expanduser('~');p=h+'/Library/LaunchAgents/de.rechnungsapi.sync.plist';os.makedirs(os.path.dirname(p),exist_ok=True);plistlib.dump({'Label':'de.rechnungsapi.sync','ProgramArguments':['/usr/bin/python3',h+'/Rechnungsapi-Agent/rechnungsapi_sync.py','--config',h+'/Rechnungsapi-Agent/agent.ini'],'RunAtLoad':True,'KeepAlive':True,'ThrottleInterval':60,'StandardErrorPath':h+'/Library/Logs/rechnungsapi-sync.log'},open(p,'wb'));print('Autostart OK')"

launchctl load -w ~/Library/LaunchAgents/de.rechnungsapi.sync.plist

launchctl list | grep rechnungsapi

open ~/Rechnungsapi

Wo was liegt nach der Einrichtung (Mac)

Eigener Ordner statt ~/Rechnungsapi

Öffnen Sie vor Schritt 5 die Einstellungen und ändern Sie nur die Zeile base = … auf den Pfad Ihres Ordners (ziehen Sie den Ordner aus dem Finder ins Terminal, um den Pfad zu sehen). In, Processed, Archive und Error werden darin angelegt, falls sie fehlen. Nicht geeignet sind Schreibtisch, Dokumente, Downloads, iCloud Drive und Dropbox – macOS blockiert dort Hintergrundprogramme, und Sync-Dienste verursachen Konflikte.

open -e ~/Rechnungsapi-Agent/agent.ini

Im Alltag

• Legen Sie eine Rechnung in In/ ab. Nach etwa einer Minute wandert sie nach Processed/ – sie ist übertragen. Die ZUGFeRD-Rechnung erscheint in der Regel wenige Minuten später in Archive/.
• Ihr Mac muss eingeschaltet und angemeldet sein. Dateien, die Sie ablegen, während er aus ist, werden später übertragen.
• Sichern Sie Archive/ mit Ihrem Backup (z. B. Time Machine). Die gesetzliche Aufbewahrung Ihrer Rechnungen (GoBD) liegt bei Ihnen.

Pausieren, fortsetzen, deinstallieren (Mac)

Beim Deinstallieren bleibt Ihr Rechnungsordner erhalten.

Sie nutzen den Sync-Agenten? Senden Sie uns die letzten Zeilen seines Protokolls – sie enthalten keine Passwörter. Mac: tail -20 ~/Rechnungsapi/agent.log

1. Freischaltung anfragen: Der E-Mail-Versand ist ein kostenpflichtiger Zusatzservice im Enterprise-Paket. Schreiben Sie an support@rechnungsapi.de, um ihn für Ihr Konto freischalten zu lassen.
2. Absenderdomain authentifizieren: Hinterlegen Sie einen DKIM-CNAME- und einen SPF-TXT-Eintrag bei Ihrem Domain-Provider. Das ist eine einmalige Einrichtung und dauert etwa fünf Minuten.
3. Versenden: Ab dann ergänzen Sie eine Erzeugungs-Anfrage um das transport-Objekt oder nutzen den Endpunkt delivery. Die Details stehen in der API-Dokumentation.

Der Versand läuft über die Mailinfrastruktur unseres Mass-Mailing-Partners saas.do. Die DNS-Einträge berechtigen ihn, im Namen Ihrer Domain zu versenden.

Für Entwickler: das transport-Objekt, delivery und sendEmailWithZugferdData in der API-Dokumentation.