Allgemeine Informationen zur Nutzung des metasfresh Webservice (REST API)

Ü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 () eingesehen, kopiert und mit den gewünschten Daten ergänzt werden. Eine Beschreibung des Anfrage-Modells () mit Erläuterungen zu den einzelnen Elementen hilft Dir bei der Erstellung Deiner eigenen Serveranfrage.

Um den Webservice nutzen zu können, benötigst Du allerdings ein Autorisierungstoken, mit dem Du Dich erst gegenüber der REST API authentifizieren musst, bevor Du eine Serveranfrage absenden kannst. Dieses Token wird Dir in dem Eintrag Deines metasfresh-Nutzers bereitgestellt.

Schritte

1. Halte Dein Autorisierungstoken bereit.
2. Erlange Zugang zur metasfresh Application Server REST API.
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 . Die Eingabefelder 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 , 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.

• Auftragskandidaten (Auftragsdisposition)
• Aufträge
• Dateiup- und -download
• Datenimport
• Geschäftspartner und Kontakte
• Produkte und Produktkategorien
• Rechnungen und Rechnungskandidaten

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://{{ Basis-URL }}/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.

Beispiel