Die Shopify Custom App ist eine spezielle Anwendung, die nur für einen einzigen Shop entwickelt wurde, nicht im Shopify App Store veröffentlicht wird und direkt vom Shop-Manager installiert wird. Diese Struktur, die bei der direkten Integration mit ERP-Systemen, Buchhaltungssoftware oder Logistikplattformen bevorzugt wird, erfordert einen anderen Token-Erhaltungs- und Autorisierungsprozess als die Entwicklung einer standardmäßigen öffentlichen App.
Dieser Leitfaden richtet sich sowohl an Entwickler, die eine benutzerdefinierte App für ihren eigenen Shop entwickeln möchten, als auch an technische Teams, die ein SaaS- oder Unternehmenssystem integrieren möchten, das mit Shopify kompatibel ist.
Was ist eine Shopify Custom App?
Eine Shopify Custom App ist eine Anwendung, die von Grund auf für die speziellen Anforderungen eines bestimmten Shops geschrieben wurde, nur in diesem Shop installiert wird und nicht die öffentliche App-Infrastruktur von Shopify (App Store, OAuth-Autorisierungsablauf) nutzt. Sie ermöglicht den programmatischen Zugriff auf die Admin-API oder die Storefront-API.
Es ist ein häufiger Fehler, die drei Shopify-App-Typen zu verwechseln. Die folgende Tabelle verdeutlicht, welche Struktur Sie in welchem Szenario verwenden sollten:
Ideale Anwendungsfälle für eine benutzerdefinierte App: ERP-Integration (SAP, Netsis, Logo), Verbindung zu einem speziellen Logistik-/Fracht-System, interne Automatisierungs-Workflows und Datensynchronisation zwischen Handelsplattformen.
Von der privaten App zur benutzerdefinierten App: Shopifys Änderung im Jahr 2023
Shopify hat im Januar 2023 das Private-App-System vollständig abgeschafft. Vor diesem Datum konnten Shop-Administratoren durch die Erstellung eines API-Schlüssels und eines API-Geheimnisses direkten Zugriff erhalten. Mit dem neuen System ist dieser Weg nun versperrt.
Wichtiger Hinweis: Wenn Sie noch eine Integration haben, die die alten privaten App-Anmeldedaten verwendet, wird diese Verbindung von Shopify dauerhaft unterbrochen. Der Wechsel zu einer benutzerdefinierten App ist obligatorisch.
Warum wurde diese Änderung vorgenommen? Aus Sicherheitsgründen barg das alte private App-System erhebliche Risiken bei der Verwaltung von API-Schlüsseln: Es gab keine Schlüsselrotation, die Bereichskontrolle war lax und es gab keinen Mechanismus zur Erkennung von Anmeldedatenlecks. Das neue benutzerdefinierte App-System hat diese Lücken mit HMAC-Authentifizierung, Bereichsbeschränkung und Token-Überwachung geschlossen.
Technische Unterschiede aufgrund der Änderung:
- Alt: Direkte Anfrage mit API-Schlüssel + API-Geheimnis. Neu: Mit OAuth 2.0 erhaltenes access_token
- Alt: API-Passwort im X-Shopify-Access-Token-Header. Neu: OAuth-Token im selben Header
- Alt: Keine Token-Zeitüberschreitung. Neu: Offline-Token dauerhaft, Online-Token 24 Stunden
Shopify Custom App Token-Typen
Bei der Entwicklung von Shopify Custom Apps gibt es zwei verschiedene API-Oberflächen und zwei damit verbundene Token-Typen.
Für die meisten Unternehmensintegrationen ist ein Admin-API-Zugriffstoken erforderlich. Die Storefront-API wird für kundenorientierte Entwicklungen (Headless Commerce, mobile Anwendungen) verwendet und bietet keinen Zugriff auf die Admin-API.
Unterschied zwischen Offline- und Online-Token:
Offline-Token für Hintergrundprozesse, Cronjobs und Server-zu-Server-Integrationen. Sie bleiben gültig, solange die Anwendung nicht aus dem Store entfernt wird. Online-Token für Abläufe, die eine Benutzersitzung erfordern, verfallen nach 24 Stunden.
Tipp: Verwenden Sie immer Offline-Token, wenn Sie eine ERP- oder Buchhaltungsintegration schreiben. Ein Synchronisierungsvorgang, der mit einem Online-Token um Mitternacht ausgeführt wird, schlägt stillschweigend fehl, wenn die Gültigkeitsdauer des Tokens abgelaufen ist.
Warum ist das neue Custom App-System so komplex?
Bei Nodus Works hören wir sowohl bei der Arbeit mit SaaS-Plattformen von Drittanbietern als auch mit ERP-Teams von Unternehmen am häufigsten folgende Frage: „Wie erhalten wir das Shopify-Token?“
Das neue Custom App-System von Shopify wurde aus guten Gründen so konzipiert, dass es sicher ist, aber dieses Design hat zu einer erheblichen Komplexität bei der Einrichtung geführt. Insbesondere für Backend- oder Integrationsteams, die zum ersten Mal mit dem Shopify-Ökosystem arbeiten, ist der Prozess unklar.
Ursachen für die Komplexität:
1. Zwei verschiedene Möglichkeiten, einen Token zu erhalten. Die Custom App kann sowohl direkt über das Shopify-Admin-Panel als auch über das Partner Dashboard mit OAuth-Flow installiert werden. Beide erfordern unterschiedliche Verfahren zum Erhalt eines Tokens. Wenn Sie nicht wissen, welchen Weg Sie wählen sollen, können Sie stundenlang mit einer unvollständigen Installation kämpfen.
2. Konfiguration des Partner-Dashboards. Wenn Sie sich für den OAuth-Weg entscheiden, müssen Sie im Partner-Dashboard eine Anwendung erstellen, Callback-URLs definieren und den Umfang angeben. Ein Fehler in einem dieser Schritte führt zu invalid_client- oder redirect_uri_mismatch-Fehlern.
3. Scope-Verwaltung. Die gewünschten Scopes müssen sowohl in der .env- oder Konfigurationsdatei als auch im Partner Dashboard genau übereinstimmen. Eine kleine Abweichung macht das Token ungültig.
4. HMAC-Überprüfung. Shopify erwartet, dass Sie die im Callback zurückgegebenen Parameter mit einer selbst erstellten Signatur überprüfen. Das Überspringen dieses Schritts führt zu einer Sicherheitslücke; die Nichtbeachtung führt zu einem Fehler in der Produktion.
Shopify Admin API-Token erhalten: Zwei Methoden
Methode 1: Direktes Token aus dem Shop-Admin-Panel
Diese Methode ist nur gültig, wenn Sie ein Token für Ihren eigenen Shop erhalten und über Administratorzugriff auf den Shop verfügen.
Schritte:
- Melden Sie sich bei Shopify Admin an → Einstellungen → Anwendungen und Vertriebskanäle
- Gehen Sie zur Seite „Apps verwalten“ → Klicken Sie auf „App entwickeln“
- App erstellen → App-Namen eingeben → Erstellen
- Wechseln Sie zur Registerkarte „API-Anmeldedaten“
- Wählen Sie die erforderlichen Admin-API-Bereiche aus (z. B. read_orders, write_products)
- App installieren → Bestätigen
- Der Admin-API-Zugriffstoken wird nur einmal angezeigt. Speichern Sie ihn sofort.
Warnung: Shopify zeigt diesen Token nur einmal an. Nachdem Sie die Seite geschlossen haben, können Sie nicht mehr auf den Token zugreifen. Um einen neuen Token zu erhalten, müssen Sie die App deinstallieren und neu installieren.
Einschränkung dieser Methode: Sie funktioniert nur für einen einzigen Shop. Wenn Sie dieselbe Integration mit mehreren Shops verbinden möchten, müssen Sie zum OAuth-Flow wechseln.
Methode 2: Partner-Dashboard und OAuth 2.0-Flow
Dieser Weg wird für SaaS-Produkte, Agenturen und Multi-Store-Integrationen verwendet. Die über das Partner-Dashboard erstellte Anwendung kann mit dem OAuth-Flow in verschiedenen Shops eingerichtet werden.
Technischer Ablauf:
1. Der Benutzer wird zur Seite „Partner Dashboard App” weitergeleitet.
2. Der Shop-Domain wird der Endpunkt /auth aufgerufen
3. Die Shopify OAuth-Autorisierungsseite wird geöffnet
4. Der Benutzer gibt seine Zustimmung → Shopify leitet ihn mit dem Code zur Callback-URL weiter
5. Der Server überprüft den HMAC
6. Der Token-Endpunkt wird mit Code + client_id + client_secret aufgerufen
7. access_token wird zurückgegeben → in der Datenbank gespeichert
Die Umsetzung dieses Ablaufs von Grund auf ist ein Prozess mit hoher Fehlerquote, insbesondere in Bezug auf die HMAC-Überprüfung und die Bereichsverwaltung.
Shopify App Token Generator: Unsere Open-Source-Lösung
Um dieses Problem zu lösen, mit dem wir bei Integrationsprojekten immer wieder konfrontiert waren, haben wir bei Nodus Works ein leichtgewichtiges Tool entwickelt und als Open Source veröffentlicht:
github.com/nodusworkscom/shopify-app-token-generator
Dieses Tool führt den OAuth 2.0-Flow in einer lokalen Umgebung aus und generiert einen permanenten Admin-API-Zugriffstoken. So erhalten Sie innerhalb weniger Minuten einen gültigen Token, ohne eine vollständige OAuth-Implementierung schreiben zu müssen.
Wie funktioniert es?
Wenn Sie das Tool ausführen, wird ein kleiner Express-Server auf localhost gestartet. Sie werden zur OAuth-Autorisierungsseite von Shopify weitergeleitet. Nach der Bestätigung wird der Code, der an die Callback-URL zurückgegeben wird, automatisch erfasst, eine HMAC-Überprüfung durchgeführt und das access_token sowohl im Terminal als auch im Browser angezeigt.
Installation:
git clone https://github.com/nodusworkscom/shopify-app-token-generator.git
cd shopify-app-token-generator
npm install
cp .env.example .env
Füllen Sie Ihre .env-Datei aus:
SHOPIFY_API_KEY=Ihre_Kunden-ID
SHOPIFY_API_SECRET=Ihr_Client-Geheimnis
SHOP=your-store.myshopify.com
SCOPES=read_products,write_orders,read_customers
npm start
Gehen Sie in Ihrem Browser zu localhost:3000 → Klicken Sie auf dem Shopify-Bestätigungsbildschirm auf „Install app“ → Das Token wird im Terminal und auf dem Bildschirm angezeigt.
Voraussetzungen:
- Node.js v16 oder höher
- Shopify-Partnerkonto (kostenlos)
- Im Shopify Partner Dashboard erstellte Anwendung
- http://localhost:3000/callback als Callback-URL definiert
Wichtig: In den App-Einstellungen im Partner-Dashboard müssen die Basis-URL http://localhost:3000 und die Weiterleitungs-URL http://localhost:3000/callback definiert sein. Andernfalls erhalten Sie den Fehler „redirect_uri_mismatch”.
Für mehrere Shops: Sie können den SHOP-Wert in der .env-Datei ändern und den Vorgang für jeden Shop wiederholen. Jedes generierte Token ist für diesen Shop spezifisch.
Dieses MIT-lizenzierte Tool kann als Ausgangspunkt für Shopify-Integrationsprojekte und als praktische Referenz zum Verständnis des Token-Erstellungsprozesses verwendet werden.
Sicherheit und Best Practices für benutzerdefinierte Apps
Die Token-Sicherheit ist der kritischste Aspekt der Integration. Ein Admin-API-Zugriffstoken berechtigt Sie zur Verwaltung von Bestellungen, Kunden und Produkten in Ihrem Shop.
Token-Speicherung: Speichern Sie das Token als Umgebungsvariable und fügen Sie es niemals in den Quellcode oder das Versionskontrollsystem ein. Vergewissern Sie sich, dass Sie .env zu Ihrer .gitignore-Datei hinzugefügt haben. Verwenden Sie in der Produktionsumgebung Vault, AWS Secrets Manager oder ein ähnliches Tool zur Geheimnisverwaltung.
Prinzip des minimalen Umfangs: Gehen Sie nicht über den für die Integration erforderlichen Umfang hinaus. Für ein System, das nur Bestellungen liest, ist read_orders ausreichend. Fügen Sie keine write_orders oder read_customers hinzu. Shopify erlaubt Ihnen zwar, die Umfangsliste nachträglich zu reduzieren, eine Erweiterung erfordert jedoch eine Neuinstallation.
HMAC-Überprüfung: Akzeptieren Sie das Token im OAuth-Callback nicht, ohne die von Shopify gesendete HMAC-Signatur zu überprüfen. Implementierungen, die diesen Schritt überspringen, sind anfällig für Token-Diebstahl-Angriffe. Unser Token-Generator führt diesen Schritt automatisch durch.
Webhook-Sicherheit: Überprüfen Sie auch Shopify-Webhooks mit HMAC. Verarbeiten Sie keine Webhook-Daten, ohne den X-Shopify-Hmac-Sha256-Header zu überprüfen.
Für Unterstützung bei Fragen zur Sicherheit und technischen Architektur von Shopify-Integrationen können Sie sich unseren Shopify-Integrationsservice ansehen.
Häufige Fehler und Lösungen
invalid_client-Fehler: Client-ID oder Client-Secret wurden falsch eingegeben. Vergleichen Sie die Anmeldedaten im Partner-Dashboard mit der .env-Datei.
Fehler „redirect_uri_mismatch”: Die Callback-URL stimmt nicht genau mit der im Partner-Dashboard definierten Weiterleitungs-URL überein. Selbst ein Unterschied im abschließenden Schrägstrich führt zu einem Fehler: http://localhost:3000/callback und http://localhost:3000/callback/ werden als unterschiedlich angesehen.
Fehler „invalid_scope“: Einer der gewünschten Bereiche ist ungültig oder falsch geschrieben. Beachten Sie die offizielle Bereichsdokumentation von Shopify.
Einmalige Token-Anzeige: Wenn das aus dem Admin-Panel abgerufene Token nicht gespeichert wurde, muss die Anwendung deinstalliert und neu installiert werden. Das über das Partner-Dashboard per OAuth abgerufene Token kann durch erneutes Ausführen des OAuth-Flows erneuert werden.
HMAC-Überprüfung fehlgeschlagen: Der Client Secret ist falsch oder die Query-String-Parameter wurden geändert. Das Token-Generator-Tool führt die Überprüfung automatisch durch; achten Sie bei der manuellen Implementierung auf die Reihenfolge der Parameter.
Weitere Informationen zu ERP-Verbindungen und Systemintegrationen in Shopify-Integrationsprojekten finden Sie in unserem Leitfaden zur Shopify-ERP-Integration und in unserem Artikel zur Shopify-Integration. Informationen zur Integration von Buchhaltungssystemen finden Sie in unserem Artikel zur Shopify-Rechnungs- und Buchhaltungsintegration.
Häufig gestellte Fragen
Was ist der Unterschied zwischen einer Shopify-Custom-App und einer Private-App? Die Private-App ist eine alte Struktur, die Shopify 2023 abgeschafft hat. Die Custom-App ist ein neues System, das die Private-App ersetzt und eine sicherere Token-Verwaltung bietet. Ihre aktuellen Private-App-Anmeldedaten funktionieren nicht mehr; die Umstellung auf die Custom-App ist obligatorisch.
Ist das Token der benutzerdefinierten App unbegrenzt gültig? Das Offline-Zugriffstoken bleibt dauerhaft gültig, solange die App nicht aus dem App Store entfernt wird. Das Online-Token läuft nach 24 Stunden ab. Für Hintergrundintegrationen müssen Sie ein Offline-Token verwenden.
Kann die Shopify Custom App kostenlos entwickelt werden? Das Shopify Partner-Konto ist kostenlos. Für die Entwicklung der Custom App fallen keine zusätzlichen Kosten an, jedoch muss der von Ihnen integrierte Shop über einen aktiven Shopify-Tarif verfügen. Während der Entwicklung können Sie den kostenlosen Development Store nutzen.
Mit wie vielen Shops kann ich mich über eine benutzerdefinierte App verbinden? Die über das Admin-Panel erstellte benutzerdefinierte App ist nur für einen einzigen Shop spezifisch. Um sich mit mehreren Shops zu verbinden, müssen Sie über das Partner-Dashboard eine Struktur einrichten, die den OAuth-Flow verwendet. In diesem Fall wird für jeden Shop ein separater Zugriffstoken generiert.
Wie wähle ich zwischen der Shopify GraphQL Admin API und der REST API? Shopify entwickelt die GraphQL Admin API aktiv weiter und stellt die REST API schrittweise ein. Wir empfehlen Ihnen, Ihre neuen Integrationen auf GraphQL aufzubauen. GraphQL löst das Problem des Daten-Overfetching und bietet flexiblere Abfragemöglichkeiten.
Kann ich ohne OAuth-Flow einen Token erhalten? Ja. Die über das Shopify-Admin-Panel erstellte benutzerdefinierte App generiert direkt einen Token, ohne dass ein OAuth-Flow erforderlich ist. Diese Methode gilt nur für Ihren eigenen Shop; für die Einrichtung in anderen Shops ist OAuth erforderlich.
Wie kann ich Shopify-Webhooks über die benutzerdefinierte App abhören? Nachdem Sie das Token für die benutzerdefinierte App erhalten haben, können Sie über die Admin-API ein Webhook-Abonnement erstellen. Sie definieren einen Endpunkt und hören auf POST-Senden von Shopify an diesen Endpunkt. Verarbeiten Sie jede Webhook-Anfrage, indem Sie den X-Shopify-Hmac-Sha256-Header überprüfen.
Kann das Token-Generator-Tool in der Produktionsumgebung verwendet werden? Das Tool wurde zum Erstellen von Tokens entwickelt. Sobald Sie ein gültiges Token erhalten haben, benötigen Sie das Tool nicht mehr. Das erstellte Token kann für Produktions-API-Anfragen verwendet werden. Das Tool eignet sich ideal zum Lernen, zur schnellen Token-Erstellung und für Integrationstests.
Fazit
Die Entwicklung von Shopify-Custom-Apps ist insbesondere mit dem neuen Token-System unnötig kompliziert geworden. Wenn Sie nicht wissen, welche Art von Token Sie mit welcher Methode erhalten, können Sie Stunden verlieren.
Das direkte Abrufen von Tokens über das Admin-Panel ist für die Integration einzelner Shops ausreichend. Wenn Sie mehrere Shops unterstützen oder ein System eines Drittanbieters integrieren möchten, ist der OAuth 2.0-Flow unvermeidlich.
Das von uns entwickelte Open-Source-Tool shopify-app-token-generator reduziert den schwierigsten Schritt dieses Prozesses, den HMAC-verifizierten OAuth-Flow, auf wenige Minuten.
Wenn Sie technische Beratung, Architekturdesign oder Entwicklungsunterstützung für Ihr Shopify-Integrationsprojekt benötigen, können Sie unseren Shopify-Technik-Support und Wartungsservice in Anspruch nehmen oder sich direkt an uns wenden.
