stepPlentyONE Skip to content

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.

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:

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 SpaltenErläuterung
KundendatencustomerId (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.
LieferadressdatenDeliveryAddressId 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.
plentyIDDie 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

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#currencies
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.

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
nameSINGLEDatastore entity name, for internal use onlyNein
orderIDSINGLEThe OrderID created by PlentyONE after import of order (automatically filled)Nein
customerIDSINGLEID 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
customerAddressIDSINGLEID of Invoice Address. Leave empty to create a new address or fill with existing AddressID.Nein
deliveryAddressIDSINGLEID of Shipping Address. Leave empty to create a new address or fill with existing AddressID.Nein
paymentIDSINGLEID of Payment. Leave empty to create a new payment or fill with existing PaymentID.Nein
remoteStatusMessageSINGLEInternal API status field, leave emptyNein
remoteStatusCodeSINGLEInternal API status field, leave emptyNein
remotePaymentStatusSINGLEInternal API status field, leave emptyNein
plentyIDSINGLEThe plenty ID of the client that the order belongs toNein
ownerIDSINGLEThe user ID of the order's ownerNein
customerReferenceSINGLEThe customer sign of the order (order property ID = 8)Nein
referrerIDSINGLEThe referrer ID of the order.Nein
orderStatusSINGLEThe ID of the order status.Nein
externalOrderIDSINGLEThe external order ID of the order (order property ID = 7)Nein
externalCustomerIDSINGLEThe external ID of the contact.Nein
customerNumberSINGLEThe number of the contact.Nein
externalCustomerNumberSINGLEThis field is deprecated will be removed in future. Please use billingExternalAddressId insteadNein
warehouseIDSINGLEWarehouse ID of item.Nein
shippingProfileIDSINGLEThe ID of the orders shipping profile (order property ID = 2).Nein
methodOfPaymentIDSINGLEThe ID of the orders payment method (order property ID = 3).Nein
tagIdsMULTIPLEVALUEList of order tag IDs.Nein
orderTypeSINGLEThe ID of the order type. It is possible to define individual order types.Nein1
marking1IDSINGLEThe order flag / marking id (order property ID = 15)Nein
shippingCostsSINGLEThe order gross shipping costs amount.Nein
estimatedTimeOfShipmentSINGLEThe estimated shipping date of this order (alias of order date type ID = 8).Nein
createdOnDateSINGLEThe date that the order was created on (alias of order date type ID = 2).Nein
additionalOrderDatesMAPMap 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
referenceOrderIDSINGLEThe ID of the parent order relation referenceNein
externalDeliveryNumberSINGLEThe external delivery id of the order (order property ID = 49) Nein
additionalOrderPropertiesMAPMap 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 idsNein
paymentTransactionIDSINGLETransaction Id of payment (payment property type = 1).Nein
paymentReferenceIDSINGLEReference Id of payment (payment property type = 2).Nein
paymentBookingTextSINGLEPayment booking text (payment property type = 3).Nein
paymentNameOfSenderSINGLEPayment name of sender (payment property type = 11).Nein
paymentCreateContactLinkSINGLEIf 'true', a link to the contact will be created for the payment (PaymentContactRelation).Nein
billingCustomerFormOfAddressSINGLEThe form of address of the billing address.Nein
billingCustomerGenderSINGLEThe gender of the billing address.Nein
billingCustomerCompanySINGLEThe billing address company name (name1 field).Nein
billingCustomerFirstNameSINGLEThe billing address first name (name2 field).Nein
billingCustomerSurnameSINGLEThe billing address last name (name3 field).Nein
billingCustomerAdditionalNameSINGLEThe billing address additional name (name4 field).Nein
billingCustomerStreetSINGLEThe billing address street (address1 field).Nein
billingCustomerHouseNumberSINGLEThe billing address house number (address2 field).Nein
billingCustomerAdditionalAddressSINGLEThe billing address additional (address3 field).Nein
billingCustomerAddress4SINGLEThe billing address 4 field (currently undefined and can be freely used).Nein
billingCustomerZipSINGLEThe billing address postcode.Nein
billingCustomerCitySINGLEThe billing address town.Nein
billingCustomerCountryIDSINGLEThe billing address country id.Nein
billingCustomerEmailSINGLEThe billing address email (option typeId = 5).Nein
billingCustomerExternalAddressIDSINGLEThe billing address external ID (option typeId = 2).Nein
billingCustomerExternalCustomerIDSINGLEThe billing address contact external ID (option typeId = 13).Nein
billingCustomerTelephoneSINGLEThe billing address phone number (option typeId = 4).Nein
billingCustomerLanguageSINGLEThe billing address contact language.Nein
billingDebitorAccountSINGLEThe 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
billingCustomerPostNumberSINGLEThe billing address postnumber (option typeId = 6).Nein
billingCustomerPlentyIDSINGLEThe client (store ID) that is assigned to the contact.Nein
billingCustomerContactPersonSINGLEThe billing address contact person (option typeId = 12).Nein
billingCustomerClassSINGLEThe ID of the contact class.Nein
billingCustomerVatIDSINGLEThe VAT ID of the contact.Nein
billingCustomerPaymentDueWithinSINGLEThe VAT ID of the contact.Nein
billingCustomerValutaSINGLEThe allowed number of days for the payment.Nein
billingCustomerDiscountDaysSINGLEThe allowed number of days for the discount.Nein
billingCustomerDiscountPercentSINGLEThe early payment discount in percent.Nein
deliveryCustomerGenderSINGLEThe gender of the shipping address.Nein
deliveryCustomerCompanySINGLEThe shipping address company name (name1 field).Nein
deliveryCustomerFirstNameSINGLEThe shipping address first name (name2 field).Nein
deliveryCustomerSurnameSINGLEThe shipping address last name (name3 field).Nein
deliveryCustomerAdditionalNameSINGLEThe shipping address additional name (name4 field).Nein
deliveryCustomerStreetSINGLEThe shipping address street (address1 field).Nein
deliveryCustomerHouseNumberSINGLEThe shipping address house number (address2 field).Nein
deliveryCustomerAdditionalAddressSINGLEThe shipping address additional (address3 field).Nein
deliveryCustomerAddress4SINGLEThe shipping address 4 field (currently undefined and can be freely used).Nein
deliveryCustomerZipSINGLEThe shipping address postcode.Nein
deliveryCustomerCitySINGLEThe shipping address town.Nein
deliveryCustomerCountryIDSINGLEThe shipping address country id.Nein
deliveryCustomerEmailSINGLEThe shipping address email (option typeId = 5).Nein
deliveryCustomerTelephoneSINGLEThe shipping address telephone number (option typeId = 4).Nein
deliveryCustomerVatIDSINGLEThe VAT ID of the delivery address (option typeId = 1)Nein
deliveryCustomerPostNumberSINGLEThe shipping address postnumber (option typeId = 6).Nein
infoUserIDSINGLEUser id of order comment.Nein
infoSINGLEThe order comment text.Nein
variantIdSINGLEThe ID of variationJa
quantitySINGLEThe quantityJa
priceSINGLEThe original gross price without any surcharges or discounts.Nein
priceNetSINGLEThe original net price without any surcharges or discounts. Leave price field empty to use priceNet.Nein
VATSINGLEThe vat amount, e.g. 19.0Nein
vatCountryIdSINGLEThe ID of the country vatNein
currencySINGLEThe currency of the amounts.Nein
itemTextSINGLEThe name of the order item.Ja
itemRebateSINGLEThe discount can be a percentage or a fixed value.Nein
itemTypeSINGLEThe ID of the order item type.Nein1
isRebatePercentageSINGLEFlag that indicates if a discount is given as a percentage or as a fixed value.Neintrue
itemReturnStatusSINGLEReturn Status of order item.Nein
parentOrderItemIdSINGLEThe ID of the parent order item that is referred toNein
externalItemIdSINGLEThe 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
identifierSINGLEThe identifier column to import Spreadsheet into a Datastore.Nein
orderIDSINGLENein
customerIDSINGLENein
customerAddressIDSINGLENein
deliveryAddressIDSINGLENein
paymentIDSINGLENein
remoteStatusMessageSINGLENein
remoteStatusCodeSINGLENein