Step: PlentyAddOrders - REST API

Mit diesem Step können Sie neue Aufträge in Plentymarkets anlegen und / oder Zahlungen(Payments) für vorhandene Bestellungen importieren.

Achtung

Dieser Step unterscheidet sich von anderen Steps. Aufträge die zu plentymarkets übertragen werden sollen, müssen zuerst in zwei Datenstores (Auftragskopfdaten und Auftragspositionen) gespeichert werden. Der PlentyAddOrders - Step kann nur gespeicherte Aufträge zu plentymarkets übertragen.

Für diesen Step benötigen Sie daher zwei Datastores in einer Master-Child Beziehung (siehe Datastoresopen in new window).

  • Im Master Datastore sind dabei die Kopfdaten der Bestellung gespeichert.
  • Im Child Datastore sind die jeweiligen Artikelpositionen gespeichert und müssen per master_identifier dem jeweiligen Masterdatastore-Item (Bestellkopf) zugewiesen sein.

Das ist notwendig, da der Step bei der Abarbeitung der Aufträge die von plentymarkets vergebene AuftragsID (orderID) an die Datensätze schreibt und jeden Datensatz als PROCESSED_SUCCESS markiert. Damit wird verhindert, dass Aufträge doppelt zu plentymarkets übertragen werden.

Benötigte Plentymarkets REST API  Berechtigungen

(es sind nicht immer alle notwendig):

  • Aufträge - Auftragsadressen - Auftragsadressen erstellen
  • Aufträge - Aufträge erstellen
  • Aufträge - Auftragseigenschaften - Eigenschaft erstellen
  • Aufträge - Referenzen für Auftragsrelationen - Referenz erstellen
  • Aufträge - Aufträge anzeigen
  • Aufträge - Aufträge aktualisieren
  • Kommentare - Kommentar erstellen

Step Konfiguration:

Input
Beschreibung
account

Ihr Plentymarkets-Account um auf die Schnittstelle zuzugreifen.

limit

Damit kann eingeschränkt werden wie viele Aufträge angelegt werden. Gerade während der Erstellung eines Flows ist es praktisch diesen Wert eher klein zu halten (z.B. 10), damit nur wenige Aufträge angelegt werden.

Default: 50

datastore

Geben Sie hier den Datastore an, in denen die jeweiligen Auftragskopfdaten abgespeichert sind. Es werden automatisch alle verknüpften Auftragspositionen gefunden und an den Kopf angehangen. Der Datastore mit den Auftragskopfdaten benötigt ein PlentyOrderPayload Schema (siehe Datastores - Schema) und der zugehörige Child-Datastore ein PlentyOrderItemsPayload. Die Bestellpositionen müssen über eine Master-Child Beziehung mit dem Auftrag verbunden sein.

folder

Geben Sie den Folder an, aus denen Sie die Aufträge aus dem Datastore abholen wollen.

Payment Options

Hier können sie auswählen ob die Zahlungsvorgang für Bestellungen angelegt und die Bestellung somit als vollständig bezahlt importiert wird. Folgende Optionen sind möglich:

  • Don't create payments - Bestellung wird ohne Zahlungsvorgang / unbezahlt angelegt (Default)
  • Auto-Create payments for all orders - Erzeugt eine vollständige Zahlung für alle importierten Bestellungen.
  • Create payment if paymentTransactionID is set - Beim Anlegen der Bestellung wird nur eine (vollständige) Zahlung angelegt, wenn die Spalte paymentTransactionID gefüllt ist. Als paymentTransactionID können Sie einen eindeutigen Wert (z.B. externe Bestellnummer oder timestamp) verwenden.
  • Only link paymentID to order - Diese Option kann gewählt werden, wenn Zahlungsvorgänge bereits in ihrem Plentymarkets System vorhanden sind. Importieren Sie die ID der Zahlung dazu in die paymentID Spalte in den Auftragkopfdaten.

Default: No

Vorbereitung:

Achtung

Aufträge die zu Plentymarkets übertragen werden sollen, müssen zuerst in zwei Datenstores (Auftragskopfdaten und Auftragspositionen) gespeichert werden. Wenn die Aufträge bereit verabeitet wurden, werden Sie im Datastore als verabeitet (PROCESSED_SUCCESS oder PROCESSED_ERROR) markiert. Wenn Sie die Daten erneut importieren wollen, muss der entsprechende Datensatz des Bestellkopfs wieder auf den Verabeitungstatus "UNPROCESSED" zurückgesetzt werden.

Datastores mit Auftragskopf und Auftragspositionen anlegen

Damit der PlentyAddOrders Step funktioniert, müssen die Auftragsdaten bereits in 2 Datastores vorliegen:

  • Im Master Datastore sind dabei die Kopfdaten der Bestellung gespeichert.
  • Im Child Datastore sind die jeweiligen Artikelpositionen gespeichert und müssen per master_identifier dem jeweiligen Masterdatastore-Item (Bestellkopf) zugewiesen sein.

Schema:

Bestellung - Kopfdaten

Bestellung - Auftragspositionen


Nachdem Sie die oberen Schritte ausgeführt haben, sehen Sie die beiden Datastores in der Datastore Ansicht so aus:

Datastores:

Aufträge in Datastores speichern

 1. Benötigte Daten für Auftragskopf

Benötigte SpaltenErläuterung
Kundendaten

customerId (und customerAddressId) oder billingCustomer... Spalten

Wenn keine customerId angegeben ist, wird automatisch ein neuer Kunde auf Grundlage der billingCustomer... Spalten angelegt. Die Spalten customerId und customerAddressId werden in diesem Fall automatisch bei Import befüllt.


Lieferadressdaten

deliveryAddressId oder deliveryCustomer... Spalten

Wenn keine deliveryAddressId angeben ist, wird eine neue Lieferadresse auf Basis der deliveryCustomer... Spalten angelegt. In diesem Fall wird die deliveryAddressId automatisch vom Step befüllt.

plentyID

Die Plentymarkets ID des Webshops.

Die Daten können sie manuell oder automatisch über einen Flow in den Datastore importieren. In der Regel wird es über einen Flow gemacht. 

Einge Felder werden automatisch beim Import der Bestellung vom Step gefüllt und dürfen nicht gesetzt werden:

  • orderId, remoteStatusMessage, remoteStatusCode, remotePaymentStatus


2.Benötigte Daten für Auftragsposition (Pflichtfelder)

Benötigte Spalten
variantId

quantity

itemText

Zur Positionsanlage sind die beiden in der Tabelle aufgeführten Spalten notwendig.

Ist kein Preis (Netto oder Brutto) angegeben wird dieser automatisch anhand der angegebenen Variante zugeordnet.



Spaltenbeschreibung:

Auftragskopf

SpaltenbezeichnungErläuterung
ID Spalten (werden teilweise, je nach Use-Case automatisch befüllt )
orderIDVon Plenty vergebene Aufrags ID
deliveryAddressIDID der Versandadresse
customerIDKunden ID
customerAddressIDID der Rechnungsadresse
paymentIDID des Zahlungsvorgangs

Status Spalten(werden automatisch befüllt)

remoteStatusMessage

Wird von Synesty mit der "Antwort" von Plenty befüllt

OrderID=XXX,OrderStatus=XXX

remoteStatusCode

Wird von Synesty bei Übertragung der Bestellung an Plenty gesetzt

SUCCESS = Erfolgreich übermittelt
ERROR = Fehler bei der Übertragung

remotePaymentStatus

Wird von Synesty bei Anlage einer Zahlung mit dem Status befüllt

Auftragseinstellungen

plentyID

ID des Mandanten / Webshops
ownerID
ID des Benutzers / Eigners der Bestellung
customerReferenceZeichen Kunde
referrerIDAuftragsherkunft ID
orderStatusAuftragsstatus
externalCustomerNumberExterne Kundennummer
externalOrderIDExterne Auftragsnummer
warehouseIDLager ID
shippingProfileIDVersandprofil ID (z.B. für Paket)
methodOfPaymentIDZahlungsmethode ID
orderTypeAuftragstyp
marking1IDMarkierung 1 ID
shippingCostsVersandkosten
estimatedTimeOfShipmentvorrausichtliches Versanddatum
referenceOrderIDID des referenzierten Auftrags, z.B. bei Retouren

Zahlungsvorgang

paymentTransactionIDZahlungstransaktion ID
paymentBookingTextVerwendungszweck der Zahlung

Kunden- / Rechnungsadressdaten

billingCustomerFormOfAddressAnrede (Rechnungsadresse)
billingCustomerCompanyFirma (Rechnungsadresse)
billingCustomerFirstNameVorname (Rechnungsadresse)
billingCustomerSurnameNachname (Rechnungsadresse)
billingCustomerAdditionalNameNamenszusatz (Rechnungsadresse)
billingCustomerStreetStraße (Rechnungsadresse)
billingCustomerHouseNumberHausnummer (Rechnungsadresse)
billingCustomerZipPostleitzahl (Rechnungsadresse)
billingCustomerCityStadt (Rechnungsadresse)
billingCustomerCountryIDLand ID (Rechnungsadresse), siehe auch https://developers.plentymarkets.com/en-gb/interface/stable7/Order.html#order_countries
billingCustomerEmailE-Mail Adresse (Rechnungsadresse)
billingCustomerTelephoneTelefon (Rechnungsadresse)
billingCustomerFaxFax (Rechnungsadresse)
billingCustomerLanguageSprache (Rechnungsadresse), siehe https://developers.plentymarkets.com/en-gb/interface/stable7/Order.html#order_currency
billingCustomerVatIDUmsatzsteuer-Identifikationsnummer (Rechnungsadresse)
billingDebitorAccountMandant (Kunde)
billingCustomerPlentyIDKundenklasse (Kunde)
billingCustomerPostNumberPostnummer (Rechnungsadresse)
billingCustomerContactPersonAnsprechpartner (Kunde)
billingCustomerClassKundenklasse (Kunde)
billingCustomerPaymentDueWithinZahlungsziel (Kunde)

Lieferadressdaten

deliveryCustomerCompanyFirma (Lieferadresse)
deliveryCustomerFirstNameVorname (Lieferadresse)
deliveryCustomerSurnameNachname (Lieferadresse)
deliveryCustomerAdditionalNameNamenszusatz (Lieferadresse)
deliveryCustomerStreetStraße (Lieferadresse)
deliveryCustomerHouseNumberHausnummer (Lieferadresse)
deliveryCustomerZipPostleitzahl (Lieferadresse)
deliveryCustomerCityStadt (Lieferadresse)
deliveryCustomerCountryIDLand ID (Lieferadresse), siehe auch https://developers.plentymarkets.com/en-gb/interface/stable7/Order.html#order_countries
deliveryCustomerEmailE-Mail Adresse (Lieferadresse)
deliveryCustomerTelephoneTelefon (Lieferadresse)
deliveryCustomerFaxFax (Lieferadresse)
deliveryCustomerVatIDUmsatzsteuer-Identifikationsnummer (Lieferadresse)
deliveryCustomerPostNumberPostnummer (Lieferadresse)


Auftragsnotiz

infoUserIDBenutzer ID der Auftragsnotiz
infoNotiz am Auftrag

Auftragsposition

SpaltenbezeichnungErläuterung
variantIdID der Variante in ihrem Plentymarkets Shop
quantityBestellmenge
pricePreis Brutto
priceNetPreis Netto
VATProzentsatz MwSt
vatCountryIdID des Landes für diesen MwSt Satz (Einstellungen » Mandant (Shop) » Standard » Umsatzsteuersätze)
currencyWährung, siehe https://developers.plentymarkets.com/rest-doc/introduction#currenciesopen in new window
itemTextArtikelname
itemRebateArtikel Rabatt

Anwendungsbeispiel:

In der Regel ist bereits in einem vorherigen Prozess ein Master-Child Datastore mit Bestellungen (Kopf- und Positionsdaten) gelaufen - siehe Vorbereitung.

Der "PlentyAddOrders" Step greift nun auf diesen Master-Child Datastore zu und sendet alle Datensätze im PROCESSING_STATUS = UNPROCESSED an Plentymarkets.

Alle erfolgreich an Plentymarkets übermittelten Aufträge werden im Auftragskopf Datastore als "PROCESSED_SUCCESS" markiert. Desweiteren erhalten die Aufträge die von Plenty angelegte Auftragsnummer (OrderID) und werden mit mit einem StatusCode (SUCCESS bei Erfolg, ERROR bei fehlerhafter Übertragung) gekennzeichnet.

Ein erfolgreich übermittelter Auftrag, sieht im Auftragksopf Datastore in etwa so aus:

Hinweis: Falls bei der Übermittlung an Plenty ein Fehler auftritt, prüfen Sie ob alle benötigten Spalten (siehe oben) gefüllt sind.