Diese Dokumentation richtet sich an Entwickler und Entwicklerinnen von Unternehmen, die Releaf zum Ausstellen von digitalen Kassenbelegen nutzen möchten.
Releaf befindet sich in einer DEMO-Phase und wird derzeit nicht kommerziell eingesetzt. Bitte kontaktieren Sie den Releaf-Support bei Interesse für weitere Informationen.
Grundsätzliches
Zur Verwendung der API benötigen Sie einen API-Schlüssel. Kontaktieren Sie zur Beantragung den Releaf-Support.
Ihre ausgestellten Releaf-Belege werden Ihnen monatlich in Rechnung gestellt. Für Fragen zur Preisgestaltung und Abrechnung, Kontaktieren den Releaf-Support.
Beleg-Datei
Mit Releaf ausgestellte Kassenbelege müssen im Format .pdf sein. Ihre Belege sollten immer einen weissen (#FFFFFF) Hintergrund und dunkle, kontrastreiche Schrift enthalten.
Releaf ist flexibel hinsichtlich dem Format der Belege. Sie müssen für Releaf-Belege grundsätzlich kein separates Layout erstellen. Falls verfügbar, sind Belege im DIN-A4-Format bei der Verwendung von Releaf grundsätzlich über solchen im Thermopapierrollen-Format zu bevorzugen.
Beachten Sie die folgenden Richtlinien abhängig vom Papierformat:
Belege in Formaten, die auf Papierblätter ausgelegt sind
Skalieren Sie Ihr PDF auf das DIN-A4-Format. Fügen Sie dazu an genau zwei gegenüberliegenden Seiten weisse Leerräume ein, falls nötig. Ihr PDF darf mehrere Seiten umfassen. Fügen Sie nicht mehrere Blätter auf eine Seite zusammen.
Lange Belege, die auf Thermopapierrollen ausgelegt sind
Ihr Beleg sollte normalerweise aus einer PDF-Seite bestehen. Falls Ihr physischer Beleg in mehreren Teilen gedruckt werden würde, die auseinandergeschnitten wären (Beispielsweise Kassenbeleg und EC-Beleg), teilen Sie diese Teile auf einzelne Seiten im PDF auf («Schnitt» = Seitenumbruch). Fügen Sie keine Ränder ausserhalb Ihres Belegs hinzu. Skalieren Sie die Belege, sodass die Breite jeder Seite genau 210 mm beträgt. Die Höhe der Seiten darf variieren, ähnlich wie die Länge dieser Belege beim Drucken variiert.
Fügen Sie Ihren Belegen keine Buttons und andere Elemente hinzu, die in einer gedruckten Version nicht nutzbar wären.
Verschlüsselung
Die PDF-Belegdatei muss von Ihrem System verschlüsselt werden, bevor Sie die Datei übermitteln. So kann die Ende-zu-Ende-Verschlüsselung von Releaf gewährleistet werden.
- Algorithmus: AES-GCM, 256 Bit Key
- Schlüssel (Key): 32 zufällige Bytes
- Initialisierungsvektor (IV): 12 zufällige Bytes
- Additional Authenticated Data (AAD):
'releaf/enc-v1' - Tag: 128 Bit (16 Bytes)
Vermeiden Sie unsichere Zufallsalgorithmen wie
Math.randomzur Erstellung von Key und IV. Nutzen Sie stattdessen beispielsweise Web CryptogetRandomValues.
Legen Sie anschliessend eine Datei mit dem Suffix '.enc' an, mit folgendem Aufbau:
IV (12 Bytes) || Ciphertext || GCM-Tag (16 Bytes)Der Dateiname ist irrelevant (frei wählbar) und wird vom Server verworfen. Es zählt nur der Suffix '.enc'. Ihre verschlüsselte Datei darf maximal 512 KB gross sein.
Um die Dateigrösse Ihrer Belege zu reduzieren, wandeln Sie darin enthaltene Bilder (zb. Wortmarken) möglichst in SVG-Grafiken um, oder reduzieren Sie die DPI der Bilder.
Hochladen
Laden Sie den Beleg nach der Verschlüsselung über den folgenden Endpoint hoch:
POST https://releaf.dylanwettstein.com/wp-json/releaf/v1/receipts/uploadAuthentifizieren Sie sich im Header mit Ihrem API-Key:
Header X-API-Key: <key>Übermitteln Sie folgenden Body als 'multipart/form-data' in Ihrer API-Anfrage:
file: Verschlüsselte .enc-Datei (binary)hash: Hex oder Base64 des SHA-256-Hash des unverschlüsselten PDFexpiration: Ein Ablaufdatum für Ihren Beleg (optional, ISO‑Datum YYYY-MM-DD)
Senden Sie niemals den Key aus der Verschlüsselung Ihres Beleges an den Server.
Releaf-Belege werden automatisch vom Server gelöscht, wenn sie ablaufen. Das Ablaufdatum wird standardmässig auf zwei Jahre nach dem Ausstellen des Belegs gesetzt.
Setzen Sie keinen expiration Header, es sei denn, Ihr Beleg enthält Garantieberechtigungen, Gutschriften oder ähnliche Eigenschaften, die länger als zwei Jahre lang relevant sind.
Die standardmässige Ablauffrist von zwei Jahren kann nicht verkürzt werden.
Server-Response:
201 Created
{ "uuid": <uuid> }Die Response enthält bei einer erfolgreichen Anfrage eine UUID. Diese ist zentral für die weitere Verarbeitung Ihres Belegs.
Beschreibungen der Fehlercodes
| Statuscode | Error Code | Beschreibung |
|---|---|---|
401 (Unauthorized) | missing_api_key | X-API-Key Header fehlt. |
401 (Unauthorized) | invalid_api_key | Ungültiger/falscher API-Key. |
403 (Forbidden) | vendor_inactive | API-Key wurde gefunden, aber ist nicht aktiv. Support kontaktieren. |
400 (Bad Request) | missing_file | Datei-Upload fehlt oder ist ungültig. |
413 (Payload Too Large) | file_too_large | Datei grösser als 512 KB (hartes Limit). |
400 (Bad Request) | missing_hash | Body-Parameter hash fehlt. |
400 (Bad Request) | invalid_hash_format | hash nicht als Hex(64) oder Base64 (32 Byte) parsebar. |
500 (Internal Server Error) | storage_unwritable | Erneut versuchen. Support kontaktieren. |
500 (Internal Server Error) | store_failed | Erneut versuchen. Support kontaktieren. |
500 (Internal Server Error) | db_insert_failed | Erneut versuchen. Support kontaktieren. |
Übertragen
Nachdem Sie Ihren Beleg erfolgreich hochgeladen haben, übertragen Sie ihn an Ihren Kunden oder Ihre Kundin.
Bauen Sie einen JSON-Payload nach folgender Struktur auf:
{
"v": int,
"uuid": string,
"key": string,
"meta": {
"category": string,
"type": string,
"country": string,
"channel": string,
"currency": string,
"amount_cents": int
}
}Erklärungen zu den JSON-Keys
v
Die Version Ihrer JSON-Struktur. Lautet derzeit immer 1.
uuid
Die UUID, die Sie beim Hochladen Ihres Belegs vom Server erhalten haben.
key
Base64url des 32-Byte-Keys, der zur Verschlüsselung Ihres Belegs verwendet wurde.
meta
category
Branche, die den Beleg ausgestellt hat. Folgende Werte sind erlaubt:
| Wert (Code) | Label (UI) |
|---|---|
| gastronomy | Gastronomie |
| shopping | Einkaufen |
| services | Dienstleistungen |
| travel | Reisen |
| entertainment | Unterhaltung |
| health | Gesundheit |
| education | Bildung |
| finance | Finanzen |
| other | Sonstiges |
type
Art des Belegs. Folgende Werte sind erlaubt:
| Wert (Code) | Label (UI) |
|---|---|
| payment | Zahlungsbeleg |
| invoice | Rechnung |
| return | Retourenbeleg |
| warranty | Garantieschein |
| voucher | Gutschein |
| delivery | Lieferschein |
| estimate | Angebot |
| service | Servicebericht |
| other | Sonstiger Beleg |
country
Land, in dem der Beleg ausgestellt wurde, nach ISO-3166-1 alpha-2 (zb. 'CH' oder 'DE').
channel
Kanal, über der die Transaktion des Belegs ausgeführt wurde. Folgende Werte sind erlaubt:
| Wert (Code) | Label (UI) | Beschreibung |
|---|---|---|
| online | Online | Online-Verkäufe |
| in-person | In Person | Verkäufe in physischen Verkaufsstellen |
| subscription | Abonnement | Automatisch verlängerte Abonnements |
currency
Währung, in der der Beleg ausgestellt wurde, nach ISO-4217 alpha-3 (zb. 'CHF' oder 'EUR').
amount_cents
Totalbetrag des Belegs in der kleinsten Einheit der Währung, zb. Rappen oder Cents.
Alle Angaben sind erforderlich. Einzige Ausnahmen sind 'currency' und 'amount_cents'. Diese sind nur obligatorisch, falls 'type' einer der folgenden Werte trägt: payment, invoice, voucher.
Bei allen anderen Werten ist die Angabe freiwillig, wobei entweder keine der beiden Felder oder beide Felder gesetzt werden müssen. Die Angabe von nur einem Feld ist unzulässig.
Codieren Sie diesen JSON-Payload anschliessend in Base64url.
In einem letzten Schritt generieren Sie einen QR-Code mit dem folgenden Payload:
https://releaf.dylanwettstein.com/r/?qr=<base64url-json>Der QR-Code sollte niedrige Fehlerkorrektur (ECC Low) aufweisen und muss in der Farbe #A20707 auf weissem #FFFFFF Hintergrund gezeichnet sein.
Präsentieren Sie diesen QR-Code Ihrem Kunden oder Ihrer Kundin. Falls Sie den QR-Code online teilen, senden Sie zusätzlich die im QR-Code hinterlegte URL (zb. als Button), sodass Ihr Kunde oder Ihre Kundin den Beleg auch mühelos auf dem selben Gerät hinzufügen kann wie der Code angezeigt wird.
Durch das Öffnen der im QR-Code hinterlegten URL kann der Beleg «beansprucht» werden. Anschliessend wird der Beleg bis zu seinem Ablaufdatum im entsprechenden Releaf-Kundenkonto angezeigt.
Belege, die nicht innerhalb von 30 Tagen beansprucht werden, verfallen und werden vollständig vom Server gelöscht.
Hinweise
Releaf-Belege lassen sich nach dem Hochladen innerhalb der Plattform nicht mehr bearbeiten. Sie sollten die Integrität und Gültigkeit von Belegen dennoch weiterhin genau wie bei Papierbelegen anhand Ihrer Unterlagen überprüfen, beispielsweise über einen Barcode auf dem Beleg.
Releaf haftet nicht für Schäden, die durch manipulierte Belege entstehen.
Playground
Im Playground können Sie das Ausstellen von Belegen in einem interaktiven Tool ausprobieren und damit experimentieren. Bitte beachten Sie, dass Sie hierzu einen gültigen API-Key benötigen.