Dieses Tutorial zeigt, wie man bei jeder bezahlten Shopify-Bestellung automatisch eine offene Debitoren-Rechnung in CashCTRL erstellen lässt, ganz ohne eigenen Server/VPS, komplett kostenlos gehostet, und auch für absolute Einsteiger ohne Programmiervorkenntnisse nachvollziehbar.

Die Zahlung selbst (z.B. der Zahlungseingang aus der Shopify-Auszahlung) wird bewusst NICHT automatisch verbucht, sondern bleibt wie gewohnt manueller Abgleich – so bleibt die Kontrolle über die Buchhaltung erhalten, während der lästige manuelle Teil (Rechnung erfassen, Kunde anlegen, Positionen eintippen) wegfällt.

Kunde bezahlt im Shopify-Shop
↓ (Webhook)
Kleiner Node.js-Server (kostenlos gehostet auf Render.com)
↓ (API-Aufruf)
CashCTRL: neue offene Debitoren-Rechnung mit Kunde und allen Positionen

Kein eigener VPS nötig, keine laufenden Kosten (solange man beim kostenlosen Render-Tier bleibt), keine Serverwartung.

Wichtiger Hinweis zu Artikeln/Positionen
Der Sync legt keine "echten" Artikel-Stammdaten in CashCTRL an. Jede Rechnungsposition wird als freie Textzeile direkt aus den Shopify-Bestelldaten erzeugt (Name, Menge, Preis, SKU als Text) – genau so, wie wenn man in CashCTRL von Hand eine Position ohne hinterlegten Artikel eintippt. Das funktioniert auch dann, wenn die Produkte in CashCTRL nicht als Artikel gepflegt sind.

Voraussetzungen

Ein Shopify-Shop mit Adminzugriff
Ein CashCTRL-Konto mit PRO-Abo (für API-Zugriff nötig, 30 Tage kostenlos testbar)
Ein kostenloses GitHub-Konto
Ein kostenloses Render.com-Konto
Keine Programmiererfahrung nötig, aber etwas Geduld beim ersten Mal mit dem Terminal

Schritt 1: API-User in CashCTRL anlegen
In CashCTRL einloggen.
Settings (Zahnrad oben rechts) → Users & Roles → Add → Add API benutzer.
Den angezeigten API-Key kopieren und sicher aufbewahren.

Schritt 2: Drei IDs aus CashCTRL herausfinden
Man braucht die IDs von: der Rechnungs-Kategorie, dem Ertragskonto und optional dem Steuercode. Diese liest man über einfache API-Aufrufe ab.
Unter Windows (PowerShell) curl.exe verwenden (nicht curl, das ist in PowerShell nur ein Alias für Invoke-WebRequest und funktioniert anders):
curl.exe "https://DEIN_ORG.cashctrl.com/api/v1/order/category/list.json" -u DEIN_API_KEY:
curl.exe "https://DEIN_ORG.cashctrl.com/api/v1/account/list.json" -u DEIN_API_KEY:
curl.exe "https://DEIN_ORG.cashctrl.com/api/v1/tax/list.json" -u DEIN_API_KEY:

DEIN_ORG ist die Sub-Domain deiner Organisation (bei https://firma.cashctrl.com ist es firma). Der Doppelpunkt nach dem API-Key ist wichtig (curl erwartet dort ein leeres Passwort).

In der Antwort auf den ersten Befehl sucht man die Kategorie mit "type": "SALES" und nameSingular gleich "Rechnung"/"Invoice" – deren id ist die CASHCTRL_INVOICE_CATEGORY_ID.

In der Antwort auf den zweiten Befehl sucht man ein Konto mit "accountClass": "REVENUE", das für Verkäufe genutzt werden soll – deren id ist die CASHCTRL_REVENUE_ACCOUNT_ID. Falls dieses Konto schon eine taxId hinterlegt hat, kann man diese direkt für CASHCTRL_TAX_ID übernehmen, ohne den dritten Befehl separat auszuwerten.

-> Die Beispiel Datei ist ebenfalls als DOWNLOAD verfügbar.

Schritt 3: Shopify Custom App erstellen
Shopify-Adminbereich → Einstellungen → Apps und Vertriebskanäle → App-Entwicklung.
"App erstellen" → Namen vergeben (z.B. "CashCTRL Sync").
Bei der Konfiguration/Version: App-URL kann als Platzhalter https://example.com bleiben, Häkchen "App in den Shopify-Adminbereich einbetten" kann entfernt werden.
Bei "API-Zugriff" → "Bereiche": read_orders eintragen.
Version veröffentlichen.
App installieren (Button auf der App-Übersichtsseite).
Wichtiger Punkt, der leicht zu Verwirrung führt: Für den eigentlichen Webhook wird NICHT der API-Secret-Key dieser Custom App gebraucht. Stattdessen registriert man den Webhook direkt über die normale Shopify-Benachrichtigungsseite (siehe Schritt 7) – dort zeigt Shopify einen eigenen, account-weiten Signatur-Schlüssel an, der ins Projekt eingetragen wird. Die Custom App wird in diesem einfachen Setup nur für die Berechtigungsstruktur gebraucht, nicht für einen aktiven API-Aufruf.

Schritt 4: Projektcode
Ordnerstruktur:
shopify-cashctrl-sync/
├── lib/
│ ├── cashctrl.js
│ ├── mapping.js
│ └── shopify.js
├── .env.example
├── package.json
├── README.md
└── server.js

Könnt ihr alles hier herunterladen: HIER

Schritt 5: Code auf GitHub hochladen
Auf github.com registrieren/einloggen.
Neues Repository erstellen, Sichtbarkeit "Private".
Über "uploading an existing file" alle Dateien hochladen (inkl. lib-Ordner und .env.example).
Wichtig: die tatsächliche .env-Datei mit den echten Zugangsdaten NIEMALS mit hochladen – nur lokal behalten.
"Commit changes" klicken.

Schritt 6: Auf Render.com deployen
Auf render.com registrieren (am einfachsten "Sign up with GitHub").
"New" → "Web Service" → das eigene Repository auswählen/verbinden.
Einstellungen:
Region: möglichst nah am eigenen Standort (z.B. Frankfurt für die Schweiz)
Branch: main
Build Command: npm install
Start Command: npm start (oder node server.js)
Instance Type: "Free"
Bei "Environment Variables" auf "Add from .env" klicken und den kompletten Inhalt der lokalen .env-Datei einfügen – Render übernimmt automatisch alle Variablen einzeln.
"Deploy Web Service" klicken.

Nach ein bis zwei Minuten zeigt Render den Status "Live" und eine öffentliche URL wie:
https://dein-projektname.onrender.com.

Schritt 7: Webhook in Shopify registrieren
Shopify-Adminbereich → Einstellungen → Benachrichtigungen.
Ganz nach unten scrollen zu "Webhooks" → "Webhook erstellen".
Ereignis: "Bestellungszahlung" (orders/paid)
Format: JSON
URL: https://dein-projektname.onrender.com/webhooks/shopify/orders-paid
Webhook-API-Version: die neueste stabile Version wählen (nicht "unstable")
Speichern.

Nach dem Speichern zeigt Shopify auf derselben Seite einen Signatur-Schlüssel an ("Deine Webhooks werden mit ... signiert"). Diesen Wert in die .env-Datei (lokal) UND bei Render unter "Environment" als SHOPIFY_WEBHOOK_SECRET eintragen. Nach dem Speichern bei Render deployt der Service automatisch neu.

Schritt 8: Testen
Man muss nicht auf eine echte Bestellung warten:
In Shopify beim eigenen Webhook-Eintrag auf "..." klicken → "Senden" (Testversand).
Im Render-Dashboard unter "Logs" nachsehen, ob eine Zeile erscheint wie:
Bestellung #9999 -> CashCTRL-Rechnung erstellt (ID ..., offen).
In CashCTRL unter Bestellungen die neue, offene Rechnung kontrollieren (Kunde, Positionen, Steuersatz, Betrag).

Häufige Stolpersteine
"curl: -u nicht erkannt" in PowerShell
curl ist in PowerShell nur ein Alias für Invoke-WebRequest, das den Parameter -u nicht kennt. Lösung: curl.exe statt curl verwenden.

"fetch failed" im Render-Log
Meist ein falscher Wert bei CASHCTRL_ORG. Dort darf NUR der reine Sub-Domain-Name stehen (z.B. firma), nicht die volle URL mit https:// und .cashctrl.com.

Webhook kommt nicht an / "Invalid signature"
Meist ein falscher Wert bei SHOPIFY_WEBHOOK_SECRET. Wichtig: Der Signatur-Schlüssel, der auf der Shopify-Benachrichtigungsseite direkt bei den Webhooks angezeigt wird ("signiert mit ..."), ist nicht dasselbe wie der API-Secret-Key der Custom App.

Render-Service reagiert manchmal verzögert
Der kostenlose Render-Plan schläft nach ca. 15 Minuten Inaktivität ein und braucht beim Aufwecken 30-60 Sekunden. Shopify liefert Webhooks bei Verzögerung automatisch erneut aus (Retry-Logik), daher geht dabei nichts verloren – nur etwas später. Bei Bedarf lässt sich auf einen kostenpflichtigen Render-Plan wechseln, der durchgehend läuft.

Hoffe, konnte damit unterstützen. Bei Fragen, einfach fragen.