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 PlentyONE übertragen werden sollen, müssen zuerst in zwei Datenstores (Auftragskopfdaten und Auftragspositionen) gespeichert werden. Der PlentyAddOrders - Step kann nur gespeicherte Aufträge zu PlentyONE übertragen.

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

• 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 PlentyONE vergebene AuftragsID (orderID) an die Datensätze schreibt und jeden Datensatz als PROCESSED_SUCCESS markiert. Damit wird verhindert, dass Aufträge doppelt zu PlentyONE ü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:

Dastores:

Aufträge in Datastores speichern

Benötigte Daten für Auftragskopf
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

Benötigte Spalten	Erlä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.

---

Benötigte Daten für Auftragsposition (Pflichtfelder)
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.

Benötigte Spalten
variantId
quantity
itemText

Spaltenbeschreibung:

Auftragskopf

Spaltenbezeichnung	Erläuterung
ID Spalten (werden teilweise, je nach Use-Case automatisch befüllt )
orderID	Von Plenty vergebene Aufrags ID
deliveryAddressID	ID der Versandadresse
customerID	Kunden ID
customerAddressID	ID der Rechnungsadresse
paymentID	ID 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
customerReference	Zeichen Kunde
referrerID	Auftragsherkunft ID
orderStatus	Auftragsstatus
externalCustomerNumber	Externe Kundennummer
externalOrderID	Externe Auftragsnummer
warehouseID	Lager ID
shippingProfileID	Versandprofil ID (z.B. für Paket)
methodOfPaymentID	Zahlungsmethode ID
orderType	Auftragstyp
marking1ID	Markierung 1 ID
shippingCosts	Versandkosten
estimatedTimeOfShipment	vorrausichtliches Versanddatum
referenceOrderID	ID des referenzierten Auftrags, z.B. bei Retouren
Zahlungsvorgang
paymentTransactionID	Zahlungstransaktion ID
paymentBookingText	Verwendungszweck der Zahlung
Kunden- / Rechnungsadressdaten
billingCustomerFormOfAddress	Anrede (Rechnungsadresse)
billingCustomerCompany	Firma (Rechnungsadresse)
billingCustomerFirstName	Vorname (Rechnungsadresse)
billingCustomerSurname	Nachname (Rechnungsadresse)
billingCustomerAdditionalName	Namenszusatz (Rechnungsadresse)
billingCustomerStreet	Straße (Rechnungsadresse)
billingCustomerHouseNumber	Hausnummer (Rechnungsadresse)
billingCustomerZip	Postleitzahl (Rechnungsadresse)
billingCustomerCity	Stadt (Rechnungsadresse)
billingCustomerCountryID	Land ID (Rechnungsadresse), siehe auch https://developers.plentymarkets.com/en-gb/interface/stable7/Order.html#order_countries
billingCustomerEmail	E-Mail Adresse (Rechnungsadresse)
billingCustomerTelephone	Telefon (Rechnungsadresse)
billingCustomerFax	Fax (Rechnungsadresse)
billingCustomerLanguage	Sprache (Rechnungsadresse), siehe https://developers.plentymarkets.com/en-gb/interface/stable7/Order.html#order_currency
billingCustomerVatID	Umsatzsteuer-Identifikationsnummer (Rechnungsadresse)
billingDebitorAccount	Mandant (Kunde)
billingCustomerPlentyID	Kundenklasse (Kunde)
billingCustomerPostNumber	Postnummer (Rechnungsadresse)
billingCustomerContactPerson	Ansprechpartner (Kunde)
billingCustomerClass	Kundenklasse (Kunde)
billingCustomerPaymentDueWithin	Zahlungsziel (Kunde)
Lieferadressdaten
deliveryCustomerCompany	Firma (Lieferadresse)
deliveryCustomerFirstName	Vorname (Lieferadresse)
deliveryCustomerSurname	Nachname (Lieferadresse)
deliveryCustomerAdditionalName	Namenszusatz (Lieferadresse)
deliveryCustomerStreet	Straße (Lieferadresse)
deliveryCustomerHouseNumber	Hausnummer (Lieferadresse)
deliveryCustomerZip	Postleitzahl (Lieferadresse)
deliveryCustomerCity	Stadt (Lieferadresse)
deliveryCustomerCountryID	Land ID (Lieferadresse), siehe auch https://developers.plentymarkets.com/en-gb/interface/stable7/Order.html#order_countries
deliveryCustomerEmail	E-Mail Adresse (Lieferadresse)
deliveryCustomerTelephone	Telefon (Lieferadresse)
deliveryCustomerFax	Fax (Lieferadresse)
deliveryCustomerVatID	Umsatzsteuer-Identifikationsnummer (Lieferadresse)
deliveryCustomerPostNumber	Postnummer (Lieferadresse)
Auftragsnotiz
infoUserID	Benutzer ID der Auftragsnotiz
info	Notiz am Auftrag

Auftragsposition

Spaltenbezeichnung	Erläuterung
variantId	ID der Variante in ihrem Plentymarkets Shop
quantity	Bestellmenge
price	Preis Brutto
priceNet	Preis Netto
VAT	Prozentsatz MwSt
vatCountryId	ID des Landes für diesen MwSt Satz (Einstellungen » Mandant (Shop) » Standard » Umsatzsteuersätze)
currency	Währung, siehe https://developers.plentymarkets.com/rest-doc/introduction#currencies
itemText	Artikelname
itemRebate	Artikel 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.

Inputs

Das sind die Optionen, mit denen man den Step konfigurieren kann.

Name	Datentyp	Beschreibung	Pflichtfeld	Werte
account	ACCOUNT	Ihre PlentyONE Verbindung	Ja
datastore	DATASTORE	Der Datastore, der die Aufträge für PlentyONE enthält. Der Datastore muss mit dem plentymarkets-Bestellschema (PlentyRESTOrderPayloadProvider) kompatibel sein.	Ja
	Folgende Felder sind zu konfigurieren: Feld Datentyp Beschreibung Pflichtfeld Standardwert name SINGLE Datastore entity name, for internal use only Nein orderID SINGLE The OrderID created by PlentyONE after import of order (automatically filled) Nein customerID SINGLE ID of Customer. Leave empty to create a new contact or fill with existing CustomerID/ContactID. Use -1 to create an order without an assigned customer (guest order). Nein customerAddressID SINGLE ID of Invoice Address. Leave empty to create a new address or fill with existing AddressID. Nein deliveryAddressID SINGLE ID of Shipping Address. Leave empty to create a new address or fill with existing AddressID. Nein paymentID SINGLE ID of Payment. Leave empty to create a new payment or fill with existing PaymentID. Nein remoteStatusMessage SINGLE Internal API status field, leave empty Nein remoteStatusCode SINGLE Internal API status field, leave empty Nein remotePaymentStatus SINGLE Internal API status field, leave empty Nein plentyID SINGLE The plenty ID of the client that the order belongs to Nein ownerID SINGLE The user ID of the order's owner Nein customerReference SINGLE The customer sign of the order (order property ID = 8) Nein referrerID SINGLE The referrer ID of the order. Nein orderStatus SINGLE The ID of the order status. Nein externalOrderID SINGLE The external order ID of the order (order property ID = 7) Nein externalCustomerID SINGLE The external ID of the contact. Nein customerNumber SINGLE The number of the contact. Nein externalCustomerNumber SINGLE This field is deprecated will be removed in future. Please use billingExternalAddressId instead Nein warehouseID SINGLE Warehouse ID of item. Nein shippingProfileID SINGLE The ID of the orders shipping profile (order property ID = 2). Nein methodOfPaymentID SINGLE The ID of the orders payment method (order property ID = 3). Nein tagIds MULTIPLEVALUE List of order tag IDs. Nein orderType SINGLE The ID of the order type. It is possible to define individual order types. Nein 1 marking1ID SINGLE The order flag / marking id (order property ID = 15) Nein shippingCosts SINGLE The order gross shipping costs amount. Nein estimatedTimeOfShipment SINGLE The estimated shipping date of this order (alias of order date type ID = 8). Nein createdOnDate SINGLE The date that the order was created on (alias of order date type ID = 2). Nein additionalOrderDates MAP Map of additional order dates to set(e.g. dateTypeId1=2023-11-03T21:42:46+01:00;dateTypeId2=2023-11-07T09:02:28+01:00;...). See https://developers.plentymarkets.com/en-gb/interface/stable7/Order.html#order_date_models for available date types. Nein referenceOrderID SINGLE The ID of the parent order relation reference Nein externalDeliveryNumber SINGLE The external delivery id of the order (order property ID = 49) Nein additionalOrderProperties MAP Map of additional order order properties as map (typeId=value). See https://developers.plentymarkets.com/en-gb/interface/stable7/Order.html#order_models_orderproperty for all available type ids Nein paymentTransactionID SINGLE Transaction Id of payment (payment property type = 1). Nein paymentReferenceID SINGLE Reference Id of payment (payment property type = 2). Nein paymentBookingText SINGLE Payment booking text (payment property type = 3). Nein paymentNameOfSender SINGLE Payment name of sender (payment property type = 11). Nein paymentCreateContactLink SINGLE If 'true', a link to the contact will be created for the payment (PaymentContactRelation). Nein billingCustomerFormOfAddress SINGLE The form of address of the billing address. Nein billingCustomerGender SINGLE The gender of the billing address. Nein billingCustomerCompany SINGLE The billing address company name (name1 field). Nein billingCustomerFirstName SINGLE The billing address first name (name2 field). Nein billingCustomerSurname SINGLE The billing address last name (name3 field). Nein billingCustomerAdditionalName SINGLE The billing address additional name (name4 field). Nein billingCustomerStreet SINGLE The billing address street (address1 field). Nein billingCustomerHouseNumber SINGLE The billing address house number (address2 field). Nein billingCustomerAdditionalAddress SINGLE The billing address additional (address3 field). Nein billingCustomerAddress4 SINGLE The billing address 4 field (currently undefined and can be freely used). Nein billingCustomerZip SINGLE The billing address postcode. Nein billingCustomerCity SINGLE The billing address town. Nein billingCustomerCountryID SINGLE The billing address country id. Nein billingCustomerEmail SINGLE The billing address email (option typeId = 5). Nein billingCustomerExternalAddressID SINGLE The billing address external ID (option typeId = 2). Nein billingCustomerExternalCustomerID SINGLE The billing address contact external ID (option typeId = 13). Nein billingCustomerTelephone SINGLE The billing address phone number (option typeId = 4). Nein billingCustomerLanguage SINGLE The billing address contact language. Nein billingDebitorAccount SINGLE The book account (debitor account) of the contact. An additional, separate number that generally corresponds to the customer number or the debtor number in your financial accounting. Nein billingCustomerPostNumber SINGLE The billing address postnumber (option typeId = 6). Nein billingCustomerPlentyID SINGLE The client (store ID) that is assigned to the contact. Nein billingCustomerContactPerson SINGLE The billing address contact person (option typeId = 12). Nein billingCustomerClass SINGLE The ID of the contact class. Nein billingCustomerVatID SINGLE The VAT ID of the contact. Nein billingCustomerPaymentDueWithin SINGLE The VAT ID of the contact. Nein billingCustomerValuta SINGLE The allowed number of days for the payment. Nein billingCustomerDiscountDays SINGLE The allowed number of days for the discount. Nein billingCustomerDiscountPercent SINGLE The early payment discount in percent. Nein deliveryCustomerGender SINGLE The gender of the shipping address. Nein deliveryCustomerCompany SINGLE The shipping address company name (name1 field). Nein deliveryCustomerFirstName SINGLE The shipping address first name (name2 field). Nein deliveryCustomerSurname SINGLE The shipping address last name (name3 field). Nein deliveryCustomerAdditionalName SINGLE The shipping address additional name (name4 field). Nein deliveryCustomerStreet SINGLE The shipping address street (address1 field). Nein deliveryCustomerHouseNumber SINGLE The shipping address house number (address2 field). Nein deliveryCustomerAdditionalAddress SINGLE The shipping address additional (address3 field). Nein deliveryCustomerAddress4 SINGLE The shipping address 4 field (currently undefined and can be freely used). Nein deliveryCustomerZip SINGLE The shipping address postcode. Nein deliveryCustomerCity SINGLE The shipping address town. Nein deliveryCustomerCountryID SINGLE The shipping address country id. Nein deliveryCustomerEmail SINGLE The shipping address email (option typeId = 5). Nein deliveryCustomerTelephone SINGLE The shipping address telephone number (option typeId = 4). Nein deliveryCustomerVatID SINGLE The VAT ID of the delivery address (option typeId = 1) Nein deliveryCustomerPostNumber SINGLE The shipping address postnumber (option typeId = 6). Nein infoUserID SINGLE User id of order comment. Nein info SINGLE The order comment text. Nein variantId SINGLE The ID of variation Ja quantity SINGLE The quantity Ja price SINGLE The original gross price without any surcharges or discounts. Nein priceNet SINGLE The original net price without any surcharges or discounts. Leave price field empty to use priceNet. Nein VAT SINGLE The vat amount, e.g. 19.0 Nein vatCountryId SINGLE The ID of the country vat Nein currency SINGLE The currency of the amounts. Nein itemText SINGLE The name of the order item. Ja itemRebate SINGLE The discount can be a percentage or a fixed value. Nein itemType SINGLE The ID of the order item type. Nein 1 isRebatePercentage SINGLE Flag that indicates if a discount is given as a percentage or as a fixed value. Nein true itemReturnStatus SINGLE Return Status of order item. Nein parentOrderItemId SINGLE The ID of the parent order item that is referred to Nein externalItemId SINGLE The external item id. Nein
folder	STRING	Der Ordner des Datenspeichers.	Nein
limit	STRING	Beschränkt die Anzahl der verarbeiteten Aufträge pro Ausführung.	Nein
sortByField	STRING	Optionales Feld zum Sortieren der Datensätze nach einem der indizierten Datastore Felder.	Nein	Keine (Standard) Identifier Identifier2 Identifier3 Tags Erstellungsdatum Aktualisierungsdatum Datum der letzten Inhaltsänderung Datum der Verarbeitung Folder
sortDir	STRING	Die Sortierreihenfolge (Aufsteigend oder Absteigend).	Nein	Aufsteigend Absteigend
addIncomingPayment	STRING	Option für die Zahlungn der Bestellung setzen. 'Keine Zahlungen erstellen' - Bestellung wird ohne Zahlung angelegt (Standard) | 'Vollständige Zahlung für alle Bestellungen' : Es wird eine vollständige Zahlung für alle Aufträge erstellt. | 'Nur wenn Spalte 'paymentTransactionID' gesetzt ist' : Es wird eine vollständige Zahlung angelegt, wenn paymentTransactionID in der Datenzeile des Auftragskopfs gesetzt ist. | 'Nur Zahlungs-ID mit Auftrag verknüpfen' : Es wird nur eine Verknüpfung zwischen einer Zahlung und einem Auftrag erstellt. Sie müssen eine gültige paymentID in der Kopfzeile setzen.	Nein	Keine Zahlungen erstellen Vollständige Zahlung für alle Bestellungen. Nur wenn Spalte 'paymentTransactionID' gesetzt ist Nur Zahlungs-ID mit Bestellung verknüpfen
identifierOrderId	STRING	Setzen Sie diese Option, um PlentyONE Order ID in das Feld identifier2 oder identifier3 des Datensatzes zu schreiben.	Nein	Deaktiviert identifier2 identifier3 Tags
enableExternalOrderIDCheck	BOOLEAN	Wenn die Option aktiviert ist, wird die Bestellung anhand der externalOrderID gesucht. Wenn die Bestellung bereits in PlentyONE vorhanden ist, wird sie nicht erneut angelegt.	Nein	Einschalten Deaktiviert
errorProcessingStatus	STRING	Der ausgewählte 'Processing Status' wird für fehlgeschlagene Aufträge (Datensätze im Master-Datastore) gesetzt. Ändern Sie diesen Wert nur, wenn Sie wissen, was Sie tun. Standard: PROCESSED_ERROR	Nein	PROCESSED_ERROR UNPROCESSED INPROCESS PROCESSED_MARK_DELETE PROCESSED_SUCCESS

Outputs

Das sind die Ergebnisse des Steps, die von nachfolgenden Steps, nach der Ausführung verwendet werden können.

Name	Datentyp	Beschreibung	Pflichtfeld	Werte
result	SPREADSHEET	Ein SPREADSHEET, dass die Ergebnisse des Auftragsimports enthält.	Ja
	Folgende Felder sind im Output enthalten: Feld Datentyp Beschreibung Pflichtfeld Standardwert identifier SINGLE The identifier column to import Spreadsheet into a Datastore. Nein orderID SINGLE Nein customerID SINGLE Nein customerAddressID SINGLE Nein deliveryAddressID SINGLE Nein paymentID SINGLE Nein remoteStatusMessage SINGLE Nein remoteStatusCode SINGLE Nein