metafresh logo and link to homepage

Allgemeine Informationen zur Verwendung des metasfresh Webservice

Überblick

Über den metasfresh Webservice (REST API) kannst Du externe Daten nach metasfresh übertragen sowie bestehende Dateneinträge aus dem System abrufen, aktualisieren oder löschen. Dies erfolgt über sogenannte API-Endpunkte, wobei jeder Endpunkt für die Migration bestimmter Datensätze eingerichtet ist, die mittels Serveranfrage im JSON-Format an den metasfresh Application Server übermittelt werden können. Eine Besonderheit der metasfresh REST API ist, dass Du Datenmigrationen, die im Normalfall über die einzelnen Endpunkte erfolgen würden, ebenso gut in nur einer Serveranfrage zusammenfassen kannst, im Zuge dessen gleich mehrere Dateneinträge auf einmal angelegt werden. So lässt sich z.B. bei der Migration eines Auftragskandidaten in die Auftragsdisposition von metasfresh gleichzeitig ein neuer Geschäftspartner- und Produkteintrag anlegen.

Eine Vorlage für eine Serveranfrage im JSON-Format steht für jeden Endpunkt zur Verfügung und kann an der jeweiligen Stelle (Anfragevorlage) eingesehen, kopiert und (je nach Präferenz) in einem Texteditor Deiner Wahl mit den gewünschten Daten ergänzt werden. Eine Beschreibung des Anfrage-Modells (Anfrage-Modell) mit Erläuterungen zu den einzelnen Elementen hilft Dir bei der Erstellung Deiner eigenen Serveranfrage.

Um den Webservice verwenden zu können, benötigst Du allerdings ein Autorisierungstoken, mit dem Du Dich erst bei der REST API authentifizieren musst, bevor Du eine Serveranfrage absenden kannst. Dieses Token erhältst Du in dem Eintrag Deines metasfresh-Nutzers.

Schritte

  1. Halte Dein Autorisierungstoken bereit.
  2. Erlange Zugang zur metasfresh Application Server REST API.

    Hinweis: Die URL setzt sich in der Regel folgendermaßen zusammen:
    https://instanzname#.metasfresh.com/app/swagger-ui.html#/

  3. Öffne den Endpunkt, den Du zur Datenmigration verwenden möchtest, durch Anklicken des Endpunktnamens.
  4. Klicke links unterhalb des Endpunktnamens auf die gewünschte Anfragemethode.
  5. Klicke rechts unterhalb der Anfragemethode auf Ausprobieren. Die Schreibfelder Authorization token und request werden editierbar.
  6. Füge in das Feld Authorization token Dein Autorisierungstoken ein.
  7. Füge in das Feld request Deine vorbereitete Serveranfrage im JSON-Format ein.
  8. Klicke auf Ausführen, um die Serveranfrage abzusenden.

    Hinweis: Eventuelle Fehlermeldungen werden Dir unten im Abschnitt Responses angezeigt.

Verfügbare Endpunkte

Im Folgenden werden die derzeit verfügbaren Endpunkte aufgeführt. Klicke auf einen Endpunkt, über den Du mehr erfahren möchtest.

JSON-Elemente

externalId

"externalId": "2156435"

Dieses Name-Wert-Paar bezieht sich auf die ID des Datensatzes auf der externen Plattform, von der die Daten abgerufen werden. Die externalId muss eindeutig sein. Zu finden ist sie am Ende der URL eines Dateneintrages in metasfresh hinter der Fenster-ID, wie in dem folgenden Beispiel zu erkennen ist:

https://live000.metasfresh.com/window/123/2156435

syncAdvise

"syncAdvise": {
  "ifExists": "DONT_UPDATE",
  "ifNotExists": "CREATE"
}

Mithilfe dieses Objektes wird geprüft, ob ein Datensatz bereits existiert oder nicht sowie gesteuert, was in dem jeweiligen Fall passieren soll. Je nach Wertvorgabe können bestehende Datensätze aktualisiert, gelöscht oder von der Datenmigration ausgeschlossen sowie neue Datensätze angelegt oder der gesamte Migrationsvorgang abgebrochen werden.

Kondition Werte Beschreibung
“ifExists” • UPDATE_MERGE
• UPDATE_REMOVE
• DONT_UPDATE
Ist ein Datensatz bereits vorhanden, kann er aktualisiert, gelöscht oder ausgelassen werden.
“ifNotExists” • CREATE
• FAIL
Ist ein Datensatz nicht vorhanden, kann er angelegt werden oder der Migrationsvorgang wird abgebrochen.

Beispiel

REST API-Endpunkt: Auftragskandidaten


Zur Quelldatei auf github.com