> For the complete documentation index, see [llms.txt](https://docs.sync4.de/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sync4.de/faq/shops/shopify-api-authentifizierung-2026.md).

# Shopify API Authentifizierung 2026

{% hint style="info" %}
DIese Seite befindet sich noch im Aufbau!
{% endhint %}

### Ziel

Diese Anleitung beschreibt die Erstellung und Installation einer **Shopify Custom App** inklusive **OAuth-Authentifizierung**, wie sie für `sync4` bzw. `desk4` verwendet wird.

***

### Voraussetzungen

* Zugriff auf das **Shopify Developer Dashboard**
* Shop, in dem die App installiert werden soll
* Gültige Redirect-URL (`sync4.de` oder `desk4.de`)

***

### 1. Developer Dashboard öffnen

* Shopify Developer Dashboard aufrufen
* Entweder ein bestehendes App-Projekt auswählen oder ein neues erstellen

***

### 2. App erstellen

* Auf **Create App** klicken
* App-Typ: **Custom App**

***

### 3. App-Name festlegen

* Namenskonvention:
  * `sync4`
  * oder `desk4_<kundenname>`

Beispiel:\
`sync4_mustermann`

***

### 4. Redirect URL konfigurieren

In den App-Einstellungen:

* **Redirect URL** setzen auf:
  * `https://sync4.de`\
    **oder**
  * `https://desk4.de`

> Diese URL wird nach erfolgreicher Authentifizierung aufgerufen.

***

### 5. Embedded App deaktivieren

* Option **„Embed app in Shopify admin“** **abwählen**

***

### 6. API Scopes (Berechtigungen) eintragen

Im Bereich **Scopes** die folgenden Rechte hinterlegen. Es sind genau die Rechte, die der sync4-Shopify-Connector verwendet. Weitere Scopes sind nicht nötig und sollten nicht eingetragen werden.

{% code overflow="wrap" %}

```
read_products,write_products,read_inventory,write_inventory,read_locations,read_publications,write_publications,read_orders,write_orders,read_all_orders,read_customers,read_files,write_files,read_translations,write_translations,read_locales,read_merchant_managed_fulfillment_orders,write_merchant_managed_fulfillment_orders,read_third_party_fulfillment_orders,write_third_party_fulfillment_orders,read_assigned_fulfillment_orders,write_assigned_fulfillment_orders
```

{% endcode %}

| Bereich                                                                 | Scopes                                                                                  | Wofür                                                                                                                                                                                                              |
| ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Artikel, Varianten, Kategorien (Collections), Hersteller, Staffelpreise | `read_products`, `write_products`                                                       | Artikel und Kategorien anlegen, ändern, löschen und lesen. Preise und Staffelpreise je B2B-Katalog.                                                                                                                |
| Bestand                                                                 | `read_inventory`, `write_inventory`                                                     | Bestände lesen und setzen.                                                                                                                                                                                         |
| Lager (Standorte)                                                       | `read_locations`                                                                        | Shopify-Standorte abrufen, damit das Default-Lager gewählt werden kann.                                                                                                                                            |
| Sales Channels                                                          | `read_publications`, `write_publications`                                               | Sales Channels abrufen. Artikel und Kategorien je Kanal veröffentlichen bzw. zurückziehen.                                                                                                                         |
| Bestellungen                                                            | `read_orders`, `write_orders`                                                           | Bestellungen abrufen und nach dem Versand abschließen.                                                                                                                                                             |
| Bestellungen älter als 60 Tage                                          | `read_all_orders`                                                                       | Abruf von Bestellungen, die älter als 60 Tage sind, zum Beispiel bei einem früheren Startdatum für den Bestellabruf. Funktioniert nur zusammen mit `read_orders`. Shopify muss diesen Scope für die App freigeben. |
| Kundendaten                                                             | `read_customers`                                                                        | Name, E-Mail und Telefon des Kunden aus den Bestellungen übernehmen. Zusätzlich muss der Zugriff auf geschützte Kundendaten freigegeben sein (siehe Hinweise unten).                                               |
| Bilder                                                                  | `read_files`, `write_files`                                                             | Artikel-, Varianten- und Kategoriebilder hochladen und prüfen.                                                                                                                                                     |
| Übersetzungen                                                           | `read_translations`, `write_translations`                                               | Übersetzungen von Artikeln und Kategorien lesen und schreiben.                                                                                                                                                     |
| Sprachen                                                                | `read_locales`                                                                          | Die im Shop aktiven Sprachen abrufen.                                                                                                                                                                              |
| Versand (Fulfillment), eigenes Lager                                    | `read_merchant_managed_fulfillment_orders`, `write_merchant_managed_fulfillment_orders` | Versand mit Sendungsnummer und Versanddienstleister an Shopify melden.                                                                                                                                             |
| Versand (Fulfillment), Fremdlager                                       | `read_third_party_fulfillment_orders`, `write_third_party_fulfillment_orders`           | Wie oben, wenn die Aufträge in Shopify bei einem Fremdlager (Drittanbieter) liegen.                                                                                                                                |
| Versand (Fulfillment), Fulfillment-Service-App                          | `read_assigned_fulfillment_orders`, `write_assigned_fulfillment_orders`                 | Wie oben, wenn die Aufträge einer Fulfillment-Service-App zugewiesen sind.                                                                                                                                         |

#### Hinweise

* **Fulfillment-Scopes:** Shopify vermerkt, dass die Fulfillment-Scopes (`*_fulfillment_orders`) von Shopify freigegeben werden müssen. Bei Fehlermeldungen zu fehlenden Rechten prüfen, ob die Freigabe vorliegt.
* **Geschützte Kundendaten:** Name, E-Mail, Telefon und Adressen aus Bestellungen unterliegen bei Shopify dem Schutz von Kundendaten. Der Zugriff wird in den App-Einstellungen im Developer Dashboard beantragt. Das ist eine Einstellung und kein Scope.
* **Staffelpreise und Kataloge:** Funktionieren nur mit einem Shopify-Plus-Tarif (B2B-Kataloge sind eine Plus-Funktion). Dafür sind keine zusätzlichen Scopes nötig. Der Benutzer, der die App betreibt, braucht aber die Berechtigung, Kataloge anzusehen und zu bearbeiten.
* **Schreibrechte schließen Leserechte ein:** Ein `write_`-Scope erlaubt in Shopify immer auch das Lesen. Beide Scopes einzutragen ist trotzdem unschädlich.

⚠️ **Hinweis:**\
Änderungen an den Scopes erfordern immer eine neue App-Version.

***

### 7. App veröffentlichen (Release)

* App **releasen**
* **Versionsnummer setzen**

#### Versionslogik

* Start bei **1.0**
* Versionsnummer erhöhen bei:
  * Änderung der Scopes
  * Hinzufügen / Entfernen von Rechten
  * Änderung der Webhook-Version

Beispiel:

* 1.0 → Initial
* 1.1 → Neue API-Rechte
* 2.0 → Größere Änderungen

***

### 8. Installationslink erstellen

* Nach dem Release den **Installations-/OAuth-Link** kopieren

***

### 9. App-Installation

* Link im Browser öffnen
* Shopify zeigt Berechtigungsabfrage
* Abfrage muss bestätigt werden → App wird installiert

***

### 10. Redirect nach erfolgreicher Installation

* Nach erfolgreicher Installation:
  * Shopify leitet automatisch auf die konfigurierte **Redirect URL** weiter
  * (`https://sync4.de` oder `https://desk4.de`)

***

### 11. Installation prüfen

Im **Developer Dashboard**:

* App öffnen
* Status prüfen:
  * Anzeige **„Install“** bestätigt erfolgreiche Installation
