Schnittstellen / API

Receipts Space bietet mehrere Schnittstellen, um Belege und Dokumente automatisiert zu erzeugen, zu importieren, weiterzuverarbeiten und wieder zu exportieren.

Überblick

Import

• Dateisystem - Dateien und Ordner per Drag & Drop, über Datei > Öffnen oder als Kommandozeilen-Parameter. Unterstützt werden PDF, Bilder (JPEG, PNG, HEIC …), E-Mails (EML) sowie JSON-Dateien im unten beschriebenen Format.
• Ordnerüberwachung - einmalig konfigurierte Ordner (z. B. Scanner-Ausgabe oder iCloud-Ordner) werden dauerhaft beobachtet; neue Dateien werden automatisch importiert.
• JSON-Import - strukturierter Import ganzer Dokumente inklusive Asset, Beträgen, Kategorien, Kontakten und Tags.
• URL-Schema - Aufruf aus Browser, Mail oder Shortcuts über receipts-space://.... Ideal, um aus Web-Portalen direkt in die Library zu importieren.

Export

• Drag & Drop / Zwischenablage - ausgewählte Dokumente lassen sich als PDF, als Originaldatei oder im JSON-Format (gleiches Schema wie der JSON-Import) in andere Apps übernehmen.
• Datei > Exportieren - Stapel-Export in einen Ordner, inklusive optionaler Metadaten-Sidecars.
• AppleScript export-Kommando - programmatischer Export einzelner oder gefilterter Dokumente. GitHub holtwick/receipts-api

Automatisierung

• AppleScript - vollständige Automatisierung der App aus Skripten, Automator oder Shortcuts heraus. Das Terminologie-Lexikon ist direkt im Skripteditor von macOS einsehbar. Beispiele unter GitHub holtwick/receipts-api.
• Direkter Bibliothekszugriff - die Bibliothek ist ein offenes Dokument-Bundle und kann von externen Tools gelesen und geschrieben werden. Details zum Aufbau stehen in der technischen Dokumentation und GitHub holtwick/receipts-space.

Bei Rückfragen hilft unser Support-Team gerne weiter.

Logfiles einsehen

Beim Arbeiten mit den Schnittstellen ist ein Blick ins Log oft der schnellste Weg zur Ursachenanalyse. Im Hauptmenü der App unter Hilfe:

• Normal: Eintrag Support & Feedback - öffnet das Feedback-Formular.
• Mit gedrückter ALT-Taste: Der Eintrag wechselt auf Open Log Files und öffnet den Log-Ordner im Finder.

Direkter Pfad:

~/Library/Logs/Receipts/de_holtwick_mac_homebrew_Receipts2.log

In der Mac-App-Store-Version weicht der Bundle-Identifier im Dateinamen leicht ab.

URL-Schema receipts-space://import

Importiert eine einzelne PDF-Datei, deren Binärdaten direkt in der URL übergeben werden. Aufrufbar aus Browser, Mail, Shortcuts oder beliebigen anderen Apps.

Beispiel:

receipts-space://import?content=JVBERi0xLjQKJeLjz9MKCg...

Hinweise:

• Der Inhalt wird immer als PDF behandelt (UTI com.adobe.pdf). Andere Dateitypen werden von diesem Endpunkt derzeit nicht unterstützt - für Bilder, E-Mails oder strukturierte Daten bitte den JSON-Import oder eine Datei-basierte Übergabe verwenden.
• Fehlt content oder lässt sich der Wert nicht dekodieren, wird der Aufruf stillschweigend verworfen.
• Die Länge einer URL ist systembedingt begrenzt (typisch einige MB über open, deutlich weniger in Browsern). Für größere Dateien ist ein Datei-basierter Import stabiler.
• Der Import läuft als manuelle Session durch die reguläre Import-Pipeline; Dublettenerkennung, Ordnerüberwachung etc. verhalten sich wie beim Datei-Import.
• Weitere Metadaten (Titel, Kategorie, Beträge, id usw.) lassen sich über dieses Schema nicht mitgeben. Wer Metadaten setzen möchte, nutzt den JSON-Import (z. B. über eine .receipts-import-Datei oder ein .receipts-package).

Dateiendungen

Receipts Space registriert sich bei macOS für eine Reihe von Dateiendungen. Beim Öffnen einer solchen Datei (Doppelklick, Drag & Drop auf das App-Icon, open im Terminal) reagiert die App entsprechend der Endung. Hier die relevantesten:

Aufbau eines .receipts-package

Ein .receipts-package ist ein Ordner-Bundle mit folgendem Aufbau:

Meinpaket.receipts-package/
├── Info.json
└── Files/
    ├── rechnung-1.pdf
    └── scan-2.jpg

Info.json enthält das Manifest:

{
  "note": "Optionaler Hinweis, wird allen Dokumenten als Notiz angefügt.",
  "files": [
    {
      "filename": "rechnung-1.pdf",
      "title": "Hotelrechnung Berlin",
      "url": "https://example.com/invoice/42"
    },
    {
      "filename": "scan-2.jpg"
    }
  ]
}

• filename verweist auf eine Datei innerhalb von Files/.
• title (optional) wird als vorgeschlagener Titel übernommen, z. B. ein Seitentitel aus Safari.
• url (optional) wird als Quell-URL im Dokument gespeichert; kann auch allein verwendet werden (ohne filename), dann wird die URL direkt importiert.

Automatisches Aufräumen: Präfix ReceiptsMove-

Datei­namen, die mit ReceiptsMove- beginnen, werden nach erfolgreichem Import automatisch in den Papierkorb verschoben. Gedacht war der Mechanismus ursprünglich für Mail.app-Temporärdateien, er funktioniert aber generisch:

ReceiptsMove-rechnung.pdf

Schlägt das Verschieben in den System-Papierkorb fehl (z. B. bei Netzlaufwerken), wird als Fallback ein Ordner .ReceiptsTrash neben der Datei angelegt und sie dort abgelegt.

JSON-Import in Receipts Space

Receipts Space kann Dokumente aus JSON-Dateien importieren. Dieses Dokument beschreibt das unterstützte Format und alle erkannten Felder.

Aufruf

Ein JSON-Import wird ausgelöst, sobald eine Datei mit UTI public.json an die App übergeben wird (Drag & Drop, Ordnerüberwachung, File > Open, AppleScript, URL-Schema usw.). Die Datei wird in import-from-url.swift erkannt und an den JSON-Importer in import-from-json.swift weitergereicht.

Die eigentliche Zuordnung der JSON-Felder auf ein DocumentSchema erfolgt in document-json-read.swift. Alle gültigen Schlüssel sind als Enum in document-json-keys.swift definiert.

Struktur der JSON-Datei

Die JSON-Datei enthält entweder ein einzelnes Dokument-Objekt oder ein Array von Dokument-Objekten. Arrays werden automatisch aufgespalten, jedes Element wird als eigenes Dokument importiert.

[
  { "id": "…", "title": "…", … },
  { "id": "…", "title": "…", … }
]

Felder

Identifikation

Flags

Datum

Datumsfelder akzeptieren entweder ein natives Date-Objekt oder einen ISO-8601-String.

Beträge

Beträge werden in zwei Blöcken verwaltet: amountsOriginal (Originalwährung des Belegs) und amounts (umgerechnet in die Default-Währung der Bibliothek).

"amountsOriginal": {
  "currency": "USD",
  "gross": 123.45,
  "tax": 19.70,
  "taxDetails": [
    { "percent": 19, "value": 19.70 }
  ]
},
"amounts": {
  "gross": 115.12,
  "exchangeRate": 0.9325
}

Relationen

IBAN

Assets (Dateianhang)

Das eigentliche Beleg-Dokument wird als asset angehängt, optional zusätzlich das Original unter assetOriginal (z. B. das unveränderte Scan-PDF vor OCR).

"asset": {
  "name": "rechnung.pdf",
  "uti": "com.adobe.pdf",
  "mime": "application/pdf",
  "data": "<base64>"
}

Die Quellen werden in der angegebenen Reihenfolge probiert; die erste, die nicht-leere Daten liefert, wird verwendet. Bei PDF-Assets wird zusätzlich der Textinhalt extrahiert, wenn text nicht bereits gesetzt ist.

Export/Import-Roundtrip

Der JSON-Export eines Dokuments (Drag & Drop, Zwischenablage, AppleScript export-Kommando) verwendet dasselbe Schema wie der Import und ist damit direkt wieder importierbar. Exportierte und importierte Felder teilen sich in der Implementierung das gleiche Schlüssel-Enum, so dass ein Roundtrip Export → Import die Daten verlustfrei zurückbringt. Assets werden beim Export wahlweise als url (interner Webserver), fileurl oder path referenziert; beim Import wird die erste verfügbare Quelle genutzt.

Bestehende Dokumente aktualisieren

Ein JSON-Import mit einer id, die bereits in der Bibliothek existiert, überschreibt die darin angegebenen Felder des vorhandenen Dokuments - es handelt sich also zugleich um eine Update-Schnittstelle. Nicht erwähnte Felder bleiben unverändert.

Standardmäßig wird das Dokument dabei als Duplikat markiert (Status “Duplikat” in der Liste). Für ein stilles Update ohne Markierung:

{
  "id": "…bestehende-uid…",
  "title": "Neuer Titel",
  "notes": "Ergänzte Notiz",
  "onDuplicateFlag": false
}

Mit onDuplicateIncludeKeys lässt sich das Update auf einzelne Felder beschränken; onDuplicateExcludeKeys bewirkt das Gegenteil. Details dazu im nächsten Abschnitt.

Duplikat-Handling

Ist bereits ein Dokument mit derselben id in der Bibliothek vorhanden, greift die Duplikat-Logik:

• Dokument war endgültig gelöscht: wird wieder hergestellt und wie ein Neu-Import behandelt.
• Dokument war im Papierkorb (archiviert): wird als Duplikat markiert. Verhalten steuerbar über folgende Keys.

Das Feld dateAdded wird bei Duplikaten nie übernommen, damit das ursprüngliche Anlage-Datum erhalten bleibt.

Beispiel

{
  "title": "Büromaterial",
  "via": "scan",
  "reference": "RE-2025-00123",
  "date": "2025-11-14",
  "datePayment": "2025-11-18",
  "isConfirmed": true,
  "amountsOriginal": {
    "currency": "EUR",
    "gross": 42.80,
    "taxDetails": [
      { "percent": 19, "value": 6.83 }
    ]
  },
  "category": "Büro",
  "contact": { "title": "Müller GmbH" },
  "tags": ["Q4", "Verbrauchsmaterial"],
  "iban": "DE89370400440532013000",
  "asset": {
    "path": "re-2025-00123.pdf",
  }
}