Oxid

Zweck

Der OXID eShop Connector bietet eine umfassende Schnittstelle zur OXID eShop REST-API und ermöglicht die Automatisierung von E‑Commerce‑Prozessen. Er erlaubt die Verwaltung von Artikeln, Kategorien, Bestellungen, Kunden und Lieferungen direkt aus Workflows. Mit diesem Connector lassen sich folgende Aufgaben umsetzen:

• Produkte verwalten: Artikel inklusive Varianten und Lagerbestand erstellen, abrufen, aktualisieren und löschen.

• Kataloge organisieren: Kategorien und Hersteller verwalten.

• Bestellungen bearbeiten: Bestelldetails abrufen und aktualisieren.

• Kunden verwalten: Kundenkonten und Lieferadressen erstellen, abrufen, aktualisieren und löschen.

• Lieferungen handhaben: Liefersätze und Lieferungen verwalten.

Praktische Anwendungshinweise

• Mehrere Authentifizierungsmethoden: Unterstützt Bearer Token, API‑Schlüssel und OAuth2 Password‑Grant. Die Methode ist an die jeweilige API‑Konfiguration anzupassen.

• Paginierung: Listenendpunkte unterstützen die Parameter limit (Elemente pro Seite) und offset (Startindex).

• Filterung und Sortierung: Filter mit filter[<Eigenschaft>]=<Wert>, Sortierung mit sort[<Eigenschaft>]=<Richtung>.

• API‑Antwortstruktur: Antworten folgen meist dem HAL‑Format, mit Daten in _embedded und Navigation in _links.

Authentifizierung

Bearer Token

• Token wird im Authorization-Header als Bearer-Token übermittelt.

Beispiel-Header:

Authorization: Bearer <token>

API‑Schlüssel

• key: Name des Schlüssels (z.B. x-api-key)

• value: Schlüsselwert

• addTo: Einfügung in headers oder queryParameters

Beispiel (Header):

x-api-key: <your-api-key>

Beispiel (Query-Parameter):

https://api.example.com/resource?x-api-key=<your-api-key>

OAuth2 Password‑Grant

• Benötigt: Username, Password, Token URL, Client ID und Client Secret

Beispiel (Token-Anfrage, Form-Urlencoded):

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=password&username=<username>&password=<password>&client_id=<client_id>&client_secret=<client_secret>

Erwartungen an Ein- und Ausgabe

Eingabe

• Pfad-Parameter: Zum Beispiel articleId bei „Artikel nach ID abrufen“.

• Query-Parameter: Optional limit, offset, sort, filter.

• JSON-Body: Bei Erstellen oder Aktualisieren (z.B. Artikel, Bestellungen) ist ein JSON-data-Objekt erforderlich.

Beispiel (Query-Parameter):

GET /articles?limit=50&offset=0&filter[name]=T-Shirt&sort[price]=asc

Beispiel (JSON-Body für Erstellen/Aktualisieren):

{
  "data": {
    "type": "articles",
    "attributes": {
      "title": "T-Shirt",
      "price": 19.99,
      "stock": 100
    }
  }
}

Ausgabe

• response: JSON-Antwort, meist im HAL‑Format mit Daten in _embedded.

• header: Optional, wenn „Header ausgeben“ aktiviert ist.

• createResponseDataStructure: Hilft, aus der response eine strukturierte Datenform zu erzeugen, die die Zuordnung in Workflows erleichtert.

Beispiel (vereinfachte HAL-Antwort):

{
  "_embedded": {
    "articles": [
      {
        "id": "123",
        "title": "T-Shirt",
        "price": 19.99
      }
    ]
  },
  "_links": {
    "self": { "href": "/articles?limit=1" },
    "next": { "href": "/articles?limit=1&offset=1" }
  }
}