Eigenen Shop über die API mit easySales verbinden

Wann Sie das brauchen

easySales bietet fertige Konnektoren für die gängigen Shop-Plattformen. Wenn Sie etwas Eigenes betreiben — einen intern entwickelten Shop oder eine Plattform, für die wir keine Integration haben —, können Sie ihn selbst über die API anbinden.

Das ist eine Entwickleraufgabe. Sie schreiben Code, der Ihren Katalog in easySales überträgt und Bestellungen übergibt, und easySales ruft Ihren Shop zurück, sobald sich etwas ändert. Nichts davon setzt ein installiertes Plugin voraus.

Wie die Verbindung funktioniert

Zwei Zugangsdaten sind im Spiel, und sie zu verwechseln ist der häufigste Grund, warum eine erste Integration 403 zurückgibt.

Beide werden bei jedem Schreibvorgang benötigt. Das Zugriffstoken belegt, wer aufruft; das Website-Token sagt, zu welchem Shop die Daten gehören.

Schritt 1 — Website anlegen

Gehen Sie zu Integrationen → Websites, klicken Sie auf Website verbinden, füllen Sie das Formular aus und wählen Sie anschließend die Kachel API und darunter die Version API V2.

Schritt 2 — Website-Token kopieren

Der Schritt Konfiguration im Assistenten zeigt ein Token mit 60 Zeichen. Genau dieses erwähnt der alte Artikel nie, und genau dieses braucht jeder Schreibaufruf.

Kopieren Sie es mit der Schaltfläche, statt es abzutippen, und hinterlegen Sie es als Geheimnis in Ihrer Anwendung. Klicken Sie auf Speichern, um die Website anzulegen.

Der Shop erscheint nun unter Integrationen → Websites und trägt dasselbe Token auf seiner Karte — dort finden Sie es später wieder.

Schritt 3 — OAuth-Client erstellen

Gehen Sie zu Einstellungen → API-Einstellungen. Dort liegen die OAuth-Zugangsdaten.

Klicken Sie auf Neuen Kunden erstellen, benennen Sie ihn nach dem System, das aufrufen wird, und setzen Sie Grant-Typ auf Website Grant.

Website Grant ist genau dafür gebaut: Er tauscht Ihr Website-Token gegen ein Zugriffstoken, ohne Browser-Weiterleitung und ohne Benutzerinteraktion. Speichern Sie und kopieren Sie die angezeigte Client-ID und das Secret.

Schritt 4 — Zugriffstoken holen

POST https://easy-sales.com/oauth/token
Content-Type: application/json

{
  "grant_type":    "website",
  "client_id":     "your-client-id",
  "client_secret": "your-client-secret",
  "website_token": "your-60-character-website-token",
  "scope":         "add-products update-products update-stock add-orders update-orders read-orders"
}

Die Antwort ist ein gewöhnlicher OAuth-Body:

{
  "token_type":    "Bearer",
  "expires_in":    31536000,
  "access_token":  "eyJ0eXAiOiJKV1Qi...",
  "refresh_token": "def50200a1b2c3..."
}

Senden Sie es bei jedem weiteren Aufruf als Authorization: Bearer <access_token>.

Schritt 5 — Katalog übertragen

Die Basis-URL für alles Folgende ist https://easy-sales.com/api/v2.

Die Reihenfolge zählt. Kategorien und Merkmale müssen existieren, bevor ein Produkt auf sie verweisen kann, sonst wird der Produktaufruf abgelehnt.

1. POST /categories/save — Ihre Kategorien
2. POST /characteristics/save — Ihre Merkmale
3. POST /products/save — Ihre Produkte

POST https://easy-sales.com/api/v2/products/save
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "website_token": "your-60-character-website-token",
  "product": {
    "product_website_id": "10231",
    "sku": "TS-BLK-M",
    "name": "Black T-shirt, size M",
    "sale_price": 79.99,
    "full_price": 99.99,
    "stock": 24,
    "type": "simple",
    "tax_rate": 21,
    "url": "https://my-shop.example.com/p/ts-blk-m",
    "images": ["https://my-shop.example.com/img/ts-blk-m.jpg"],
    "categories": ["cat-778"],
    "characteristics": [{ "id": "char-12", "value": "Black" }]
  }
}

Schritt 6 — Bestände aktuell halten

Der Bestand ist das, was aktuell bleiben muss, und er ist der günstigste Aufruf, um ihn oft zu senden. Übergeben Sie bis zu 100 Zeilen auf einmal:

PATCH https://easy-sales.com/api/v2/stocks/bulk
Authorization: Bearer <access_token>

{
  "website_token": "your-60-character-website-token",
  "data": [
    { "sku": "TS-BLK-M", "stock": 24 },
    { "sku": "TS-BLK-L", "stock": 0 }
  ]
}

Jede SKU muss auf dieser Website bereits existieren; unbekannte werden abgelehnt und nicht angelegt.

Schritt 7 — Bestellungen übergeben

POST https://easy-sales.com/api/v2/orders/save
Authorization: Bearer <access_token>

{
  "website_token": "your-60-character-website-token",
  "order": {
    "order_id": "SO-100244",
    "order_date": "2026-09-09 14:31:00",
    "order_total": 179.98,
    "status": "new",
    "payment_mode": "card",
    "shipment_tax": 21,
    "billing_address":  { "country": "RO", "city": "Cluj-Napoca", "street": "Str. Memorandumului 4" },
    "shipping_address": { "country": "RO", "city": "Cluj-Napoca", "street": "Str. Memorandumului 4" },
    "order_products": [
      { "product_website_id": "10231", "sku": "TS-BLK-M", "name": "Black T-shirt, size M",
        "quantity": 2, "price": 79.99, "total": 159.98 }
    ]
  }
}

Senden Sie dieselbe order_id erneut, wird die Bestellung aktualisiert statt dupliziert — Wiederholungen sind damit gefahrlos.

Schritt 8 — Änderungen zurückbekommen

Ihr Shop muss wissen, wann eine Bestellung berechnet wurde, ein Versandlabel hat oder den Status wechselt. Abonnieren Sie einen Webhook, statt zu pollen:

GET https://easy-sales.com/api/v2/webhooks
Authorization: Bearer <access_token>

POST https://easy-sales.com/api/v2/webhooks/order-updated
Authorization: Bearer <access_token>

{
  "url":    "https://my-shop.example.com/hooks/easysales",
  "secret": "a-shared-secret-of-at-least-24-characters"
}

Sie abonnieren jeweils ein Ereignis, wiederholen Sie den Aufruf also für order-created, order-updated, awb-created, invoice-created und delivery-status-updated.

Jede Zustellung ist signiert, prüfen Sie also die Signatur, bevor Sie dem Inhalt vertrauen. Antworten Sie schnell — die Anfrage läuft nach wenigen Sekunden ab und wird nur begrenzt oft wiederholt, bestätigen Sie also zuerst und verarbeiten Sie danach.

Limits

Wenn etwas fehlschlägt

Was auf unserer Seite fehlschlägt, landet außerdem unter Produkte → Online-Shops → Website-Fehler, samt Payload und einer Aktion zum erneuten Versuch — das ist meist schneller, als den Aufruf nachzustellen.

Referenz

Die vollständige Endpunkt-Referenz, mit jedem Feld und jeder Antwort, ist unter https://api.easy-sales.com veröffentlicht.