ShopAPI.io Logo

API

Dokumentation für die Verwendung der API

Allgemein

Endpunkte

POST api/v1/token

Stellt die Verbindung zu einer E-Commerce-Plattform her und gibt ein Token zurück

Parameter

Parameter Beispiel Beschreibung
applicationId Postman Schlüssel-Name der aufrufenden Anwendung.
Entnehmen Sie diese Angabe Ihrer Lizenz.
licenseId 55ff7975-91a5-45ed-8b93-8fd05f90b761 GUID
Entnehmen Sie diese Angabe Ihrer Lizenz
serialNumber 99999999999999 Seriennummer
Entnehmen Sie diese Angabe Ihrer Lizenz
platform Shopware6 Geben Sie die E-Commerce-Plattform an mit der die Verbindung hergestellt werden soll. Diese muss in der Lizenz freigeschaltet sein.
configJson { "Url": "https://example.com", "AccessKey": "874KJHJFG876876JHBHGFHZ", "SecretAccessKey": "MvUnwLMrYKRqRMEo02Dhe2Gnb7y2YGkHACVvNJlWdl2mEStYY8O" } Verbindungsparameter für die jeweilige E-Commerce-Plattform - diese sind abhängig von der verwendeten Plattform im JSON-Format
withNativeData true (optional) Wenn dieser Parameter auf true gestellt ist, werden die Original-Daten-Objekte der E-Commerce-Plattformen mit in die Daten eingebettet (Im Feld "Native")
(Mögliche Werte: true, false)

Plattform-Verbindungsparameter

Gambio

Plattform-Kürzel (Parameter platform): Gambio

Anleitung für die Einrichtung des API-Zugangs in Gambio

Parameter Beispiel Beschreibung
Url "https://example.com" URL zu dem Gambio-Online-Shop
Username "admin@example.com" Benutzername zu dem Gambio-Online-Shop (typischerweise ein Administrator-Benutzer)
Password "admin-secret123" Passwort zu dem Benutzernamen
{
 "Url": "https://example.com",
 "Username": "admin@example.com",
 "Password": "admin-secret123"
}
Shopify (Beta)

Plattform-Kürzel (Parameter platform): Shopify

Anleitung für die Einrichtung des API-Zugangs in Shopify

Die Verbindung zu Shopify befindet sich noch im Beta-Stadium. Möglicherweise funktionieren noch nicht alle Endpunkte vollständig. Darüber hinaus können aktuell nur die folgenden Endpunkte in Verbindung mit Shopify verwendet werden.

Parameter Beispiel Beschreibung
Url "https://meinshop.myshopify.com" URL zu dem Shopify-Online-Shop (Wichtig: MyShopify-Adresse)
AccessToken "shpat_34...7ba" In Shopify erstelltes Zugriffstoken
{
 "Url": "https://meinshop.myshopify.com",
 "AccessToken": "shpat_34...7ba",
}
Shopware 5

Plattform-Kürzel (Parameter platform): Shopware5

Anleitung für die Einrichtung des API-Zugangs in Shopware 5

Parameter Beispiel Beschreibung
Url "https://example.com" URL zu dem Shopware-Online-Shop
Username "admin" Benutzername zu dem Shopware-Online-Shop
ApiKey "MvUnwLMrYKRqRMEo02Dh...vNJlWdl2mEStYY8O" API-Schlüssel zu dem Benutzernamen
{
 "Url": "https://example.com",
 "Username": "admin",
 "ApiKey": "MvUnwLMrYKRqRMEo02Dh...vNJlWdl2mEStYY8O"
}
Shopware 6

Plattform-Kürzel (Parameter platform): Shopware6

Anleitung für die Einrichtung des API-Zugangs in Shopware 6

Parameter Beispiel Beschreibung
Url "https://example.com" URL zu dem Shopware-Online-Shop
AccessKey "874KJHJFG8...76JHBHGFHZ" In Shopware 6 erstellte Zugangs-ID
SecretAccessKey "MvUnwLMrYKRqRMEo02Dh...vNJlWdl2mEStYY8O" In Shopware 6 erstellter Sicherheitsschlüssel
ApiVersion 3

(optional) Die verwendete API-Version
(Standardwert: 0)

Mögliche Werte:

  • Shopware 6.0.x = 0
  • Shopware 6.1.x = 1
  • Shopware 6.2.x = 2
  • Shopware 6.3.x = 3
  • Shopware 6.4.x = 0

Dieser Parameter ist nötig von Shopware Version 6.1 bis 6.3

EnrichOrderWithProductData true (optional) Produktdaten zu jeder Position laden, im Feld "nativeProduct")
(Standardwert: false)
UseManufacturerNumberAsSku true (optional) Hersteller-Artikelnummer vorrangig als Artikelnummer verwenden (number)
(Standardwert: false)
RecalcInventoryUpdateByAvailableStock true (optional) Bei der Aktualisierung von Beständen den im Shop reservierten Bestand automatisch dem übertragenen Bestand hinzufügen (addieren)
(Standardwert: false)
PriorizeNetPrices true (optional) Für das Auslesen und Speichern von Preisen Netto- statt Bruttopreise nutzen
(Standardwert: false)
DefaultPriceGroupCode "Alle Kunden der Standard-Kundengruppe" (optional) Für Speichern von Staffel-Preisen, die ohne GroupCode übergeben werden, wird automatisch dieser GroupCode eingesetzt
(Standardwert: null)
{
 "Url": "https://example.com",
 "AccessKey": "874KJHJFG8...76JHBHGFHZ",
 "SecretAccessKey": "MvUnwLMrYKRqRMEo02Dh...vNJlWdl2mEStYY8O",
 "ApiVersion": 3,
 "EnrichOrderWithProductData": true,
 "UseManufacturerNumberAsSku": true,
 "RecalcInventoryUpdateByAvailableStock": true,
 "PriorizeNetPrices": true,
 "DefaultPriceGroupCode": "Alle Kunden der Standard-Kundengruppe"
}
WooCommerce

Plattform-Kürzel (Parameter platform): WooCommerce

Anleitung für die Einrichtung des API-Zugangs in WooCommerce

Parameter Beispiel Beschreibung
Url "https://example.com" URL zu dem WooCommerce-Online-Shop
ConsumerKey "ck_jllrbstm2euhdou...psfp6le4gxxhs" In WooCommerce erstellter Schlüssel
ConsumerSecret "cs_cawl3ld5i0tgbox...c9mcbt2a1yajm" In WooCommerce erstelltes Geheimnis
AddCredentialsToUri true (optional) Bei Verbindungsproblemen kann dieser Parameter auf true gestellt werden, um die Anmelde-Parameter in die URL zu integrieren.
DefaultTaxCountry "DE" (optional) Länder-Einstellung zur Berechnung der Umsatzsteuer für Bestell-Positionen als ISO-Ländercode
(Standard-Wert "DE")
{
 "Url": "https://example.com",
 "ConsumerKey": "ck_jllrbstm2euhdou...psfp6le4gxxhs",
 "ConsumerSecret": "cs_cawl3ld5i0tgbox...c9mcbt2a1yajm",
 "AddCredentialsToUri": true,
 "DefaultTaxCountry": "DE"
}

epages

Plattform-Kürzel (Parameter platform): epages

Parameter Beispiel Beschreibung
Url "https://12345678.shop.strato.de/rs/shops" URL zu dem epages-Online-Shop bei dem jeweiligen Provider (in dem Beispiel wurde Stato benutzt)
ShopID "12345678" Vom Provider vergebene Shop-ID
AccessToken "mWwImuZYh...wDSEVCJJL" Im epages-Shop erstellter Zugriffsschlüssel (Access Token)
{
 "Url": "https://12345678.shop.strato.de/rs/shops",
 "ShopID": "12345678",
 "AccessToken": "mWwImuZYh...wDSEVCJJL"
}

Rückgabe

{
  "token_type": "Bearer",
  "expires_in": 59.999995738333332,
  "access_token": "eyJhbGciOi...7bXlwpiSvms0"
}

Rückgabe bei Fehlern

HTTP 400 - Bad Request

{
  "error": "Connecting to platform \"...\" error: ..."
}

GET api/v1/orders

Empfangen von Bestellungen als absteigend nach Bestell-Datum sortierte Liste

Query-Parameter

Parameter Beispiel Beschreibung
limit &limit=50

(optional) Die maximale Anzahl Datensätze, die pro Seite abgerufen werden sollen

Der Standardwert und die maximale Anzahl an Datensätzen werden durch die verwendete E-Commerce-Plattform bestimmt.

page &page=3 (optional) Die Seite des Ergebnisses (Standard-Wert "1")
lastId &lastId=325

(optional) Nur Bestellungen seit der letzten ID abrufen

Wenn dieser Parameter nicht angegeben wird, werden alle Bestellungen abgerufen

state &state[0]=Open&state[1]=Processing&state[2]=Closed

(optional) Filtern von bestimmten Status als Auflistung (Array)

Mögliche Werte:

  • Open
  • Processing
  • Closed

Wenn dieser Parameter nicht angegeben wird, werden alle Bestellungen abgerufen.

Rückgabe

{
  "count": 3,
  "page": 3,
  "limit": 50,
  "list": [
    {
      Order
    },
    {
      Order
    },
    {
      Order
    }
  ]
}

GET api/v1/orders/<id>

Abruf einer einzigen Bestellung

URL-Parameter

Parameter Beispiel Beschreibung
id /97c05101bd6c4252918422db89bca541

Eindeutige ID der Bestellung

Rückgabe

{
  "data": {
    Order
  }
}

POST api/v1/orders/<id>/fulfill

Abschließen einer Bestellung

URL-Parameter

Parameter Beispiel Beschreibung
id /97c05101bd6c4252918422db89bca541/fulfill

Eindeutige ID der Bestellung

POST-Daten

Es muss ein Fulfillment-Objekt übergeben werden.

{
  "data":{
    "shippingService": "DHL",
    "trackingCode": "JJD98967890809765098",
    "shippingDate": "2019-09-05T00:00:00+02:00",
    "newState": "Processing",
    "status": "in_progress"
  }
}

GET api/v1/inventory

Abrufen von Lagerbeständen als Liste

Query-Parameter

Parameter Beispiel Beschreibung
limit &limit=50

Die maximale Anzahl Datensätze, die pro Seite abgerufen werden sollen

Der Standardwert und die maximale Anzahl an Datensätzen werden durch die verwendete E-Commerce-Plattform bestimmt.

page &page=3 Die Seite des Ergebnisses

Rückgabe

{
  "count": 16,
  "page": 3,
  "limit": 50,
  "list": [
    {
      Inventory
    },
    {
      Inventory
    },
    {
      Inventory
    }
  ]
}

PUT api/v1/inventory

Aktualisieren von Lagerbeständen als Liste

PUT-Daten

Es müssen Inventory-Objekte übergeben werden.

{
  "data": [
    {
      "identifier": 57,
      "inStock": 255
    },
    {
      "identifier": 40,
      "inStock": 250
    }
  ]
  
}

GET api/v1/prices

Abrufen von Artikel-Listenpreise als Liste

Query-Parameter

Parameter Beispiel Beschreibung
sku &sku=8776545 Preise nur für eine Artikelnummer anzeigen
limit &limit=50

Die maximale Anzahl Datensätze, die pro Seite abgerufen werden sollen

Der Standardwert und die maximale Anzahl an Datensätzen werden durch die verwendete E-Commerce-Plattform bestimmt.

page &page=3 Die Seite des Ergebnisses

Rückgabe

{
  "count": 16,
  "page": 3,
  "limit": 50,
  "list": [
    {
      Price
    },
    {
      Price
    },
    {
      Price
    }
  ]
}

PUT api/v1/prices

Aktualisieren von Artikel-Listenpreisen als Liste

PUT-Daten

Es müssen Artikel-Listenpreis-Objekte übergeben werden.

{
    "data": [
        {
            "identifier": "8776546",
            "priceGroups": [
                {
                    "price": 39.90,
                    "scales": [
                        {
                            "fromQuantity": 5,
                            "price": 38.29
                        },
                        {
                            "fromQuantity": 8,
                            "price": 38.19
                        }
                    ]
                }
            ]
        },
        {
            "identifier": "E78690",
            "priceGroups": [
                {
                    "price": 999.20
                },
                {
                    "groupCode": "Reseller",
                    "price": 799.20
                }
            ]
        }
    ]
}

GET api/v1/telemetry

Abruf von statistischen Daten zu den übertragenen Datensätzen und Anzahl der Transaktionen (Telemetrie) für die eigene Lizenz

URL-Parameter

Parameter Beispiel Beschreibung
year year=2020

Jahr für das die monatlichen Daten berechnet werden sollen

month month=3

Monat für den die monatlichen Daten berechnet werden sollen

Rückgabe

Es wird ein Telemetry-Objekt zurückgegeben

{
  "productSerial": "99999999999999",
  "month": 3,
  "year": 2020,
  "monthsRequestsCount": 2567,
  "monthsItemsCount": 4598,
  "requestCountSum": 7609,
  "itemsCountSum": 14657
}

Modelle

Token

Token mit allen Eigenschaften

Feld Beschreibung
token_type

"token_type": "Bearer"

Token-Typ - derzeit immer Bearer

expires_in

"expires_in": 59.99999788

Gültigkeit des Tokens in Minuten

platform

"access_token": "eyJhb...Ta6-X8vv6I"

Das zu verwendendende Token

Order

Bestellung mit allen Eigenschaften

Feld Beschreibung
identifier

"identifier": "97c05101bd6c4252918422db89bca541"

Eindeutige ID für die Bestellung

native

"native": { ... }

Enthält die kompletten Rohdaten der Bestellung (abhängig vom Shop-System)

(withNativeData muss bei der Token-Generierung true sein.)

platform

"platform": "Shopware6"

Plattform-Code der E-Commerce-Plattform

number

"number": "10000"

Nummer der Bestellung innerhalb des Shop-Systems (in der Regel fortlaufend)

orderDate

"orderDate": "2019-09-05T13:41:51+02:00"

Datum und Uhrzeit, wann die Bestellung aufgegeben wurde

customerName

"customerName": "Phillipp Frei"

Name des Bestellers, in der Regel Vorname- und Nachname aber auch Firma möglich

email

"email": "Phillipp.Frei@danielpeters.eu"

Name des Bestellers

netAmount

"netAmount": 50.41

Gesamtsumme netto

amount

"amount": 59.98

Gesamtsumme brutto

shippingTermsCode

"shippingTermsCode": "Standard"

Spezifischer Shop-Code der Versandart

shippingTermsName

"shippingTermsName": "Standard"

Bezeichnung der Versandart im Shop

shippingCosts

"shippingCosts": 0.0

Versandkosten brutto

shippingCostsNet

"shippingCostsNet": 0.0

Versandkosten netto

paymentTermsCode

"paymentTermsCode": "handler_shopware_cashpayment"

Spezifischer Shop-Code der Zahlungsart

paymentTermsName

"paymentTermsName": "Nachnahme"

Bezeichnung der Zahlungsart im Shop

paymentTransactionCode

"paymentTransactionCode": "TX7867866789"

Transaktions-Nummer für Zahlungen über Zahlungsanbieter (wie z. B. PayPal)

notes

"notes": ""

Bemerkungen zur Bestellung seitens des Bestellers

currencyCode

"currencyCode": "EUR"

Währungs-Kürzel für Geldbeträge

state

"state": "Processing"

Status der Bestellung

  • Open - Offen
  • Processing - In Bearbeitung
  • Closed - Geschlossen oder abgebrochen
isPaid

"isPaid": true

  • true, wenn die Bestellung vollständig bezahlt ist
  • false, wenn die Bestellung nicht nicht oder nur teilweise bezahlt ist
  • null, wenn kein Zahlungs-Status vorliegt
vatNumber

"vatNumber": null

Steuer-Identifikationsnummer (z. B. bei Firmen)

shippingTrackingCode

"shippingTrackingCode": null

Verfolgungsnummer des Paketdienstes

shippingService

"shippingService": null

Code des Paketdienstes

status

"status": "in_progress"

Shop-Spezifischer Status der Bestellung (abhängig von der E-Commerce-Plattform)

shopName

"shopName": "Testshop"

Name des Shops (z. B. bei mandantenfähigen Shop-Systemen)

positions

"positions": [
  {
    "identifier": "71c70bf94a41447ba2bd0cf9e77a8143",
    "native": { ... },
    "nativeProduct": { ... },
    "platform": "Shopware6",
    "productId": "3ac014f329884b57a2cce5a29f34779c",
    "sku": "SWDEMO10006",
    "productText": "Hauptprodukt, versandkostenfrei mit Hervorhebung",
    "quantity": 1.0,
    "price": 20.0,
    "netPrice": 16.81,
    "taxRate": 19.0,
    "positionType": "default"
  },
  {
    ...
  },
  {
    ...
  }
]

Positionen der Bestellung als Auflistung (Array) mit folgenden Eigenschaften:

  • identifier: Eindeutige ID der Position
  • native: Rohdaten des Shop-Systems
  • nativeProduct: Rohdaten des Shop-Produkts (abhängig von der Plattform - nicht immer verfügbar)
  • platform: Wiederholung der E-Commerce-Plattform
  • productId: Eindeutige ID des Produktes
  • sku: Artikelnummer des Produktes
  • productText: Positionstext
  • quantity: Menge
  • price: Einzelpreis brutto
  • netPrice: Einzelpreis netto
  • taxRate: Steuersatz
  • positionType: Positions-Art

Mögliche Positions-Arten

  • default Standard-Position (z. B. Produkt)
  • voucher Gutschein-Position
  • discount Rabatt-Position
billingAddress

"billingAddress": {
  "identifier": "cb284a7bd52c49aca865fcf2b847de2a",
  "native": { ... },
  "platform": "Shopware6",
  "title": null,
  "company": null,
  "firstname": "Phillipp",
  "lastname": "Frei",
  "street": "Jahnstrasse 5",
  "additional": null,
  "zipCode": "84402"
  "city": "Dorfen",
  "countryCode": "DE",
  "email": null,
  "primaryPhone": null,
  "secondaryPhone": null,
  "fax": null,
}

Rechnungs-Adresse mit folgenden Eigenschaften:

  • identifier: Eindeutige ID der Adresse
  • native: Rohdaten des Shop-Systems
  • platform: Wiederholung der E-Commerce-Plattform
  • title: Anrede
  • company: Firma
  • firstname: Vorname
  • lastname: Nachname
  • street: Straße inkl. Hausnummer
  • additional: Adresszusatz
  • countryCode: ISO-Ländercode
  • email: E-Mail-Adresse zur Adresse
  • primaryPhone: Telefonnummer
  • secondaryPhone: Weitere Telefonnummer
  • fax: Faxnummer
shippingAddress

"shippingAddress": {
  "identifier": "49f02ee4acda406bbaa0421dab3c4397",
  "native": { ... },
  "platform": "Shopware6",
  "title": null,
  "company": null,
  "firstname": "Barbara",
  "lastname": "Schwab",
  "street": "Augsburger Straße 80",
  "additional": null,
  "zipCode": "44623"
  "city": "Herne",
  "countryCode": "DE",
  "email": null,
  "primaryPhone": null,
  "secondaryPhone": null,
  "fax": null,
}

Liefer-Adresse mit folgenden Eigenschaften:

  • identifier: Eindeutige ID der Adresse
  • native: Rohdaten des Shop-Systems
  • platform: Wiederholung der E-Commerce-Plattform
  • title: Anrede
  • company: Firma
  • firstname: Vorname
  • lastname: Nachname
  • street: Straße inkl. Hausnummer
  • additional: Adresszusatz
  • countryCode: ISO-Ländercode
  • email: E-Mail-Adresse zur Adresse
  • primaryPhone: Telefonnummer
  • secondaryPhone: Weitere Telefonnummer
  • fax: Faxnummer

Fulfillment

Bestellabschluss mit allen Eigenschaften

Feld Beschreibung
shippingService

"shippingService": "DHL"

Paketdienst-Kürzel

trackingCode

"trackingCode": "JJD98967890809765098"

Sendungsverfolgungs-Nummer

shippingDate

"shippingDate": "2019-09-05T00:00:00+02:00"

Datum und Uhrzeit, wann die Bestellung versendet wurde

newState
POST: Pflichtfeld

"newState": "Processing"

Geänderter Status der Bestellung

Status der Bestellung

  • Open - Offen
  • Processing - In Bearbeitung
  • Closed - Geschlossen oder abgebrochen
status

"status": "in_progress"

Nativer Status im Shop-System

Inventory

Lagerbestand mit allen Eigenschaften

Feld Beschreibung
identifier
PUT: Pflichtfeld

"identifier": 57

Eindeutige ID des Lagerbestands-Datensatzes

native

"native": { ... }

Enthält die kompletten Rohdaten des Lagerbestands-Datensatzes (abhängig vom Shop-System)

(withNativeData muss bei der Token-Generierung true sein.)

platform

"platform": "Shopware6"

Plattform-Code der E-Commerce-Plattform

inStock
PUT: Pflichtfeld

"inStock": 255

Absolute verfügbare Bestandsmenge

restockTimeDays

"restockTimeDays": 14

Wiederbeschaffungszeit in Tagen

(Dezeit nur mit Shopware 6 nutzbar)

productSku

"productSku": "SW10014"

Artikelnummer

productName

"productName": "Schwarzes T-Shirt"

Artikelbezeichnung

(Nur vorhanden, wenn bei der Bestands-Abfrage vom Shop vorhanden)

Price

Artikel-Listenpreis mit allen Eigenschaften

Feld Beschreibung
identifier
PUT: Pflichtfeld

"identifier": "8776546""

Eindeutige ID des Artikel-Listenpreis-Datensatzes

native

"native": { ... }

Enthält die kompletten Rohdaten des Artikel-Listenpreis-Datensatzes (abhängig vom Shop-System)

(withNativeData muss bei der Token-Generierung true sein.)

platform

"platform": "Mock"

Plattform-Code der E-Commerce-Plattform

productName

"productName": "Test product 8776545"

Bezeichnung des Artikels

variantName

"productName": "color blue"

Bezeichnung der Variante

priceGroups
PUT: Pflichtfeld

"priceGroups": [
    {
        "price": 10.00,
        "offerPrice": 8.99,
        "scales": []
    },
    {
        "groupCode": "Reseller",
        "price": 8.00,
        "isNetPrice": true,
        "scales": [
            {
                "fromQuantity": 5,
                "price": 7.87
            },
            {
                "fromQuantity": 10,
                "price": 7.77
            },
            {
                "fromQuantity": 20,
                "price": 7.35
            }
        ]
    }
]

Preis-Gruppen mit folgenden Eigenschaften:

  • price: Preis PUT: Pflichtfeld
  • groupCode: Gruppen-Code zur Unterscheidung von Preis-Gruppen
  • offerPrice: Angebots-Preis
  • isNetPrice: Angabe, ob es sich bei der Preisgruppe um einen Nettopreis handelt
  • scales: Preise für Staffelmengen
    • fromQuantity: Menge ab PUT: Pflichtfeld
    • price: Staffelpreis PUT: Pflichtfeld
    • offerPrice: Angebots-Staffelpreis

Telemetry

Informationen für die Anzahl der durch die Lizenz genutzten Transaktionen.

Feld Beschreibung
productSerial

"productSerial": "99999999999999"

Seriennummer der aktuellen Lizenz

month

"month": 3

Monat für den die Berechnungen erfolgt sind

(z. B. 1 = Januar, 3 = März, 12 = Dezember)

year

"year": 2020

Jahr für das die Berechnungen erfolgt sind

monthsRequestsCount

"monthsRequestsCount": 2567

Anzahl der Transaktionen für den angegebenen Monat

monthsItemsCount

"monthsItemsCount": 4598

Anzahl der Datensätze für den angegebenen Monat

(Dieser Wert ist höher als monthsRequestsCount, da je Transaktionen mehrere Datensätze übertragen werden können)

requestCountSum

"requestCountSum": 7609

Anzahl aller Transaktionen

itemsCountSum

"itemsCountSum": 14657

Anzahl aller Datensätze