Smarda API-Anbindung

Inhaltsbereich

Die Smarda API kann benutzt werden, um einen Smarda-Shop oder eine Website an beliebige andere Systeme anzubinden. Dabei geht es oft um Warenwirtschaftsysteme (WaWi), ERP-Systeme, CRM-Systeme, Buchhaltung oder auch um Middleware. Es spielt dabei keine Rolle, ob es sich um große, gängige Systeme (wie SAP, Odoo, JTL, BMD, Hubspot, Pipedrive, Datev, Zapier usw.) oder spezielle, individuell entwickelte Apps handelt. Mittels der API Dokumentation können Entwickler auf Smarda zugreifen und jede Art von Datenaustausch steuern.

Smarda ist nach dem API-First-Prinzip aufgebaut, dadurch kann man über die API jede Änderung vornehmen, die einem User über das Backend möglich ist.

Jeder API-Aufruf passiert über folgende Basis-Adresse:

Base URL: https://api.smarda.app/backend/

An diese Basis-Adresse wird dann der Name des jeweiligen Endpoints angehängt. Um Produkte abzufragen rufst du zum Beispiel

GET https://api.smarda.app/backend/shops/{{shopId}}/products

auf. Du findest alle Endpoint-Namen in unserer API-Referenz beschrieben.

Zugriff einrichten: Private App anlegen

Bevor du die API ansprechen kannst, brauchst du eine private App in deinem Shop. Die Authentifizierung erfolgt nach dem Standard OAuth 2.0 Client-Credentials-Flow — es gibt keine Login mit Benutzername/Passwort mehr.

So gehst du vor:

  1. Im Smarda-Backend deines Shops im Einstellungen-Menü Apps aufrufen. Du landest auf der Seite /apps.
  2. Im Abschnitt Meine Apps auf Hinzufügen klicken und einen Namen für die neue private App vergeben.
  3. Die benötigten Scopes (Berechtigungen) auswählen, die deine Integration braucht — siehe Tabelle unten.
  4. Nach dem Speichern erhältst du zwei Werte:
    • client_id  — öffentlich, z. B. app_3a1f9c2b4d8e7f6a0b1c2d3e4f5a6b7c
    • client_secret — wird nur einmalig angezeigt, sicher speichern
  5. Über den Aktiv-/Inaktiv-Schalter in der App-Liste kannst du den Zugriff jederzeit pausieren, ohne die App löschen zu müssen.

Behandle das client_secret wie ein Passwort. Es darf nicht in öffentliche Repositories, Frontend-Code oder Logs gelangen.

Verfügbare Scopes

Beim Anlegen der privaten App wählst du aus, auf welche Ressourcen die App zugreifen darf. Jeder Scope entspricht einer Ressource im Backend; ohne den passenden Scope antwortet die API mit HTTP 403. Das Token enthält genau die Scopes, die du in der App-Konfiguration ausgewählt hast — sie werden in der Token-Antwort im Feld scope mitgeschickt.

Stamm- und Produktdaten

  • shop — Stammdaten des Shops (/shops/{shopId})
  • products — Produkte und Varianten
  • categories — Kategorien
  • manufacturers — Hersteller
  • tags — Tags / Schlagworte
  • product_filters — Produkt-Filter
  • features — Eigenschaften / Feature-Groups
  • cross_selling_groups — Cross-Selling-Gruppen
  • files — Datei-Uploads / Mediathek

Verkauf & Kunden

  • orders — Bestellungen
  • invoices — Rechnungen
  • delivery_notes — Lieferscheine
  • customers — Kunden
  • customer_groups — Kundengruppen
  • discount_codes — Rabattcodes
  • gift_vouchers — Gutscheine
  • gift_voucher_layouts — Gutschein-Layouts
  • price_conditions — Preisregeln / Preisbedingungen

Inhalte & Storefront

  • pages — Seiten / CMS
  • main_menu — Hauptmenüs
  • redirect_rules — Weiterleitungsregeln
  • snippets — Snippets
  • popups — Popups
  • forms — Formulare
  • form_submits — Formular-Einsendungen
  • themes — Themes / Templates
  • labels — Übersetzungs-Labels
  • email — E-Mail-Templates
  • domains — Domains

System & Integration

  • statistics — Statistiken
  • webhooks — Webhook-Konfiguration
  • apps — Apps / Installationen

Im scope-Parameter der Token-Antwort werden die Scopes als Leerzeichen-separierte Liste übergeben (OAuth-Standard), z. B. "scope": "products orders customers".

Access-Token holen

Mit client_id und client_secret forderst du per POST ein Access-Token an:

POST https://api.smarda.app/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=app_3a1f9c2b4d8e7f6a0b1c2d3e4f5a6b7c
&client_secret=<dein client_secret>

Die Antwort sieht so aus:

{
    "access_token": "soa_7f2c…",
    "token_type": "Bearer",
    "scope": "products:read orders:write"
}

Wichtig zu wissen:

  • Das Token beginnt immer mit dem Präfix soa_.
  • Es ist an genau einen Shop gebunden — nämlich den Shop, in dem die private App installiert wurde. Die shopId in den Endpoint-URLs muss zu diesem Shop passen.
  • Die Gültigkeit ist großzügig (mehrere Jahre); du kannst das Token dauerhaft cachen und musst es nicht bei jedem Aufruf neu anfordern.
  • Das Token kann jederzeit über POST /oauth/revoke oder durch Deaktivieren der App im Backend zurückgezogen werden.

Authentifizierte Requests

Den Wert aus access_token sendest du bei jedem Folge-Request im Authorization-Header mit.

Beispiel: Abfrage der Produkte

GET https://api.smarda.app/backend/shops/{{shopId}}/products

Authorization: Bearer soa_7f2c…

Shop-ID herausfinden

Falls deine Integration die shopId nicht aus dem Onboarding kennt, kannst du sie über folgenden Endpoint ermitteln:

GET https://api.smarda.app/backend/oauth/me

Authorization: Bearer soa_7f2c…

Die Antwort enthält die shopId sowie die gewährten Scopes des aktuellen Tokens.

Fehlerantworten

Bei ungültigen Credentials antwortet /oauth/token mit HTTP 401:

{
    "error": "invalid_client",
    "error_description": "Invalid client credentials"
}

Bei fehlerhaften Parametern (z. B. unbekannter grant_type) kommt HTTP 400 mit "error": "invalid_request".

Die API-Referenz findest du unter: https://developer.smarda.com/api/doc/reference/shop/